Skip to content

Architecture Overview

iCapture v3 is a React and JavaScript web application for DHIS2 data-capture workflows. It combines a reusable core application with project extensions, so that shared capabilities can evolve consistently while individual projects implement their own forms, workflows, and configuration.

This page describes the system context, application layers, and main extension points. It is intended for developers, architects, technical leads, and external partner teams implementing new modules.

System context

The application runs in a user's browser and connects to DHIS2 through supported Web API endpoints. At application start, it loads the user context and the metadata needed for the current implementation. Feature modules then use this metadata to provide the relevant dataset, event, or tracker workflow.

flowchart TB
    User["Users<br/>(Data entry and review)"] --> Browser["Browser<br/>(iCapture v3 web application)"]

    subgraph App["iCapture v3 application"]
        Extension["Project extension<br/>(Custom forms, rules, configuration, branding)"]
        Core["iCapture v3 core<br/>(Shared features, navigation, API wrappers)"]
        Extension --> Core
    end

    Browser --> Extension
    Core <--> API["DHIS2 Web API"]
    API <--> DHIS2["DHIS2 server<br/>Metadata, users, and captured data"]

    classDef user fill:#E8F0FE,stroke:#1A73E8,color:#17324D
    classDef browser fill:#FFF3E0,stroke:#F29900,color:#5F370E
    classDef extension fill:#FCE8E6,stroke:#D93025,color:#5F1510
    classDef core fill:#E6F4EA,stroke:#188038,color:#0D3B22
    classDef dhis fill:#F3E8FD,stroke:#9334E6,color:#3D1766
    class User user
    class Browser browser
    class Extension extension
    class Core core
    class API,DHIS2 dhis

Core application and project extensions

iCapture v3 separates reusable capabilities from project-specific implementation work.

  • iCapture v3 core is the default application. It contains no project configuration or custom extensions, and provides standard data-entry support for datasets, events, and trackers.
  • Project extensions are forks of the core application. Each implementation can add its own forms, workflows, configuration, branding, and other local requirements, while maintaining its own repository and release cycle.

This approach lets teams share a common base without exposing one project's implementation details to another project. HISP Vietnam–Mekong maintains the core application and can support collaborating teams that own their project extension.

flowchart TB
    Users["Implementation teams and end users"] --> Extension["Project extension\nCustom forms, workflows, configuration, and branding"]
    Extension --> Core["iCapture v3 core\nStandard Dataset, Event, and Tracker data entry"]
    Core --> DHIS2["DHIS2 instance\nMetadata, users, and data"]

    classDef user fill:#E8F0FE,stroke:#1A73E8,color:#17324D
    classDef extension fill:#FFF3E0,stroke:#F29900,color:#5F370E
    classDef core fill:#E6F4EA,stroke:#188038,color:#0D3B22
    classDef dhis fill:#F3E8FD,stroke:#9334E6,color:#3D1766
    class Users user
    class Extension extension
    class Core core
    class DHIS2 dhis

The project extension is the implementation-owned layer. It extends the shared core and connects to the project's DHIS2 instance.

Release and maintenance model

iCapture v3 uses semantic versioning in the format major.minor.patch, for example 1.3.5. Each release should include a changelog that records features, fixes, and other changes. This makes it easier for implementation teams to identify the deployed version and to roll back to a previous stable release if necessary.

Application layers

The application is organised into three main layers. Each layer has a distinct responsibility so that interface changes, workflow logic, and API concerns can evolve independently.

flowchart TB
    Presentation["Presentation layer<br/>(React pages and components<br/>Shadcn UI patterns<br/>Feature containers)"]
    Application["Application layer<br/>(Feature hooks and orchestration<br/>Form validation and transformations<br/>Route-driven mode switching)"]
    Data["Data layer<br/>(API clients and request wrappers<br/>Zustand metadata and runtime stores<br/>DHIS2 endpoint integration)"]
    DHIS2["DHIS2 Web API"]

    Presentation --> Application --> Data --> DHIS2

    classDef presentation fill:#E8F0FE,stroke:#1A73E8,color:#17324D
    classDef application fill:#E6F4EA,stroke:#188038,color:#0D3B22
    classDef data fill:#FFF3E0,stroke:#F29900,color:#5F370E
    classDef dhis fill:#F3E8FD,stroke:#9334E6,color:#3D1766
    class Presentation presentation
    class Application application
    class Data data
    class DHIS2 dhis

Presentation layer

The presentation layer contains React pages and components, Shadcn UI-based component patterns, and feature-level containers. It is responsible for displaying user interfaces and collecting user input; it should not contain complex API or data-transformation logic.

Application layer

The application layer coordinates feature behaviour. It contains feature hooks, workflow orchestration, form validation, data transformations, and route-driven switching between tracker, event, and aggregate modes.

Data layer

The data layer provides shared API clients and request wrappers, together with metadata and runtime state. It connects to DHIS2 endpoints and centralises consistent handling of requests, errors, and retries.

State management architecture

Zustand is used for focused, centralised state slices. Stores should be divided by domain, and side effects should live in hooks or services rather than in store declarations.

Recommended state boundaries include:

  • Global application state: dialogs, global notifications, and similar cross-cutting UI state.
  • Metadata state: programs, datasets, organisation units, option sets, and other DHIS2 metadata.
  • User selection state: current program, dataset, organisation unit, and reporting period.
  • Feature state: local state for event, tracker, and aggregate screens.

Use selectors where possible to reduce unnecessary component rerenders.

Routing and feature modules

iCapture v3 groups data-capture behaviour into feature modules for tracker workflows, event workflows, and aggregate dataset workflows. Each feature module owns its internal user interface and logic.

The URL should reflect the user's working context. Route parameters and selection state should remain synchronised so that a workflow can be refreshed, shared, or returned to without losing context.

Integration with DHIS2

All DHIS2 communication should use shared API client wrappers for operations such as GET, POST, and DELETE. The application follows a metadata-driven data flow:

  1. Fetch DHIS2 metadata and user context during application initialisation.
  2. Store the required metadata in centralised state.
  3. Bind the selected program, dataset, organisation unit, and period to the relevant page or form.
  4. Transform completed form data into the payload required by DHIS2 tracker or data-value APIs.
  5. Submit the payload and present consistent success, warning, or error feedback to the user.

Extension and customisation points

Extensions should add local behaviour without changing the assumptions of the core application. Common extension points include:

  • Program-specific forms.
  • Dataset-specific forms.
  • Control-bar behaviour and feature toggles.
  • Program-stage rules and custom handlers.

Before adding a new custom implementation, check whether an existing core pattern or extension point can meet the requirement. This reduces duplicated logic and makes later upgrades easier.