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

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

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:

# 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:

   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