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

> Architecture diagram of the GitHub repository hcm-nigeria-go-deep/health-campaign-field-worker-app, 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/hcm-nigeria-go-deep/health-campaign-field-worker-app
- Repository: https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app

## Overview

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.

Main entry points: [`apps/health_campaign_field_worker_app/lib/app.dart`](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/app.dart) (App Shell), [`packages/digit_data_model/lib/data_model.dart`](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/digit_data_model/lib/data_model.dart) (Data Model), [`packages/survey_form/lib/survey_form.dart`](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/survey_form/lib/survey_form.dart) (Survey Forms), [`apps/health_campaign_field_worker_app/lib/data/sync_registry.dart`](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/data/sync_registry.dart) (Sync Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Host App"]
  node_app_shell["App Shell<br/>Flutter host<br/>[app.dart]"]
  node_app_entry["Main Entry<br/>Flutter entrypoint<br/>[main.dart]"]
  node_app_router["Root Router<br/>navigation<br/>[app_router.dart]"]
  node_sync_registry["Sync Registry<br/>sync coordination<br/>[sync_registry.dart]"]
  node_sync_mapper["Sync Mapper<br/>sync mapping"]
  node_oplog_repo[("Op-log Repo<br/>offline log<br/>[oplog.dart]")]
  node_downsync_repo["Downsync Repo<br/>config fetch<br/>[downsync.dart]"]
  node_local_config_store[("Local Config<br/>offline config store<br/>[downsync.dart]")]
end

subgraph group_features["Feature Packages"]
  node_registration_delivery["Registration & Delivery<br/>feature module"]
  node_attendance_management["Attendance<br/>feature module"]
  node_inventory_management["Inventory<br/>feature module"]
  node_complaints["Complaints<br/>feature module<br/>[complaints.dart]"]
  node_referral_reconciliation["Referral Recon<br/>feature module"]
  node_survey_form["Survey Forms<br/>feature module<br/>[survey_form.dart]"]
  node_transit_post["Transit Post<br/>feature module<br/>[transit_post.dart]"]
  node_closed_household["Closed Household<br/>feature module"]
end

subgraph group_shared["Shared Foundation"]
  node_digit_data_model[("Data Model<br/>domain foundation<br/>[data_model.dart]")]
  node_sync_service["Sync Service<br/>sync engine"]
  node_digit_scanner["Scanner<br/>[digit_scanner.dart]"]
  node_digit_dss["Dashboard UI<br/>dashboard package<br/>[digit_dss.dart]"]
  node_digit_showcase["Showcase<br/>ui helper"]
  node_digit_firebase_services["Firebase Utils<br/>firebase support"]
  node_forms_engine["Forms Engine<br/>dynamic forms<br/>[forms_engine.dart]"]
end

subgraph group_tooling["Build Tooling"]
  node_tooling["Tools & Build<br/>developer tooling"]
end

node_app_entry -->|"starts"| node_app_shell
node_app_shell -->|"navigates"| node_app_router
node_app_shell -->|"orchestrates"| node_sync_registry
node_sync_registry -->|"maps"| node_sync_mapper
node_sync_mapper -->|"uses"| node_sync_service
node_oplog_repo -->|"feeds"| node_sync_registry
node_downsync_repo -->|"persists"| node_local_config_store
node_downsync_repo -->|"uses"| node_digit_data_model
node_registration_delivery -->|"uses"| node_digit_data_model
node_attendance_management -->|"uses"| node_digit_data_model
node_inventory_management -->|"uses"| node_digit_data_model
node_complaints -->|"uses"| node_digit_data_model
node_referral_reconciliation -->|"uses"| node_digit_data_model
node_survey_form -->|"renders"| node_forms_engine
node_survey_form -->|"uses"| node_digit_data_model
node_transit_post -->|"uses"| node_digit_data_model
node_closed_household -->|"uses"| node_digit_data_model
node_app_shell -->|"composes"| node_registration_delivery
node_app_shell -->|"composes"| node_attendance_management
node_app_shell -->|"composes"| node_inventory_management
node_app_shell -->|"composes"| node_complaints
node_app_shell -->|"composes"| node_referral_reconciliation
node_app_shell -->|"composes"| node_survey_form
node_app_shell -->|"composes"| node_transit_post
node_app_shell -->|"composes"| node_closed_household
node_app_shell -->|"integrates"| node_digit_scanner
node_app_shell -->|"integrates"| node_digit_dss
node_app_shell -->|"integrates"| node_digit_showcase
node_app_shell -->|"integrates"| node_digit_firebase_services
node_app_shell -.->|"built by"| node_tooling
node_sync_service -->|"syncs"| node_digit_data_model

click node_app_shell "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/app.dart"
click node_app_entry "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/main.dart"
click node_app_router "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/router/app_router.dart"
click node_sync_registry "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/data/sync_registry.dart"
click node_sync_mapper "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/data/sync_service_mapper.dart"
click node_oplog_repo "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/data/repositories/oplog.dart"
click node_downsync_repo "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/data/repositories/remote/downsync.dart"
click node_local_config_store "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/data/local_store/downsync/downsync.dart"
click node_registration_delivery "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/registration_delivery/lib/registration_delivery.dart"
click node_attendance_management "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/attendance_management/lib/attendance_management.dart"
click node_inventory_management "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/inventory_management/lib/inventory_management.dart"
click node_complaints "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/complaints/lib/complaints.dart"
click node_referral_reconciliation "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/referral_reconciliation/lib/referral_reconciliation.dart"
click node_survey_form "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/survey_form/lib/survey_form.dart"
click node_transit_post "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/transit_post/lib/transit_post.dart"
click node_closed_household "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/closed_household/lib/closed_household.dart"
click node_digit_data_model "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/digit_data_model/lib/data_model.dart"
click node_sync_service "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/sync_service/lib/sync_service_lib.dart"
click node_digit_scanner "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/digit_scanner/lib/digit_scanner.dart"
click node_digit_dss "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/digit_dss/lib/digit_dss.dart"
click node_digit_showcase "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/digit_showcase/lib/digit_showcase.dart"
click node_digit_firebase_services "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/digit_firebase_services/lib/digit_firebase_services.dart"
click node_forms_engine "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/forms_engine/lib/forms_engine.dart"
click node_tooling "https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/tools/run_build_runner.sh"

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_app_shell,node_app_entry,node_app_router,node_sync_registry,node_sync_mapper,node_oplog_repo,node_downsync_repo,node_local_config_store toneBlue
class node_registration_delivery,node_attendance_management,node_inventory_management,node_complaints,node_referral_reconciliation,node_survey_form,node_transit_post,node_closed_household toneAmber
class node_digit_data_model,node_sync_service,node_digit_scanner,node_digit_dss,node_digit_showcase,node_digit_firebase_services,node_forms_engine toneMint
class node_tooling toneRose
```

## Components

### Host App

Flutter shell for the field worker runtime

- [App Shell](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/app.dart): Flutter host · Bootstraps the app, wiring services, state, and feature composition · `apps/health_campaign_field_worker_app/lib/app.dart`
- [Main Entry](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/main.dart): Flutter entrypoint · Starts the runtime and selects the main driver · `apps/health_campaign_field_worker_app/lib/main.dart`
- [Root Router](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/router/app_router.dart): navigation · Composes package routers into the host navigation tree · `apps/health_campaign_field_worker_app/lib/router/app_router.dart`
- [Sync Registry](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/data/sync_registry.dart): sync coordination · Registers repositories and maps sync-up/sync-down flows · `apps/health_campaign_field_worker_app/lib/data/sync_registry.dart`
- [Sync Mapper](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/data/sync_service_mapper.dart): sync mapping · Bridges app repositories to the sync service contract · `apps/health_campaign_field_worker_app/lib/data/sync_service_mapper.dart`
- [Op-log Repo](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/data/repositories/oplog.dart): offline log · App-level operation log repository used by offline-first writes · `apps/health_campaign_field_worker_app/lib/data/repositories/oplog.dart`
- [Downsync Repo](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/data/repositories/remote/downsync.dart): config fetch · Pulls app configuration, roles, localization, and master data · `apps/health_campaign_field_worker_app/lib/data/repositories/remote/downsync.dart`
- [Local Config](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/apps/health_campaign_field_worker_app/lib/data/local_store/downsync/downsync.dart): offline config store · Persists configuration and localization state locally · `apps/health_campaign_field_worker_app/lib/data/local_store/downsync/downsync.dart`

### Feature Packages

Business workflows composed into the app

- [Registration & Delivery](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/registration_delivery/lib/registration_delivery.dart): feature module · Household registration, beneficiary delivery, referrals, and side effects · `packages/registration_delivery/lib/registration_delivery.dart`
- [Attendance](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/attendance_management/lib/attendance_management.dart): feature module · Register management and attendance marking workflow · `packages/attendance_management/lib/attendance_management.dart`
- [Inventory](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/inventory_management/lib/inventory_management.dart): feature module · Stock recording, reconciliation, and reports · `packages/inventory_management/lib/inventory_management.dart`
- [Complaints](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/complaints/lib/complaints.dart): feature module · Complaint registration and inbox management · `packages/complaints/lib/complaints.dart`
- [Referral Recon](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/referral_reconciliation/lib/referral_reconciliation.dart): feature module · Facility referral reconciliation and search workflow · `packages/referral_reconciliation/lib/referral_reconciliation.dart`
- [Survey Forms](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/survey_form/lib/survey_form.dart): feature module · Dynamic service and form capture flow · `packages/survey_form/lib/survey_form.dart`
- [Transit Post](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/transit_post/lib/transit_post.dart): feature module · Post-transit and post-delivery vaccination flow · `packages/transit_post/lib/transit_post.dart`
- [Closed Household](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/closed_household/lib/closed_household.dart): feature module · Closed-household handling and acknowledgement flow · `packages/closed_household/lib/closed_household.dart`

### Shared Foundation

Reusable domain, sync, scanner, dashboard, and Firebase support

- [Data Model](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/digit_data_model/lib/data_model.dart): domain foundation · Common entities, repositories, and SQL/no-sql persistence abstractions · `packages/digit_data_model/lib/data_model.dart`
- [Sync Service](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/sync_service/lib/sync_service_lib.dart): sync engine · Bidirectional sync-up and sync-down orchestration · `packages/sync_service/lib/sync_service_lib.dart`
- [Scanner](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/digit_scanner/lib/digit_scanner.dart): scanner package · QR/barcode scanner UI and detection logic · `packages/digit_scanner/lib/digit_scanner.dart`
- [Dashboard UI](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/digit_dss/lib/digit_dss.dart): dashboard package · Dashboard rendering and analytics views · `packages/digit_dss/lib/digit_dss.dart`
- [Showcase](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/digit_showcase/lib/digit_showcase.dart): ui helper · Guided overlays and in-app help surfaces · `packages/digit_showcase/lib/digit_showcase.dart`
- [Firebase Utils](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/digit_firebase_services/lib/digit_firebase_services.dart): firebase support · Firebase helpers and crash tooling used by the host app · `packages/digit_firebase_services/lib/digit_firebase_services.dart`
- [Forms Engine](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/packages/forms_engine/lib/forms_engine.dart): dynamic forms · JSON schema-based form rendering and builders · `packages/forms_engine/lib/forms_engine.dart`

### Build Tooling

Generation and automation used across the monorepo

- [Tools & Build](https://github.com/hcm-nigeria-go-deep/health-campaign-field-worker-app/blob/master/tools/run_build_runner.sh): developer tooling · Melos, code generation, scripts, and CI automation · `tools/run_build_runner.sh`

## Connections

- Main Entry → App Shell: starts · Entrypoint hands off to the application shell
- App Shell → Root Router: navigates · Shell composes the root navigation graph
- App Shell → Sync Registry: orchestrates · Shell wires the sync boundary into runtime state
- Sync Registry → Sync Mapper: maps · Registry delegates repository-to-sync mapping
- Sync Mapper → Sync Service: uses · App-level mapping targets the shared sync engine
- Op-log Repo → Sync Registry: feeds · Operation log entries become sync work items
- Downsync Repo → Local Config: persists · Configuration fetches are stored locally for offline use
- Downsync Repo → Data Model: uses · Downsync payloads are normalized through shared entities
- Registration & Delivery → Data Model: uses · Feature repositories share common domain and storage abstractions
- Attendance → Data Model: uses · Attendance data is modeled through shared persistence primitives
- Inventory → Data Model: uses · Inventory records rely on the common data model layer
- Complaints → Data Model: uses · Complaint flows adapt the shared entity/repository layer
- Referral Recon → Data Model: uses · Referral data is built on the shared domain model
- Survey Forms → Forms Engine: renders · Survey package uses the dynamic form renderer
- Survey Forms → Data Model: uses · Form-driven records persist through shared model abstractions
- Transit Post → Data Model: uses · Transit/post-delivery records use the shared storage model
- Closed Household → Data Model: uses · Closed-household state is backed by shared domain entities
- App Shell → Registration & Delivery: composes · Host app includes the core campaign workflows
- App Shell → Attendance: composes · Host app includes the attendance module
- App Shell → Inventory: composes · Host app includes the inventory module
- App Shell → Complaints: composes · Host app includes the complaints module
- App Shell → Referral Recon: composes · Host app includes referral reconciliation
- App Shell → Survey Forms: composes · Host app includes survey form workflows
- App Shell → Transit Post: composes · Host app includes post-transit workflows
- App Shell → Closed Household: composes · Host app includes closed-household workflows
- App Shell → Scanner: integrates · Shell exposes scanner capability to features
- App Shell → Dashboard UI: integrates · Shell surfaces dashboards and reports
- App Shell → Showcase: integrates · Shell enables guided overlays and help UI
- App Shell → Firebase Utils: integrates · Shell uses Firebase-related utilities and hooks
- App Shell → Tools & Build: built by · Architecture is supported by code generation and CI tooling
- Sync Service → Data Model: syncs · Sync engine operates over the shared offline data layer