hcm-nigeria-go-deep/health-campaign-field-worker-app

1. This repository is a Flutter monorepo for the DIGIT Health Campaign Management field worker app. It contains one host application under apps/health_campaign_field_worker_app and many reusable feature packages under packages/, wired together with Melos and code generation.

2. The host app is primarily an orchestration shell. It bootstraps Flutter/Firebase, configures routing, localization, background services, notifications, network state, and then composes feature modules into a single runtime experience.

3. The codebase is built around feature packages rather than one large app. Each package is self-contained and usually follows the same internal structure: blocs for state, pages for screens, router for nested navigation, data for repositories, models for entities, widgets for reusable UI, and utils for feature-specific constants/helpers.

4. The main feature packages map to business capabilities: registration and delivery, attendance, inventory, complaints, referral reconciliation, survey forms, scan/QR support, dashboarding, closed household handling, and post-transit/post-delivery flows. The README’s role-based access model reflects this modular design: different roles surface different packages and workflows.

5. Shared domain and persistence infrastructure lives in foundational packages like digit_data_model, sync_service, digit_scanner, digit_dss, digit_showcase, and digit_firebase_services. These provide the common entity model, sync engine, scanner UI/logic, dashboard rendering, guided UI overlays, and Firebase-related utilities used by the feature packages and app.

6. Data access follows a repository pattern split into local and remote sides. Local repositories persist offline state and query models; remote repositories encapsulate server APIs. The data_model/digit_data_model layer provides common entity/search model abstractions, while package-specific repositories adapt those abstractions to each module’s domain.

7. Offline-first is the central data-flow boundary. User actions go to the feature UI and bloc, then into local repositories, which write to SQLite and/or ISAR-backed stores and create operation-log entries. Those op-log entries are later consumed by sync logic to reconcile local and remote state.

8. Sync is bidirectional and handled by a dedicated sync subsystem. The sync_service package and app-level sync registry/mapper code coordinate sync-down and sync-up across registered repositories, using the op-log to group pending operations and push or fetch changes in batches. This is the key boundary between “device truth” and “server truth.”

9. The app also has a configuration/data-downsync path for MDMS, localization, role access, project setup, and boundary/project-specific records. The README and tree show dedicated repositories for auth, localization, bandwidth checks, project downsync, and MDMS-driven configuration, which means many screens are populated from server-side configuration rather than hardcoded UI.

10. Navigation is modular and generated. The host app’s root router integrates package routers, while each package has its own router and generated route map. This keeps feature flows isolated but still composable into a single app shell.

11. Cross-cutting UI infrastructure includes localization delegates, shared headers, progress indicators, no-result/error screens, showcase/help overlays, and network manager wrappers. These are used across packages to keep a consistent UX while allowing each feature package to remain independent.

12. Native platform code is minimal but important: Android and iOS folders contain standard Flutter runners plus platform hooks such as location service support and Firebase config. That indicates the app relies on native capabilities mainly for device integration, not for business logic.

13. Build and developer tooling are a visible part of the architecture. Generated Dart artifacts (freezed, dart_mappable, router code, and schema code) are produced through build_runner; custom scripts under tools/ generate package imports, APK builds, localization conversions, and cleanup; GitHub Actions automate build and quality workflows.

14. For an architecture diagram, the most important diagram boundaries are: host app shell, feature packages, shared platform packages, local offline stores, remote backend services, and the sync/op-log pipeline connecting local and remote data. The data flow is predominantly UI → bloc → repository → local store/op-log → sync engine → remote API, with sync-down feeding configuration and master data back into local stores.