Population Health Service — Service Overview
Status: populated
Owner: TBD
Last updated: 2026-04-18
Companion: Service Template · 03 platform-services · 02 DDD
1. Purpose
The population-health-service provides national-scale population analytics and public-health intelligence for the Ghasi eHealth platform. It owns disease registries (TB, malaria, MCH, NCD), cohort builders, quality-metric computation, risk stratification, outreach orchestration, HMIS indicator exports to MoPH DHIS2, de-identification pipelines for research exports, and secondary-use consent enforcement.
This is a licensed add-on module. It never holds source-of-truth clinical records; all analytics are derived from upstream clinical services. Afghanistan is the initial reference jurisdiction; multi-country indicator packs are supported via configuration.
2. Bounded Context
| Aspect | Value |
|---|
| DDD context | Population Health (analytic + orchestration) |
| Bounded context owner | MoPH Analytics team + Ghasi platform |
| Source of truth for | Cohort definitions, registry snapshots, quality-metric snapshots, outreach lists, HMIS export jobs, de-identification results |
| NOT source of truth for | Patient demographics, clinical encounters, medications, lab results, immunization records |
3. Responsibilities
| # | Responsibility |
|---|
| R1 | Maintain versioned cohort definitions and refresh membership against upstream clinical data |
| R2 | Compute population dashboards (aggregate counts, age/gender distributions, disease prevalence) |
| R3 | Manage chronic disease registries: TB, malaria, MCH, diabetes, hypertension, COPD, asthma, CHF, CKD, mental health, obesity |
| R4 | Run quality-metric snapshots (HEDIS, QOF, OHIP QIP, MoPH-custom, donor indicator sets) |
| R5 | Execute configurable clinical risk-scoring models and track manual tier overrides with audit trail |
| R6 | Generate outreach lists; track contact-attempt lifecycle to terminal state |
| R7 | Push HMIS indicator aggregates to MoPH DHIS2 on configured schedules (daily / weekly / monthly per indicator family) |
| R8 | Apply de-identification pipeline (k-anonymity k≥5 + differential privacy ε≤1.0) before any research export crosses the trust boundary |
| R9 | Enforce secondary-use consent: aggregate-only queries for non-consented patients; identifiable research requires explicit consent + IRB-approved purpose |
| R10 | Generate facility-level offline aggregate reports; sync when connectivity restores |
4. Non-Responsibilities
| Non-responsibility | Owned by |
|---|
| Storing or modifying clinical records | patient-chart-service, immunizations-service, medication-service |
| Real-time CDS at point of care | care-plan-service, ai-gateway-service |
| Patient identity matching | registration-service |
| IRB protocol management | MoPH / legal |
| Trusted Research Environment (TRE) execution | Roadmap — separate deployable |
| SMS/notification delivery | communication-service |
5. Upstream / Downstream Dependencies
6. Key Architectural Decisions
| Decision | Choice | Rationale |
|---|
| Analytics store | Materialized snapshots in PostgreSQL 16 | No DWH dependency in phase 1; ClickHouse migration path in MIGRATION_PLAN |
| HMIS push | Scheduled outbound adapter (DHIS2 REST API v2.39+) | MoPH mandates DHIS2; schedule and indicator set are tenant-configurable |
| De-identification | k-anonymity (k≥5) + Laplace differential privacy (ε≤1.0) computed server-side before export | Research exports must never expose re-identifiable micro-data per Afghan data protection baseline |
| Cohort DSL | JSON boolean expression tree, validated at write time, versioned immutably | Deterministic; reproducible membership across reruns with same source snapshot |
| Offline reports | Facility-level JSON snapshot generation; CouchDB-Lite / local SQLite for district health offices; sync via platform sync-protocol | Afghanistan: intermittent connectivity at district level |
| FHIR output | MeasureReport (quality metrics); Group (cohort publishing); Patient de-identified | FHIR R4 conformant; routed via interop-service |
| Event domain | population_health per NAMING.md (replaces legacy health-population.* subjects) | Consistency across platform event naming |
7. Slice Involvement
| Slice | Scope |
|---|
| S0 | Platform scaffold, NATS stream POPULATION_HEALTH, DB migrations, tenant isolation |
| S1 | Population dashboard, cohort CRUD, disease registries |
| S2 | Quality metrics (HEDIS/QOF/MoPH), risk scoring, HMIS DHIS2 export |
| S3 | Outreach lists, de-identification pipeline, research export API |
| S4 | Offline facility reports, sync protocol, donor indicator pack |
8. Source Reconciliation
Primary source: services/population-health-service/_sources/health-population/ (single module — no multi-module merge). Legacy health-population.* event subjects mapped to population_health.* per NAMING.md. FR-POP-* identifiers are preserved in legacy column; new canonical refs use FR-POPHEALTH-* prefix for synthesized requirements. No removed specs/modules/... paths referenced in this documentation set.