Population Health Service — Epics
Service: population-health-service Epic prefix: POPHEALTH-EPIC Last updated: 2026-04-18
Epics
POPHEALTH-EPIC-01 — Population Dashboard and Disease Registries
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Population dashboard, disease registries, screening + immunization views |
| Status | To Do |
| Priority | Must |
| Labels | service:population-health, domain:population_health, slice:S1 |
| Components | dashboard, registries, screenings, immunizations |
| Fix version | M1 |
| FR references | FR-POPHEALTH-001 – FR-POPHEALTH-007, FR-POPHEALTH-020 – FR-POPHEALTH-042 |
| Legacy FR refs | FR-POP-001–007, FR-POP-020–022, FR-POP-030–042 |
| Dependencies | patient-chart-service, immunizations-service, registration-service |
| Rollup status | Not started |
Business outcome: Care teams and facility managers have near-real-time visibility into population health status, chronic disease burdens, screening compliance, and immunization coverage across facilities and districts.
Description:
Deliver the foundational population health monitoring surface: a configurable dashboard with aggregate metrics (active patients, age/gender distribution, high-risk counts, screening compliance, immunization coverage), plus disease-specific registry views for TB, malaria, MCH, diabetes, hypertension, and other NCDs. All views enforce RBAC + node-scope filtering. PHI (patientId) is visible only to users with the phi:read permission.
Stories: POPHEALTH-US-001, POPHEALTH-US-002, POPHEALTH-US-003, POPHEALTH-US-004
POPHEALTH-EPIC-02 — Cohort Builder and Management
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Versioned cohort definitions with DSL, refresh engine, and membership management |
| Status | To Do |
| Priority | Must |
| Labels | service:population-health, domain:population_health, slice:S1 |
| Components | cohort-engine, cohort-dsl, refresh-worker |
| Fix version | M1 |
| FR references | FR-POPHEALTH-010 – FR-POPHEALTH-014 |
| Legacy FR refs | FR-POP-010–014 |
| Dependencies | patient-chart-service, laboratory-service, medication-service |
| Rollup status | Not started |
Business outcome: Analysts and clinicians can define patient cohorts using structured boolean predicates, save them for reuse, and rely on deterministic, versioned membership that can be refreshed on schedule or on demand.
Description: Implement the cohort expression DSL (JSON boolean tree with AND/OR/NOT/LEAF nodes), a parser with validation, a versioning strategy, a background refresh worker, and APIs for CRUD and refresh. Membership computation must be deterministic: identical predicates + identical source snapshot → identical membership. Refresh jobs coalesce to prevent duplicate processing. Supports demographic, clinical, lab, vital, immunization, medication, and risk predicates.
Stories: POPHEALTH-US-005, POPHEALTH-US-006
POPHEALTH-EPIC-03 — Risk Stratification and Outreach
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Clinical risk scoring models, manual overrides, care-gap detection, outreach lists |
| Status | To Do |
| Priority | Must |
| Labels | service:population-health, domain:population_health, slice:S1 |
| Components | risk-engine, care-gap-engine, outreach |
| Fix version | M1 |
| FR references | FR-POPHEALTH-050 – FR-POPHEALTH-062 |
| Legacy FR refs | FR-POP-050–062 |
| Dependencies | communication-service, patient-chart-service |
| Rollup status | Not started |
Business outcome: Care coordinators can identify high-risk patients, detect overdue care gaps, generate targeted outreach lists, and track contact attempts through to completion — driving proactive population health management.
Description: Implement configurable risk scoring models (points-based and logistic weight variants, configurable per tenant), care-gap detection rules per registry type, and outreach list generation from cohorts. Manual risk tier overrides require reason text and create an immutable audit record. Outreach items follow an FSM (pending → attempted → contacted → completed / declined / unable_to_reach). The communication-service is notified via NATS when an outreach list is generated.
Stories: POPHEALTH-US-007, POPHEALTH-US-008
POPHEALTH-EPIC-04 — Quality Metrics and Reporting
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | HEDIS, QOF, OHIP QIP, MoPH-custom, and donor quality metric computation |
| Status | To Do |
| Priority | Must |
| Labels | service:population-health, domain:population_health, slice:S2 |
| Components | quality-metrics, measure-engine, fhir-measure-report |
| Fix version | M2 |
| FR references | FR-POPHEALTH-070 – FR-POPHEALTH-072 |
| Legacy FR refs | FR-POP-070–072 |
| Dependencies | interop-service (FHIR MeasureReport), patient-chart-service |
| Rollup status | Not started |
Business outcome: MoPH, facility administrators, and donors receive accurate, programmatically computed quality metric snapshots with trend data, enabling evidence-based program management and donor reporting.
Description: Implement a pluggable quality measure engine supporting HEDIS (blood pressure control, diabetes care, preventive screening), QOF (UK primary care), OHIP QIP, MoPH-custom (Afghanistan-specific indicators), and donor indicator packs. Each measure computes numerator, denominator, exclusions, and rate. Snapshots are immutable once stored. Trend series are derived from historical snapshots. Patient-level drill-down is role-restricted. FHIR MeasureReport publication via interop-service on each snapshot.
Stories: POPHEALTH-US-009, POPHEALTH-US-010
POPHEALTH-EPIC-05 — HMIS DHIS2 Export Pipeline
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Scheduled and on-demand MoPH DHIS2 aggregate indicator push |
| Status | To Do |
| Priority | Must |
| Labels | service:population-health, domain:population_health, slice:S2 |
| Components | hmis-exporter, dhis2-adapter, hmis-scheduler |
| Fix version | M2 |
| FR references | FR-POPHEALTH-080, FR-POPHEALTH-081 |
| Legacy FR refs | FR-POP-080–081 |
| Dependencies | MoPH DHIS2 API, interop-service |
| Rollup status | Not started |
Business outcome: MoPH receives timely, accurate national health indicator data in DHIS2 without manual extraction, satisfying national HMIS reporting obligations for Afghanistan.
Description: Implement the DHIS2 REST adapter (v2.39+ API), an indicator family → DHIS2 data-element mapping layer (configurable per tenant/program), a scheduler for daily/weekly/monthly push frequencies, retry logic with exponential backoff (max 3 attempts), and an on-demand trigger API. All exports are audited. Import summary parsing validates no indicators were silently ignored. Parallel push during migration cutover (Phase 3) compares results before legacy decommission.
Stories: POPHEALTH-US-011, POPHEALTH-US-012
POPHEALTH-EPIC-06 — De-Identification and Research Export
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | k-anonymity + differential privacy pipeline for secondary-use research exports |
| Status | To Do |
| Priority | Must |
| Labels | service:population-health, domain:population_health, slice:S3 |
| Components | deident-pipeline, research-export, consent-enforcement |
| Fix version | M2 |
| FR references | FR-POPHEALTH-082 – FR-POPHEALTH-085 |
| Legacy FR refs | FR-POP-082 |
| Dependencies | audit-service, access-policy (consent check) |
| Rollup status | Not started |
Business outcome: Researchers and MoPH analysts can access de-identified cohort data for secondary use without risk of patient re-identification, satisfying Afghan data protection requirements and donor audit trails.
Description: Implement server-side k-anonymity (k≥5) via quasi-identifier generalization and differential privacy (Laplace noise, ε≤1.0) applied before any research export crosses the trust boundary. Consent enforcement blocks identifiable exports without IRB reference. Aggregate-only exports bypass de-identification. Output files are stored in encrypted object storage with presigned URLs (24h TTL). All export events are audited with purpose, IRB reference, requester, and privacy parameters.
Stories: POPHEALTH-US-013, POPHEALTH-US-014
POPHEALTH-EPIC-07 — Offline Facility Reports and Sync
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Offline facility aggregate report generation and sync for low-connectivity districts |
| Status | To Do |
| Priority | Should |
| Labels | service:population-health, domain:population_health, slice:S4 |
| Components | offline-reports, sync-protocol |
| Fix version | M3 |
| FR references | FR-POPHEALTH-090 – FR-POPHEALTH-092 |
| Legacy FR refs | — (synthesized) |
| Dependencies | sync-protocol library (@ghasi/sync-protocol) |
| Rollup status | Not started |
Business outcome: District health officers in Afghanistan can generate and review population health summaries even when offline, with automatic sync to the national platform when connectivity is restored.
Description:
Implement the facility-level offline aggregate report generator (daily/weekly patient counts, screening compliance, immunization rates, registry summary). Reports are signed with device keypair and queued for upload. The sync endpoint verifies signatures, deduplicates by (facilityId, periodKey, deviceId), and merges into the analytics store. dataFreshness metadata is exposed in all dashboard responses to indicate stale offline data. Automated tests cover queue replay, idempotency, and conflict paths.
Stories: POPHEALTH-US-015
POPHEALTH-EPIC-08 — Security, RBAC, and Compliance
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | RBAC/ABAC enforcement, PHI controls, audit events, tenant isolation |
| Status | To Do |
| Priority | Must |
| Labels | service:population-health, domain:population_health, slice:S0 |
| Components | security, rbac, audit, rls |
| Fix version | M1 |
| FR references | FR-POPHEALTH-100 – FR-POPHEALTH-106 |
| Legacy FR refs | FR-POP-080–083 |
| Dependencies | audit-service, identity-service (Keycloak) |
| Rollup status | Not started |
Business outcome: The platform can demonstrate full auditability and access control compliance for population health data, satisfying MoPH data governance, HIPAA-analogue, and donor audit requirements.
Description: Implement RBAC + ABAC on all endpoints (node-scope filtering, phi:read gate for patient IDs), PostgreSQL RLS on all tables, structured audit events for every sensitive operation (exports, overrides, PHI access), cross-tenant violation detection and logging, and encryption-at-rest for all PHI columns. Security posture is verified by mandatory integration tests: tenant-isolation, RLS enforcement, consent-enforcement. PHI redaction enforced at logging layer.
Stories: POPHEALTH-US-016