# ashishtrucksup/trucksup_flutter_monorepo architecture

> Architecture diagram of the GitHub repository ashishtrucksup/trucksup_flutter_monorepo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashishtrucksup/trucksup_flutter_monorepo
- Repository: https://github.com/ashishtrucksup/trucksup_flutter_monorepo

## Overview

1. **Repository shape**
   - This is a **Flutter monorepo/workspace**, not a single app project.
   - The workspace is split into:
     - `apps/Trucksup` for the runnable mobile app
     - `packages/core` for cross-cutting infrastructure and shared primitives
     - `packages/shared` for shared domain abstractions
     - `packages/features/*` for independently packaged features
     - `bricks/*` for code generation templates

2. **Top-level dependency boundary**
   - The architecture is centered on a **modular clean-architecture style**.
   - The app shell depends on reusable packages, while feature packages are meant to stay isolated from each other.
   - `packages/core` is the main platform layer; `packages/features/splash` is an example vertical feature module.

3. **App shell responsibilities**
   - `apps/Trucksup/lib/main.dart` and `bootstrap.dart` are the entry points for runtime startup.
   - `app.dart` wires the Flutter app together.
   - `app/config`, `app/di`, and `app/router` define the shell-level composition:
     - environment/flavor selection
     - dependency injection
     - route configuration
     - navigator observation

4. **Environment and flavor system**
   - The app supports **dev, staging, and prod** flavors.
   - Flavor selection is driven by `--dart-define=FLAVOR=...`.
   - Flavor-specific configuration lives in `lib/app/config/flavor/src/env/*`.
   - This configuration layer likely feeds startup values into the core services and API endpoints, making environment choice a first-class architectural concern.

5. **Core package as platform layer**
   - `packages/core` is the shared platform package and is intentionally split into public API and internal implementation:
     - `core_api` exposes contracts and interfaces
     - `src/core_*` contains the actual implementations
   - This separation suggests other packages should depend on abstractions, not concrete internals.

6. **Core data subsystem**
   - `core_data` contains the infrastructure for app data access:
     - network client and HTTP configuration
     - interceptors for auth, logging, error handling, retry
     - cache and memory cache management
     - local storage services and local user repository
     - background sync, retry policy, and sync queue
   - This is the boundary where remote API calls, local persistence, and offline/retry behavior converge.

7. **Core domain subsystem**
   - `core_domain` provides reusable business-side primitives:
     - failure types such as network, cache, validation, unauthorized
     - result/either abstractions for success/failure handling
     - base use case classes and pagination helpers
     - common validators
   - This layer keeps business logic independent from Flutter, network, or storage details.

8. **Core services subsystem**
   - `core_services` contains app-wide capabilities that are not feature-specific:
     - analytics and Firebase analytics integration
     - crash reporting via Crashlytics
     - remote feature flags
     - logging and debug overlays
     - notifications and push handling
     - permissions
     - payment gateway abstractions and Razorpay integration
     - authentication/session service
     - webview bridge/service
   - These services are consumed by the app shell and features through shared contracts.

9. **Core UI and utility subsystem**
   - `core_ui` packages global UI concerns:
     - themes, typography, color palette
     - responsive layouts and spacing
     - localization and language control
     - framework-level progress/loading UI
   - `core_utils` provides shared constants, regex patterns, enums, extensions, formatting helpers, debounce/throttle/retry utilities, and default Firebase options.
   - These packages support consistency across all features and reduce duplication.

10. **Shared package**
   - `packages/shared` holds domain concepts that cross feature boundaries.
   - The current tree shows user-domain localization and a shared domain entrypoint.
   - This package likely acts as a neutral place for models or abstractions needed by multiple feature modules without pulling in feature-specific code.

11. **Feature module pattern**
   - `packages/features/splash` demonstrates the feature-package structure:
     - API layer: `splash_api`
     - data/state model: `splash_state.dart`
     - presentation: bindings, controller, screen, widget
   - The presence of bindings and controllers indicates **GetX-based** feature composition and state management.
   - Each feature is expected to own its UI, state, and feature-specific logic while relying on core/shared packages for shared capabilities.

12. **Startup data flow**
   - Typical runtime flow is:
     1. App starts in Flutter entrypoint.
     2. Bootstrap chooses flavor/configuration.
     3. Dependency injection registers core services and feature dependencies.
     4. Router resolves the initial route.
     5. Feature modules render UI and call into core data/services as needed.
   - This makes startup composition centralized, while feature execution remains modular.

13. **Routing and navigation**
   - Routing is centralized in `app/router`.
   - The repository includes a custom navigator observer, suggesting navigation events are monitored for analytics, logging, or debugging.
   - Features likely expose route contracts through their API packages rather than hard-coding navigation dependencies.

14. **Platform-specific native layer**
   - `apps/Trucksup/android` and `apps/Trucksup/ios` are standard Flutter host projects.
   - Firebase is already configured on both platforms via `google-services.json` and `GoogleService-Info.plist`.
   - The native layer mainly serves as the platform bootstrap for Flutter and Firebase, not as a separate business logic layer.

15. **Code generation and repo tooling**
   - `Melos` orchestrates the monorepo, and `Mason` generates feature/core boilerplate from bricks.
   - The `bricks/core_module` and `bricks/feature_module` templates mirror the workspace structure, which is important for keeping package boundaries consistent as the repo grows.

Main entry points: [`pubspec.yaml`](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/pubspec.yaml) (Monorepo), [`apps/Trucksup/lib/main.dart`](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/main.dart) (Bootstrap), [`apps/Trucksup/lib/app/di/service_injection.dart`](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/app/di/service_injection.dart) (DI), [`packages/core/lib/core_api/core_api.dart`](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/core_api/core_api.dart) (Core API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_monorepo["Monorepo<br/>flutter-workspace<br/>[pubspec.yaml]"]
  node_android_host["Android Host<br/>native-host"]
  node_ios_host["iOS Host<br/>native-host"]
end

subgraph group_app["App Shell"]
  node_app_entry["Bootstrap<br/>runtime-entry<br/>[main.dart]"]
  node_app_shell["App Shell<br/>flutter-composition<br/>[app.dart]"]
  node_app_config["Config<br/>[app_config.dart]"]
  node_flavor_service["Flavors<br/>env-selection"]
  node_di["DI<br/>composition-root"]
  node_router["Router<br/>navigation-core<br/>[app_router.dart]"]
end

subgraph group_core["Core Platform"]
  node_core_api["Core API<br/>contracts<br/>[core_api.dart]"]
  node_core_data[("Data Layer<br/>platform-data<br/>[core_data.dart]")]
  node_core_domain{{"Domain Primitives<br/>business-core<br/>[core_domain.dart]"}}
  node_core_services["Services<br/>[core_services.dart]"]
  node_core_ui["Core UI<br/>ui-system<br/>[core_ui.dart]"]
  node_core_utils["Utils<br/>shared-helpers<br/>[core_utils.dart]"]
end

subgraph group_features["Feature Modules"]
  node_splash_api["Splash API<br/>feature-contracts<br/>[splash_api.dart]"]
  node_splash_state["Splash State<br/>feature-state<br/>[splash_state.dart]"]
  node_splash_presentation["Splash UI<br/>feature-presentation<br/>[splash_screen.dart]"]
end

subgraph group_shared["Shared Domain"]
  node_shared_domain["Shared Domain<br/>cross-feature-domain<br/>[shared_domain.dart]"]
end

subgraph group_tooling["Tooling"]
  node_melos["Melos<br/>workspace-orchestrator<br/>[mason.yaml]"]
  node_mason_bricks["Bricks<br/>code-templates"]
end

node_monorepo -->|"orchestrates"| node_melos
node_monorepo -.->|"scaffolds"| node_mason_bricks
node_monorepo -->|"contains"| node_app_entry
node_monorepo -->|"contains"| node_core_api
node_monorepo -->|"contains"| node_shared_domain
node_monorepo -->|"contains"| node_splash_api
node_monorepo -.->|"hosts"| node_android_host
node_monorepo -.->|"hosts"| node_ios_host
node_app_entry -->|"bootstraps"| node_app_config
node_app_entry -->|"initializes"| node_di
node_app_entry -->|"starts"| node_router
node_app_entry -->|"launches"| node_app_shell
node_app_config -->|"selects"| node_flavor_service
node_app_shell -->|"uses"| node_core_ui
node_app_shell -->|"consumes"| node_core_services
node_di -->|"binds"| node_core_api
node_di -->|"registers"| node_core_services
node_di -->|"registers"| node_core_data
node_router -->|"routes"| node_splash_api
node_splash_api -->|"drives"| node_splash_presentation
node_splash_presentation -->|"models"| node_splash_state
node_core_api -->|"depends on"| node_core_domain
node_core_data -->|"returns"| node_core_domain
node_core_services -->|"implements"| node_core_api
node_core_ui -->|"reuses"| node_core_utils
node_shared_domain -.->|"aligns with"| node_core_domain

click node_monorepo "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/pubspec.yaml"
click node_melos "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/mason.yaml"
click node_mason_bricks "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/tree/main/bricks"
click node_app_entry "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/main.dart"
click node_app_shell "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/app/app.dart"
click node_app_config "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/app/config/app_config.dart"
click node_flavor_service "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/app/config/flavor/src/flavor_config_service.dart"
click node_di "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/app/di/service_injection.dart"
click node_router "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/app/router/app_router.dart"
click node_core_api "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/core_api/core_api.dart"
click node_core_data "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/src/core_data/core_data.dart"
click node_core_domain "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/src/core_domain/core_domain.dart"
click node_core_services "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/src/core_services/core_services.dart"
click node_core_ui "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/src/core_ui/core_ui.dart"
click node_core_utils "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/src/core_utils/core_utils.dart"
click node_shared_domain "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/shared/lib/shared_domain.dart"
click node_splash_api "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/features/splash/lib/splash_api/splash_api.dart"
click node_splash_state "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/features/splash/lib/src/data/state_model/splash_state.dart"
click node_splash_presentation "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/features/splash/lib/src/presentation/views/splash_screen.dart"
click node_android_host "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/tree/main/apps/Trucksup/android"
click node_ios_host "https://github.com/ashishtrucksup/trucksup_flutter_monorepo/tree/main/apps/Trucksup/ios"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_monorepo,node_android_host,node_ios_host toneBlue
class node_app_entry,node_app_shell,node_app_config,node_flavor_service,node_di,node_router toneAmber
class node_core_api,node_core_data,node_core_domain,node_core_services,node_core_ui,node_core_utils toneMint
class node_splash_api,node_splash_state,node_splash_presentation toneRose
class node_shared_domain toneIndigo
class node_melos,node_mason_bricks toneTeal
```

## Components

### Workspace

Monorepo root and orchestration

- [Monorepo](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/pubspec.yaml): flutter-workspace · Melos-managed Flutter monorepo root · `pubspec.yaml`
- [Android Host](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/tree/main/apps/Trucksup/android): native-host · Android Flutter shell and Firebase config · `apps/Trucksup/android`
- [iOS Host](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/tree/main/apps/Trucksup/ios): native-host · iOS Flutter shell and Firebase config · `apps/Trucksup/ios`

### App Shell

Runnable Flutter application composition

- [Bootstrap](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/main.dart): runtime-entry · Flutter startup and bootstrapping entrypoints · `apps/Trucksup/lib/main.dart`
- [App Shell](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/app/app.dart): flutter-composition · Top-level app widget wiring · `apps/Trucksup/lib/app/app.dart`
- [Config](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/app/config/app_config.dart): shell-config · App-level configuration and flavor plumbing · `apps/Trucksup/lib/app/config/app_config.dart`
- [Flavors](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/app/config/flavor/src/flavor_config_service.dart): env-selection · Dev, staging, and prod flavor resolution · `apps/Trucksup/lib/app/config/flavor/src/flavor_config_service.dart`
- [DI](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/app/di/service_injection.dart): composition-root · Registers app and feature dependencies · `apps/Trucksup/lib/app/di/service_injection.dart`
- [Router](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/apps/Trucksup/lib/app/router/app_router.dart): navigation-core · Central route map and navigation observation · `apps/Trucksup/lib/app/router/app_router.dart`

### Core Platform

Shared platform layer split into API and implementations

- [Core API](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/core_api/core_api.dart): contracts · Public contracts and interfaces for other packages · `packages/core/lib/core_api/core_api.dart`
- [Data Layer](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/src/core_data/core_data.dart): platform-data · Network, cache, storage, and sync infrastructure · `packages/core/lib/src/core_data/core_data.dart`
- [Domain Primitives](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/src/core_domain/core_domain.dart): business-core · Failures, results, use cases, and validators · `packages/core/lib/src/core_domain/core_domain.dart`
- [Services](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/src/core_services/core_services.dart): app-services · Analytics, crashlytics, flags, notifications, payments, auth, webview · `packages/core/lib/src/core_services/core_services.dart`
- [Core UI](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/src/core_ui/core_ui.dart): ui-system · Themes, layouts, localization, and framework UI helpers · `packages/core/lib/src/core_ui/core_ui.dart`
- [Utils](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/core/lib/src/core_utils/core_utils.dart): shared-helpers · Constants, extensions, formatters, and helper utilities · `packages/core/lib/src/core_utils/core_utils.dart`

### Feature Modules

Independently packaged feature areas

- [Splash API](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/features/splash/lib/splash_api/splash_api.dart): feature-contracts · Public route contract for the splash feature · `packages/features/splash/lib/splash_api/splash_api.dart`
- [Splash State](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/features/splash/lib/src/data/state_model/splash_state.dart): feature-state · Splash feature state model · `packages/features/splash/lib/src/data/state_model/splash_state.dart`
- [Splash UI](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/features/splash/lib/src/presentation/views/splash_screen.dart): feature-presentation · Bindings, controller, screen, and widget composition · `packages/features/splash/lib/src/presentation/views/splash_screen.dart`

### Shared Domain

Cross-feature domain abstractions

- [Shared Domain](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/packages/shared/lib/shared_domain.dart): cross-feature-domain · Shared user-domain abstractions and localization · `packages/shared/lib/shared_domain.dart`

### Tooling

Monorepo and template generation

- [Melos](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/blob/main/mason.yaml): workspace-orchestrator · Coordinates packages and app workspace tasks · `mason.yaml`
- [Bricks](https://github.com/ashishtrucksup/trucksup_flutter_monorepo/tree/main/bricks): code-templates · Boilerplate templates for core and feature modules · `bricks`

## Connections

- Monorepo → Melos: orchestrates · Workspace tasks are coordinated through Melos
- Monorepo → Bricks: scaffolds · Code generation templates mirror the package structure
- Monorepo → Bootstrap: contains · The runnable app lives in the Trucksup workspace app
- Monorepo → Core API: contains · Core platform package is part of the monorepo
- Monorepo → Shared Domain: contains · Shared abstractions are packaged separately
- Monorepo → Splash API: contains · Feature packages are independently published modules
- Monorepo → Android Host: hosts · Native platform shells support Flutter runtime startup
- Monorepo → iOS Host: hosts · Native platform shells support Flutter runtime startup
- Bootstrap → Config: bootstraps · Startup selects environment and app configuration
- Bootstrap → DI: initializes · Bootstrap wires dependency injection before UI starts
- Bootstrap → Router: starts · Initial navigation is resolved through the router
- Bootstrap → App Shell: launches · Entry points hand off into the app widget tree
- Config → Flavors: selects · Flavor service resolves dev, staging, and prod config
- App Shell → Core UI: uses · Global theming, localization, and layout utilities power the shell
- App Shell → Services: consumes · Shell-level capabilities like analytics and notifications are injected
- DI → Core API: binds · Dependency injection prefers public contracts
- DI → Services: registers · App-wide services are assembled in the composition root
- DI → Data Layer: registers · Data infrastructure is wired into runtime services
- Router → Splash API: routes · Feature route contracts are resolved centrally
- Splash API → Splash UI: drives · Feature contract connects to the feature UI flow
- Splash UI → Splash State: models · Presentation state stays local to the feature
- Core API → Domain Primitives: depends on · Contracts build on shared domain primitives
- Data Layer → Domain Primitives: returns · Repositories and network operations surface domain failures and results
- Services → Core API: implements · Services satisfy shared interfaces and contracts
- Core UI → Utils: reuses · UI layer consumes shared constants and helpers
- Shared Domain → Domain Primitives: aligns with · Shared domain concepts remain compatible with core result and failure types