Folder Structure

Folder Structure Reference

This reference provides the complete folder structure for MOFA architecture projects, including file placement rules and organization principles.

Single App Structure

For single applications, use this simplified structure:

lib/
├── main.dart                           # Application entry point
├── core/                               # Core features shared across the app
│   ├── auth/                           # Authentication feature
│   │   ├── services/
│   │   │   └── auth_service.dart
│   │   ├── models/
│   │   │   └── auth_state.dart
│   │   └── providers/
│   │       └── auth_providers.dart
│   ├── router/                         # Navigation and routing
│   │   ├── app_router.dart
│   │   ├── routes.dart
│   │   └── pages/
│   │       ├── login_page.dart
│   │       └── home_page.dart
│   ├── service_locators/               # Dependency injection
│   │   ├── client_providers.dart       # GraphQL/HTTP clients
│   │   ├── datasource_providers.dart   # Datasource instances
│   │   ├── repository_providers.dart   # Repository implementations
│   │   └── service_providers.dart      # Business logic services
│   └── config/                         # Configuration
│       ├── flavor_config.dart
│       └── app_config.dart
├── features/                           # Business features
│   └── [feature_name]/                 # Individual feature
│       ├── ui/                         # UI Layer
│       │   ├── screens/
│       │   │   └── [feature]_screen.dart
│       │   ├── widgets/
│       │   │   └── [feature]_widget.dart
│       │   └── notifiers/
│       │       └── [feature]_notifier.dart
│       ├── services/                   # Service Layer
│       │   ├── [feature]_service.dart
│       │   └── [feature]_orchestrator_service.dart
│       ├── domain/                     # Domain Layer
│       │   ├── models/
│       │   │   └── [feature]_model.dart
│       │   ├── inputs/
│       │   │   └── [feature]_inputs.dart
│       │   └── repositories/
│       │       └── i_[feature]_repository.dart
│       └── datasource/                 # Datasource Layer
│           ├── [feature]_datasource.dart
│           ├── [feature]_repository.dart
│           ├── [feature]_datasource_module.dart
│           ├── gql/
│           │   └── [feature]_operations.graphql
│           └── strategies/
│               ├── [feature]_request_strategies.dart
│               └── [feature]_cache_strategies.dart
├── services/                           # Cross-cutting services
│   ├── caching/
│   │   ├── secure_cache_service.dart
│   │   ├── simple_cache_service.dart
│   │   └── complex_cache_service.dart
│   ├── error_handling/
│   │   └── error_handling_service.dart
│   ├── logging/
│   │   └── logging_service.dart
│   └── analytics/
│       └── analytics_service.dart
└── packages/                           # Generic packages
    ├── i18n/
    │   ├── lib/
    │   │   ├── src/
    │   │   │   ├── services/
    │   │   │   └── extensions/
    │   │   └── i18n.dart
    │   └── pubspec.yaml
    └── assets/
        ├── lib/
        │   ├── src/
        │   │   ├── services/
        │   │   └── constants/
        │   └── assets.dart
        └── pubspec.yaml

Monorepo Structure

Monorepo Approach

For larger projects or multiple apps, use the monorepo structure with Pub Workspaces. This provides better separation of concerns and independent package development.

├── pubspec.yaml                        # Root workspace configuration
├── apps/
│   └── [app_name]/                     # Individual applications
│       ├── lib/
│       │   ├── main.dart
│       │   └── src/
│       │       ├── core/               # App-specific core
│       │       │   └── providers/
│       │       │       ├── datasource_providers.dart
│       │       │       └── service_providers.dart
│       │       └── features/
│       │           └── [feature]/
│       │               └── presentation/
│       │                   ├── screens/
│       │                   ├── widgets/
│       │                   └── notifiers/
│       └── pubspec.yaml
├── packages/
│   ├── domain/                         # Domain layer package
│   │   ├── lib/
│   │   │   ├── src/
│   │   │   │   ├── [feature]/
│   │   │   │   │   ├── models/
│   │   │   │   │   ├── inputs/
│   │   │   │   │   ├── filters/
│   │   │   │   │   ├── exceptions/
│   │   │   │   │   └── repositories/
│   │   │   │   └── shared/
│   │   │   └── domain.dart
│   │   └── pubspec.yaml
│   ├── services/                       # Service layer package
│   │   ├── lib/
│   │   │   ├── src/
│   │   │   │   ├── [feature]/
│   │   │   │   │   ├── [feature]_service.dart
│   │   │   │   │   └── [feature]_orchestrator.dart
│   │   │   │   └── shared/
│   │   │   │       ├── caching/
│   │   │   │       ├── error_handling/
│   │   │   │       └── logging/
│   │   │   └── services.dart
│   │   └── pubspec.yaml
│   ├── datasource/                     # Datasource layer package
│   │   ├── lib/
│   │   │   ├── src/
│   │   │   │   ├── core/
│   │   │   │   │   ├── remote/
│   │   │   │   │   │   └── gql/
│   │   │   │   │   │       ├── client/
│   │   │   │   │   │       └── schema/
│   │   │   │   │   └── local/
│   │   │   │   └── [feature]/
│   │   │   │       ├── remote/
│   │   │   │       │   ├── gql/
│   │   │   │       │   └── rest/
│   │   │   │       ├── repositories/
│   │   │   │       └── strategies/
│   │   │   └── datasource.dart
│   │   └── pubspec.yaml
│   ├── i18n/                           # Internationalization package
│   │   ├── lib/
│   │   │   ├── src/
│   │   │   │   ├── services/
│   │   │   │   ├── models/
│   │   │   │   └── extensions/
│   │   │   └── i18n.dart
│   │   └── pubspec.yaml
│   └── assets/                         # Assets management package
│       ├── lib/
│       │   ├── src/
│       │   │   ├── services/
│       │   │   └── constants/
│       │   └── assets.dart
│       └── pubspec.yaml
└── tools/                              # Development tools
    ├── build_runner/
    └── code_generation/

File Naming Conventions

Dart Files

• Models: [entity]_model.dart (e.g., user_model.dart)
• Services: [feature]_service.dart (e.g., user_service.dart)
• Orchestrators: [purpose]_orchestrator_service.dart (e.g., data_merge_orchestrator_service.dart)
• Repositories: [entity]_repository.dart (e.g., user_repository.dart)
• Repository Interfaces: i_[entity]_repository.dart (e.g., i_user_repository.dart)
• Datasources: [entity]_datasource.dart (e.g., user_datasource.dart)
• Notifiers: [feature]_notifier.dart (e.g., user_list_notifier.dart)
• Screens: [feature]_screen.dart (e.g., user_list_screen.dart)
• Widgets: [feature]_widget.dart (e.g., user_card_widget.dart)

GraphQL Files

• Operations: [entity]_operations.graphql (e.g., user_operations.graphql)
• Fragments: [entity]_fragments.graphql (e.g., user_fragments.graphql)

Test Files

• Unit Tests: [class_name]_test.dart (e.g., user_service_test.dart)
• Widget Tests: [widget_name]_test.dart (e.g., user_list_widget_test.dart)
• Integration Tests: [feature]_integration_test.dart

Directory Rules

Core Folder Rules

• Purpose: Contains features that need to be imported by other features
• Rule: If a feature needs to be imported by another feature, it belongs in core
• Components: Auth, Router, Service Locators, Configuration

Feature Folder Rules

• Independence: Features must not import other features directly
• Self-contained: Each feature contains all its layers (UI, Services, Domain, Datasource)
• Shared Logic: Extract shared logic to services or core modules

Package Rules

• Generic Packages: Must be business-logic independent
• Domain Package: Contains only pure models and interfaces
• Service Package: Contains all business logic
• Datasource Package: Contains only data access logic

Import Rules

Allowed Imports

// UI Layer
import 'package:domain/domain.dart';           // ✅ Domain models
import 'package:services/services.dart';       // ✅ Business logic
import '../core/auth/auth_service.dart';       // ✅ Core features
import 'package:i18n/i18n.dart';              // ✅ Generic packages

// Service Layer
import 'package:domain/domain.dart';           // ✅ Domain models
import 'package:datasource/repositories.dart'; // ✅ Repository implementations
import '../core/service_locators.dart';        // ✅ Service locators

// Domain Layer
// No imports from other layers                // ✅ Pure domain

// Datasource Layer
import 'package:domain/domain.dart';           // ✅ Domain interfaces only

Prohibited Imports

// UI Layer
import 'package:datasource/datasource.dart';   // ❌ Skip service layer

// Domain Layer
import 'package:services/services.dart';       // ❌ Domain depends on services
import 'package:datasource/datasource.dart';   // ❌ Domain depends on datasource

// Datasource Layer
import 'package:services/services.dart';       // ❌ Circular dependency

// Features
import '../other_feature/feature.dart';        // ❌ Feature-to-feature dependency

Test Organization

test/
├── unit/                               # Unit tests
│   ├── services/
│   ├── repositories/
│   └── domain/
├── widget/                             # Widget tests
│   ├── screens/
│   ├── components/
│   └── forms/
├── integration/                        # Integration tests
│   └── features/
└── helpers/                            # Test utilities
    ├── mocks/
    ├── fixtures/
    └── test_utils.dart

This folder structure ensures clear separation of concerns, maintainable code organization, and proper architectural boundaries in MOFA architecture projects.