retail/docs/PROJECT_STRUCTURE.md

# Retail POS - Flutter Project Structure

## Project Overview
Complete clean architecture implementation for a Flutter-based Point of Sale (POS) retail application.

## Architecture Pattern
**Clean Architecture with Feature-First Organization**

### Layers:
1. **Domain Layer** (Business Logic) - Pure Dart, no Flutter dependencies
2. **Data Layer** (Data Sources & Repositories) - Hive CE + Dio
3. **Presentation Layer** (UI & State Management) - Riverpod 3.0

---

## Complete File Structure

### Root Files
```
lib/
├── main.dart                 # App entry point with Hive & DI initialization
└── app.dart                  # Root widget with Riverpod, theme, and navigation
```

### Core Module (`lib/core/`)

#### Constants
```
core/constants/
├── api_constants.dart        # API URLs, endpoints, timeouts
├── app_constants.dart        # App config, defaults, business rules
├── ui_constants.dart         # Spacing, sizes, animations, grid config
└── storage_constants.dart    # Hive box names, type IDs, keys
```

#### Theme (Material 3)
```
core/theme/
├── app_theme.dart            # Light & dark theme configuration
├── colors.dart               # Material 3 color schemes
└── typography.dart           # Material 3 type scale
```

#### Network
```
core/network/
├── dio_client.dart           # Dio HTTP client with interceptors
├── api_interceptor.dart      # Request/response logging
└── network_info.dart         # Connectivity checker (connectivity_plus)
```

#### Errors
```
core/errors/
├── exceptions.dart           # Custom exceptions (Server, Cache, Network, etc.)
└── failures.dart             # Failure classes with Equatable
```

#### Utilities
```
core/utils/
├── formatters.dart           # Price, date, number formatting (intl)
├── validators.dart           # Input validation (email, price, quantity)
└── extensions.dart           # String, DateTime, double, List extensions
```

#### Widgets
```
core/widgets/
├── custom_button.dart        # Reusable button with loading states
├── loading_indicator.dart    # Loading spinner with message
├── error_widget.dart         # Error display with retry button
└── empty_state.dart          # Empty list placeholder
```

#### Dependency Injection
```
core/di/
└── service_locator.dart      # GetIt setup for DI
```

---

### Features Module (`lib/features/`)

## Feature 1: Products

### Domain Layer (Business Logic)
```
features/products/domain/
├── entities/
│   └── product.dart          # Product entity (Equatable)
├── repositories/
│   └── product_repository.dart  # Repository interface (abstract)
└── usecases/
    ├── get_all_products.dart    # Fetch all products use case
    └── search_products.dart     # Search products use case
```

### Data Layer (Data Access)
```
features/products/data/
├── models/
│   ├── product_model.dart       # Hive model with JSON serialization
│   └── product_model.g.dart     # Generated Hive adapter
├── datasources/
│   ├── product_local_datasource.dart   # Hive CE data source
│   └── product_remote_datasource.dart  # Dio API data source
└── repositories/
    └── product_repository_impl.dart    # Repository implementation
```

### Presentation Layer (UI & State)
```
features/products/presentation/
├── providers/
│   ├── products_provider.dart      # Riverpod provider
│   └── products_provider.g.dart    # Generated provider
├── pages/
│   └── products_page.dart          # Products grid page
└── widgets/
    ├── product_grid.dart           # Responsive grid view
    ├── product_card.dart           # Product card with image
    └── product_search_bar.dart     # Search input with debounce
```

---

## Feature 2: Categories

### Domain Layer
```
features/categories/domain/
├── entities/
│   └── category.dart          # Category entity
├── repositories/
│   └── category_repository.dart  # Repository interface
└── usecases/
    └── get_all_categories.dart   # Fetch categories use case
```

### Data Layer
```
features/categories/data/
├── models/
│   ├── category_model.dart       # Hive model
│   └── category_model.g.dart     # Generated adapter
├── datasources/
│   └── category_local_datasource.dart  # Hive data source
└── repositories/
    └── category_repository_impl.dart   # Repository implementation
```

### Presentation Layer
```
features/categories/presentation/
├── providers/
│   ├── categories_provider.dart    # Categories list provider
│   └── categories_provider.g.dart  # Generated
├── pages/
│   └── categories_page.dart        # Categories grid page
└── widgets/
    ├── category_grid.dart          # Grid view
    └── category_card.dart          # Category card with icon
```

---

## Feature 3: Home (POS/Cart)

### Domain Layer
```
features/home/domain/
├── entities/
│   └── cart_item.dart          # Cart item entity
├── repositories/
│   └── cart_repository.dart    # Cart repository interface
└── usecases/
    ├── add_to_cart.dart        # Add item use case
    ├── remove_from_cart.dart   # Remove item use case
    ├── clear_cart.dart         # Clear cart use case
    └── calculate_total.dart    # Calculate total use case
```

### Data Layer
```
features/home/data/
├── models/
│   ├── cart_item_model.dart    # Hive model
│   └── cart_item_model.g.dart  # Generated
├── datasources/
│   └── cart_local_datasource.dart  # Hive data source
└── repositories/
    └── cart_repository_impl.dart   # Repository implementation
```

### Presentation Layer
```
features/home/presentation/
├── providers/
│   ├── cart_provider.dart      # Cart state provider
│   └── cart_provider.g.dart    # Generated
├── pages/
│   └── home_page.dart          # POS main screen
└── widgets/
    ├── product_selector.dart   # Product picker
    ├── cart_summary.dart       # Cart display
    └── cart_item_card.dart     # Cart item row
```

---

## Feature 4: Settings

### Domain Layer
```
features/settings/domain/
├── entities/
│   └── app_settings.dart       # Settings entity
├── repositories/
│   └── settings_repository.dart  # Repository interface
└── usecases/
    ├── get_settings.dart       # Get settings use case
    └── update_settings.dart    # Update settings use case
```

### Data Layer
```
features/settings/data/
├── models/
│   ├── app_settings_model.dart  # Hive model
│   └── app_settings_model.g.dart # Generated
├── datasources/
│   └── settings_local_datasource.dart  # Hive data source
└── repositories/
    └── settings_repository_impl.dart   # Repository implementation
```

### Presentation Layer
```
features/settings/presentation/
├── providers/
│   ├── settings_provider.dart   # Settings provider
│   └── settings_provider.g.dart # Generated
└── pages/
    └── settings_page.dart       # Settings screen
```

---

### Shared Module (`lib/shared/`)

```
shared/widgets/
├── app_bottom_nav.dart       # Bottom navigation bar (4 tabs)
├── custom_app_bar.dart       # Reusable app bar
└── price_display.dart        # Formatted price widget
```

---

## Dependencies

### Production Dependencies
```yaml
dependencies:
  # Core Flutter
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.8

  # Local Database
  hive_ce: ^2.6.0
  hive_ce_flutter: ^2.1.0
  
  # State Management (Riverpod 3.0)
  flutter_riverpod: ^3.0.0
  riverpod_annotation: ^3.0.0
  
  # Network
  dio: ^5.7.0
  connectivity_plus: ^6.1.1
  
  # Image Caching
  cached_network_image: ^3.4.1
  
  # Utilities
  intl: ^0.20.1           # Formatting
  equatable: ^2.0.7       # Value equality
  dartz: ^0.10.1          # Functional programming (Either)
  path_provider: ^2.1.5   # File paths
  uuid: ^4.5.1            # ID generation
  
  # Dependency Injection
  get_it: ^8.0.4
```

### Dev Dependencies
```yaml
dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0
  
  # Code Generation
  build_runner: ^2.4.14
  hive_ce_generator: ^1.6.0
  riverpod_generator: ^3.0.0
  riverpod_lint: ^3.0.0
  custom_lint: ^0.8.0
```

---

## Code Generation Required

After creating the project, run:

```bash
# Generate Hive adapters and Riverpod providers
flutter pub get
dart run build_runner build --delete-conflicting-outputs
```

This will generate:
- `*.g.dart` files for Hive type adapters
- `*.g.dart` files for Riverpod providers

---

## Next Steps

1. **Run Code Generation**:
   ```bash
   flutter pub get
   dart run build_runner build --delete-conflicting-outputs
   ```

2. **Uncomment Hive Setup in main.dart**:
   - Register Hive adapters
   - Open Hive boxes

3. **Implement TODOs**:
   - Connect providers to repositories
   - Wire up dependency injection
   - Add navigation logic
   - Implement checkout flow

4. **Add Sample Data**:
   - Create seed data for products
   - Create seed data for categories
   - Test cart functionality

5. **Testing**:
   - Unit tests for use cases
   - Widget tests for UI components
   - Integration tests for flows

---

## Architecture Benefits

1. **Testability**: Each layer can be tested independently
2. **Maintainability**: Clear separation of concerns
3. **Scalability**: Easy to add new features
4. **Flexibility**: Can swap implementations (e.g., Hive → SQLite)
5. **Reusability**: Core utilities and widgets shared across features

---

## File Count Summary

- **Total Dart Files**: 139+
- **Core Files**: 25+
- **Feature Files**: 100+
- **Shared Files**: 3+
- **Generated Files**: Will be created by build_runner

---

## Key Design Patterns

1. **Repository Pattern**: Abstract data sources
2. **Use Case Pattern**: Single responsibility for business logic
3. **Provider Pattern**: Riverpod for state management
4. **Dependency Injection**: GetIt for service locator
5. **Clean Architecture**: Domain → Data → Presentation separation