ashishtrucksup/trucksup_flutter_monorepo

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.