medic/cht-core

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.