# medic/cht-core architecture

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

- Interactive diagram: https://gitdiagram.com/medic/cht-core
- Repository: https://github.com/medic/cht-core

## Overview

#### Purpose and runtime topology
CHT Core is an offline-capable community-health application framework: health workers capture contacts, reports, tasks, and messages; supervisors/admins manage, search, export, and monitor them. It is a multi-service system, not just a web app: Angular browser clients, Node.js API and background workers, CouchDB, and reverse proxies are deployed as Docker/Kubernetes services.

Core process entry points are `api/server.js` and `sentinel/server.js`; the browser client starts at `webapp/src/ts/main.ts`; the legacy administration UI starts at `admin/src/js/main.js`.

#### Client applications and offline boundary
The primary user client is an Angular/TypeScript SPA organized around routed operational domains—contacts, reports, tasks, messages, analytics, and training—under `webapp/src/ts/modules/` and routed by `webapp/src/ts/app-routing.module.ts`. NgRx-style actions, reducers, selectors, and effects separate UI state from database/network work.

Offline-first behavior is a defining boundary: bootstrapping establishes local storage, initial replication, local design documents/search indexes, purging, translations, and service-worker registration in `webapp/src/js/bootstrapper/index.js` and `webapp/src/js/bootstrapper/initial-replication.js`. Database synchronization is managed by `webapp/src/ts/services/db-sync.service.ts`.

A separate AngularJS admin client provides user/role, settings, upgrade, translation, branding, SMS, and export administration via `admin/src/js/controllers/` and `admin/src/js/services/db.js`.

#### API gateway and domain API
The Node.js API owns HTTP routing, authentication, authorization, request shaping, rate limiting, and server-side domain operations. Routing and server composition are centered on `api/src/routing.js`, `api/src/auth.js`, and `api/src/server-utils.js`. Controllers expose contacts, people/places, reports, forms, records, users, settings, exports, monitoring, and replication endpoints in `api/src/controllers/`.

The API is the boundary between clients and CouchDB: its database adapters (`api/src/db.js`, `api/src/db-batch.js`) and middleware (`api/src/middleware/authorization.js`, `api/src/middleware/rate-limiter.js`) enforce access and operational policy. Login, public privacy pages, and static web assets are also served from `api/src/public/`.

#### Document data platform and replication
CouchDB is the source of truth for application documents, users, metadata, logs, SMS, and Sentinel state. Database setup, design-document deployment, index readiness, default-document upload, and upgrade sequencing are orchestrated by `api/src/services/setup/`, `api/src/migrations.js`, and `api/src/upload-default-docs.js`.

Design documents encode data access, validation, and search schemas. Key examples are `ddocs/medic-db/medic/validate_doc_update.js`, `ddocs/medic-db/medic-client/views/`, and `ddocs/medic-db/medic/nouveau/`. Controlled replication APIs protect per-user/offline datasets via `api/src/services/replication/` and `api/src/controllers/replication.js`.

#### Asynchronous clinical workflow engine
Sentinel is the Node.js background worker that consumes database changes and scheduled jobs. Its core loop and processing hooks are in `sentinel/src/transitions.js`, `sentinel/src/lib/feed.js`, and `sentinel/src/schedule/index.js`.

It applies reusable transition rules from `shared-libs/transitions/src/transitions/` to incoming reports/documents: registration, alerts, notifications, scheduled reports/tasks, muting, outbound marking, and data cleanup. It also runs reminder, replication, outbound, purging, and background-cleanup schedules under `sentinel/src/schedule/`. This separates eventual clinical workflow processing from synchronous user/API requests.

#### Forms, messaging, and integrations
Forms are XForms/XML artifacts, transformed server-side and rendered in the client through Enketo integration: `api/src/services/forms.js`, `api/src/enketo-transformer/`, and `webapp/src/ts/services/enketo.service.ts`. Submitted forms become report/contact documents, replicate through CouchDB, and then trigger Sentinel transitions.

Messaging supports SMS gateway workflows and external providers including Africa’s Talking and RapidPro through `api/src/services/messaging.js`, `api/src/services/africas-talking.js`, and `api/src/services/rapidpro.js`. Outbound work is persisted and scheduled rather than coupled directly to form submission.

#### Deployment and shared contracts
Deployments package API, Sentinel, CouchDB, HAProxy, Nginx, health checking, and CouchDB Nouveau search. Container/service definitions are rooted in `api/Dockerfile`, `sentinel/Dockerfile`, `couchdb/Dockerfile`, and Helm templates in `scripts/build/helm/templates/`. HAProxy fronts CouchDB/service traffic (`haproxy/backend.cfg.template`); Nginx serves TLS/static edge concerns (`nginx/nginx.conf`).

`shared-libs/` contains cross-runtime business contracts, notably rules evaluation (`shared-libs/rules-engine/src/`), document access (`shared-libs/cht-datasource/src/`), lineage (`shared-libs/lineage/src/`), and transition logic. Application-specific behavior and default health-program content are supplied as deployable configuration bundles in `config/default/`, including settings, forms, tasks, targets, resources, and translations.

Main entry points: [`couchdb/Dockerfile`](https://github.com/medic/cht-core/blob/master/couchdb/Dockerfile) (CouchDB), [`api/src/routing.js`](https://github.com/medic/cht-core/blob/master/api/src/routing.js) (Domain controllers), [`api/server.js`](https://github.com/medic/cht-core/blob/master/api/server.js) (HTTP API), [`webapp/src/ts/main.ts`](https://github.com/medic/cht-core/blob/master/webapp/src/ts/main.ts) (Angular health-worker SPA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client applications"]
  node_webapp["Angular health-worker SPA<br/>Angular client<br/>[main.ts]"]
  node_webapp_routes["Operational routes<br/>routing modules"]
  node_offline_bootstrap["Offline bootstrap<br/>replication bootstrap<br/>[index.js]"]
  node_db_sync["Client DB sync<br/>sync service<br/>[db-sync.service.ts]"]
  node_admin["Legacy admin UI<br/>AngularJS client<br/>[main.js]"]
end

subgraph group_api["API service"]
  node_api_server{{"HTTP API<br/>Node.js service<br/>[server.js]"}}
  node_api_routing["Domain controllers<br/>HTTP routing<br/>[routing.js]"]
  node_api_policy["Access and rate policy<br/>middleware<br/>[authorization.js]"]
  node_api_db["CouchDB adapters<br/>data access<br/>[db.js]"]
  node_forms["Forms and Enketo transform<br/>form service<br/>[forms.js]"]
  node_replication_api["Controlled replication<br/>replication service"]
  node_messaging["External messaging<br/>provider integration<br/>[messaging.js]"]
end

subgraph group_workflow["Async workflow"]
  node_sentinel{{"Sentinel worker<br/>Node.js worker<br/>[server.js]"}}
  node_change_feed["Change feed and transitions<br/>event processor<br/>[transitions.js]"]
  node_schedules["Background schedules<br/>job scheduler<br/>[index.js]"]
  node_transition_rules["Clinical transition rules<br/>shared contracts"]
end

subgraph group_data["Document platform"]
  node_couchdb[("CouchDB<br/>document database")]
  node_design_docs["Design docs and search<br/>CouchDB schemas"]
  node_setup["Database setup and migration<br/>provisioning"]
end

subgraph group_deployment["Deployment"]
  node_config_bundle["Health-program bundles<br/>deployable configuration"]
  node_edge["Proxy and TLS edge<br/>reverse proxies<br/>[nginx.conf]"]
  node_helm["Kubernetes packaging<br/>Helm deployment"]
end

node_webapp -->|"navigates"| node_webapp_routes
node_webapp -->|"initializes"| node_offline_bootstrap
node_offline_bootstrap -->|"starts"| node_db_sync
node_db_sync -->|"syncs via"| node_replication_api
node_webapp -->|"uses HTTP API"| node_api_server
node_admin -->|"admin requests"| node_api_server
node_edge -->|"routes traffic"| node_api_server
node_api_server -->|"composes"| node_api_routing
node_api_routing -->|"enforces"| node_api_policy
node_api_routing -->|"serves domains through"| node_api_db
node_api_routing -->|"serves forms"| node_forms
node_api_routing -->|"exposes"| node_replication_api
node_api_db -->|"reads and writes"| node_couchdb
node_replication_api -->|"filters datasets"| node_couchdb
node_forms -->|"persists submissions"| node_couchdb
node_couchdb -->|"document changes"| node_change_feed
node_sentinel -->|"runs"| node_change_feed
node_sentinel -->|"runs"| node_schedules
node_change_feed -->|"applies"| node_transition_rules
node_transition_rules -->|"updates workflow documents"| node_couchdb
node_schedules -->|"dispatches outbound work"| node_messaging
node_setup -->|"provisions"| node_couchdb
node_setup -->|"deploys"| node_design_docs
node_config_bundle -->|"supplies defaults"| node_setup
node_helm -.->|"deploys"| node_api_server
node_helm -.->|"deploys"| node_sentinel
node_helm -.->|"deploys"| node_couchdb

click node_webapp "https://github.com/medic/cht-core/blob/master/webapp/src/ts/main.ts"
click node_webapp_routes "https://github.com/medic/cht-core/blob/master/webapp/src/ts/app-routing.module.ts"
click node_offline_bootstrap "https://github.com/medic/cht-core/blob/master/webapp/src/js/bootstrapper/index.js"
click node_db_sync "https://github.com/medic/cht-core/blob/master/webapp/src/ts/services/db-sync.service.ts"
click node_admin "https://github.com/medic/cht-core/blob/master/admin/src/js/main.js"
click node_api_server "https://github.com/medic/cht-core/blob/master/api/server.js"
click node_api_routing "https://github.com/medic/cht-core/blob/master/api/src/routing.js"
click node_api_policy "https://github.com/medic/cht-core/blob/master/api/src/middleware/authorization.js"
click node_api_db "https://github.com/medic/cht-core/blob/master/api/src/db.js"
click node_forms "https://github.com/medic/cht-core/blob/master/api/src/services/forms.js"
click node_sentinel "https://github.com/medic/cht-core/blob/master/sentinel/server.js"
click node_change_feed "https://github.com/medic/cht-core/blob/master/sentinel/src/transitions.js"
click node_schedules "https://github.com/medic/cht-core/blob/master/sentinel/src/schedule/index.js"
click node_couchdb "https://github.com/medic/cht-core/blob/master/couchdb/Dockerfile"
click node_design_docs "https://github.com/medic/cht-core/blob/master/ddocs/medic-db/medic/validate_doc_update.js"
click node_messaging "https://github.com/medic/cht-core/blob/master/api/src/services/messaging.js"
click node_edge "https://github.com/medic/cht-core/blob/master/nginx/nginx.conf"

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_webapp,node_webapp_routes,node_offline_bootstrap,node_db_sync,node_admin toneBlue
class node_api_server,node_api_routing,node_api_policy,node_api_db,node_forms,node_replication_api,node_messaging toneAmber
class node_sentinel,node_change_feed,node_schedules,node_transition_rules toneMint
class node_couchdb,node_design_docs,node_setup toneRose
class node_config_bundle,node_edge,node_helm toneIndigo
```

## Components

### Client applications

- [Angular health-worker SPA](https://github.com/medic/cht-core/blob/master/webapp/src/ts/main.ts): Angular client · Operational UI for contacts, reports, tasks, messages, analytics, and training. · `webapp/src/ts/main.ts`
- [Operational routes](https://github.com/medic/cht-core/blob/master/webapp/src/ts/app-routing.module.ts): routing modules · `webapp/src/ts/app-routing.module.ts`
- [Offline bootstrap](https://github.com/medic/cht-core/blob/master/webapp/src/js/bootstrapper/index.js): replication bootstrap · Initializes local storage, replication, indexes, purge, translations, and service worker. · `webapp/src/js/bootstrapper/index.js`
- [Client DB sync](https://github.com/medic/cht-core/blob/master/webapp/src/ts/services/db-sync.service.ts): sync service · `webapp/src/ts/services/db-sync.service.ts`
- [Legacy admin UI](https://github.com/medic/cht-core/blob/master/admin/src/js/main.js): AngularJS client · Administration for users, settings, upgrades, exports, and integrations. · `admin/src/js/main.js`

### API service

- [HTTP API](https://github.com/medic/cht-core/blob/master/api/server.js): Node.js service · Authenticates, authorizes, shapes, and routes client requests. · `api/server.js`
- [Domain controllers](https://github.com/medic/cht-core/blob/master/api/src/routing.js): HTTP routing · Contacts, reports, forms, records, users, settings, exports, monitoring, and replication. · `api/src/routing.js`
- [Access and rate policy](https://github.com/medic/cht-core/blob/master/api/src/middleware/authorization.js): middleware · `api/src/middleware/authorization.js`
- [CouchDB adapters](https://github.com/medic/cht-core/blob/master/api/src/db.js): data access · `api/src/db.js`
- [Forms and Enketo transform](https://github.com/medic/cht-core/blob/master/api/src/services/forms.js): form service · Transforms XForms for client rendering and submission. · `api/src/services/forms.js`
- **Controlled replication**: replication service · Protects per-user offline datasets.
- [External messaging](https://github.com/medic/cht-core/blob/master/api/src/services/messaging.js): provider integration · Schedules SMS work for Africa's Talking and RapidPro. · `api/src/services/messaging.js`

### Async workflow

- [Sentinel worker](https://github.com/medic/cht-core/blob/master/sentinel/server.js): Node.js worker · Processes changes and scheduled clinical work outside request paths. · `sentinel/server.js`
- [Change feed and transitions](https://github.com/medic/cht-core/blob/master/sentinel/src/transitions.js): event processor · `sentinel/src/transitions.js`
- [Background schedules](https://github.com/medic/cht-core/blob/master/sentinel/src/schedule/index.js): job scheduler · Runs reminder, replication, outbound, purge, and cleanup jobs. · `sentinel/src/schedule/index.js`
- **Clinical transition rules**: shared contracts · Registration, alerts, notifications, tasks, muting, and cleanup rules.

### Document platform

- [CouchDB](https://github.com/medic/cht-core/blob/master/couchdb/Dockerfile): document database · Source of truth for application, user, messaging, log, and Sentinel documents. · `couchdb/Dockerfile`
- [Design docs and search](https://github.com/medic/cht-core/blob/master/ddocs/medic-db/medic/validate_doc_update.js): CouchDB schemas · Validation, views, and Nouveau search schemas. · `ddocs/medic-db/medic/validate_doc_update.js`
- **Database setup and migration**: provisioning · Deploys design docs, defaults, indexes, and upgrades.

### Deployment

- **Health-program bundles**: deployable configuration · Default settings, forms, tasks, targets, resources, and translations.
- [Proxy and TLS edge](https://github.com/medic/cht-core/blob/master/nginx/nginx.conf): reverse proxies · Nginx serves edge/static concerns; HAProxy fronts CouchDB and services. · `nginx/nginx.conf`
- **Kubernetes packaging**: Helm deployment · Packages API, Sentinel, CouchDB, proxies, and search services.

## Connections

- Angular health-worker SPA → Operational routes: navigates
- Angular health-worker SPA → Offline bootstrap: initializes
- Offline bootstrap → Client DB sync: starts
- Client DB sync → Controlled replication: syncs via
- Angular health-worker SPA → HTTP API: uses HTTP API
- Legacy admin UI → HTTP API: admin requests
- Proxy and TLS edge → HTTP API: routes traffic
- HTTP API → Domain controllers: composes
- Domain controllers → Access and rate policy: enforces
- Domain controllers → CouchDB adapters: serves domains through
- Domain controllers → Forms and Enketo transform: serves forms
- Domain controllers → Controlled replication: exposes
- CouchDB adapters → CouchDB: reads and writes
- Controlled replication → CouchDB: filters datasets
- Forms and Enketo transform → CouchDB: persists submissions
- CouchDB → Change feed and transitions: document changes
- Sentinel worker → Change feed and transitions: runs
- Sentinel worker → Background schedules: runs
- Change feed and transitions → Clinical transition rules: applies
- Clinical transition rules → CouchDB: updates workflow documents
- Background schedules → External messaging: dispatches outbound work
- Database setup and migration → CouchDB: provisions
- Database setup and migration → Design docs and search: deploys
- Health-program bundles → Database setup and migration: supplies defaults
- Kubernetes packaging → HTTP API: deploys
- Kubernetes packaging → Sentinel worker: deploys
- Kubernetes packaging → CouchDB: deploys