flutter-scaffold

When to Use

• Creating a new feature/domain from scratch (e.g., auth, booking, pet)
• Adding layers to an existing feature
• Reviewing or refactoring app structure
• Onboarding someone to the mobile architecture

Architecture Principles

| Principle | Rule | |-----------|------| | Screaming Architecture | Directory names = business domains, NOT technical concerns | | Clean Architecture | Dependencies point INWARD: infrastructure → application → domain | | Ports & Adapters | Domain defines interfaces, infrastructure implements them | | Feature-first | Each feature is self-contained with all 4 layers | | Shared is shared | Only truly cross-feature code goes in shared/ |

Dependency Rule (CRITICAL)

Presentation  → can import → Application, Domain
Application   → can import → Domain ONLY
Domain        → imports NOTHING (pure Dart)
Infrastructure → implements → Domain interfaces

Domain layer has ZERO dependencies on Flutter, Firebase, or any external package. Pure Dart only.

Feature Structure

Every feature follows this exact structure:

features/{feature}/
  domain/
    entities/                # Business objects
      {entity}.dart
    repositories/            # Abstract interfaces (ports)
      {feature}_repository.dart
    value_objects/            # Immutable typed values
      {value_object}.dart
  application/
    use_cases/               # One class per use case
      {verb}_{noun}_use_case.dart
  presentation/
    providers/               # Riverpod providers
      {feature}_providers.dart
    pages/                   # Full-screen widgets (Atomic: pages level)
      {feature}_{action}_page.dart
    widgets/                 # Feature-specific widgets
      {descriptive_name}.dart
  infrastructure/
    datasources/             # External data access
      {source}_{feature}_datasource.dart
    repositories/            # Concrete implementations (adapters)
      {feature}_repository_impl.dart
    models/                  # DTOs / API response models
      {entity}_model.dart

Naming Conventions

| Element | Pattern | Example | |---------|---------|---------| | Feature dir | singular noun | features/booking/ | | Entity | singular PascalCase | Booking, Pet, User | | Repository interface | {Feature}Repository | AuthRepository | | Repository impl | {Feature}RepositoryImpl | AuthRepositoryImpl | | Use case | {Verb}{Noun}UseCase | LoginUseCase, CreateBookingUseCase | | Page | {Feature}{Action}Page | LoginPage, BookingDetailPage | | Provider | {feature}{Purpose}Provider | authStateProvider, bookingListProvider | | Datasource | {Source}{Feature}Datasource | FirebaseAuthDatasource | | Model (DTO) | {Entity}Model | UserModel, BookingModel |

Adding a New Feature

1. Create directory: lib/features/{feature}/
2. Create all 4 layers: domain/, application/, presentation/, infrastructure/
3. Define entities in domain/entities/
4. Define repository interface in domain/repositories/
5. Implement use cases in application/use_cases/
6. Create Riverpod providers in presentation/providers/
7. Build pages and widgets in presentation/pages/ and presentation/widgets/
8. Implement repository in infrastructure/repositories/
9. Register providers in app/di/providers.dart if global

Commands

# Create a new feature scaffold
mkdir -p lib/features/{feature}/{domain/{entities,repositories,value_objects},application/use_cases,presentation/{providers,pages,widgets},infrastructure/{datasources,repositories,models}}

# Verify structure
find lib/features/{feature} -type d | sort

Anti-Patterns

| ❌ Don't | ✅ Do | |----------|-------| | lib/screens/login_screen.dart | lib/features/auth/presentation/pages/login_page.dart | | lib/models/user.dart (global) | lib/features/auth/domain/entities/user.dart | | Import Firebase in domain | Define interface in domain, implement in infrastructure | | lib/utils/ grab bag | Put in the feature or shared/ where it belongs | | Business logic in widgets | Widgets call providers, providers call use cases | | One massive providers.dart | One provider file per feature, global DI in app/di/ | | Domain entities with toJson | DTOs in infrastructure/models handle serialization |