07 — Epics and User Stories
Status: populated Last updated: 2026-04-18 Companion: 01 enterprise-architecture · 02 DDD contexts · 03 platform-services · 06 traceability-matrix · 11 risks-and-tradeoffs
1. Purpose
Platform-wide index of all epics, user stories, and cross-service journeys across the 27 Ghasi-eHealth services. Service-local backlogs live at services/<service>/EPICS.md and services/<service>/USER_STORIES.md. Cross-service journeys (below, §4) cut across multiple services and anchor end-to-end E2E coverage in 18 testing-strategy.
2. ID Prefix Registry
All epics, stories, and FR references use service-aligned prefixes (zero-padded: -01, -02 for epics; -001, -002 for stories). The prefix set is normative — agents generating or reviewing backlog content MUST use these exact prefixes.
| # | Service | Epic prefix | Story prefix | FR prefix | Event domain |
|---|---|---|---|---|---|
| 1 | identity-service | IDENT-EPIC | IDENT-US | FR-IDENT | identity |
| 2 | tenant-service | TENANT-EPIC | TENANT-US | FR-TENANT | tenant |
| 3 | platform-admin-service | PLTADM-EPIC | PLTADM-US | FR-PLTADM | platform_admin |
| 4 | facility-service | FAC-EPIC | FAC-US | FR-FAC | facility |
| 5 | provider-directory-service | PROVDIR-EPIC | PROVDIR-US | FR-PROVDIR | provider_directory |
| 6 | registration-service | REG-EPIC | REG-US | FR-REG | registration |
| 7 | scheduling-service | SCHED-EPIC | SCHED-US | FR-SCHED | scheduling |
| 8 | patient-portal-service | PORTAL-EPIC | PORTAL-US | FR-PORTAL | patient_portal |
| 9 | virtual-care-service | VCARE-EPIC | VCARE-US | FR-VCARE | virtual_care |
| 10 | patient-chart-service | CHART-EPIC | CHART-US | FR-CHART | patient_chart |
| 11 | immunizations-service | IMMUN-EPIC | IMMUN-US | FR-IMMUN | immunizations |
| 12 | care-plan-service | CAREPL-EPIC | CAREPL-US | FR-CAREPL | care_plan |
| 13 | orders-service | ORDERS-EPIC | ORDERS-US | FR-ORDERS | orders |
| 14 | medication-service | MED-EPIC | MED-US | FR-MED | medication |
| 15 | ghasi-eprescribing-gateway-service | EPRX-EPIC | EPRX-US | FR-EPRX | eprescribing |
| 16 | laboratory-service | LAB-EPIC | LAB-US | FR-LAB | laboratory |
| 17 | radiology-service | RAD-EPIC | RAD-US | FR-RAD | radiology |
| 18 | billing-service | BILL-EPIC | BILL-US | FR-BILL | billing |
| 19 | claims-service | CLAIMS-EPIC | CLAIMS-US | FR-CLAIMS | claims |
| 20 | communication-service | COMMS-EPIC | COMMS-US | FR-COMMS | communication |
| 21 | interop-service | INTEROP-EPIC | INTEROP-US | FR-INTEROP | interop |
| 22 | terminology-service | TERM-EPIC | TERM-US | FR-TERM | terminology |
| 23 | document-service | DOC-EPIC | DOC-US | FR-DOC | document |
| 24 | ai-gateway-service | AIGW-EPIC | AIGW-US | FR-AIGW | ai_gateway |
| 25 | audit-service | AUDIT-EPIC | AUDIT-US | FR-AUDIT | audit |
| 26 | config-service | CONFIG-EPIC | CONFIG-US | FR-CONFIG | config |
| 27 | population-health-service | POPHEALTH-EPIC | POPHEALTH-US | FR-POPHEALTH | population_health |
3. Per-service backlog index
Counts below are minima; service docs are the source of truth. Legacy FR refs (e.g., FR-IAM-AUTH-001) are preserved in a "Legacy ref" column in each service's USER_STORIES.md and mapped to the new prefix.
4. Cross-service user journeys (J-01 … J-25)
Each journey is named J-NN, traces one actor through ≥ 3 services, and maps to an E2E gate in 18 testing-strategy. Starred (*) entries are nightly blocking E2E gates.
4.1 Journey catalogue
| ID | Journey | Primary actor | Services touched | AI | Offline | E2E gate |
|---|---|---|---|---|---|---|
| J-01* | Tenant onboarding → first facility live | Tenant Admin | tenant · identity · platform-admin · facility · provider-directory · config · audit | — | — | Yes |
| J-02* | New patient registration → first encounter | Registration Clerk → Clinician | registration · patient-chart · scheduling · provider-directory · facility · audit | optional (duplicate suggest) | Yes (desktop station) | Yes |
| J-03* | Clinician SSO sign-in → open chart → place order | Clinician | identity · patient-chart · orders · terminology · medication · audit | — | Yes | Yes |
| J-04* | E-prescribing cross-facility fill | Prescriber → Pharmacist | orders · medication · eprescribing-gateway · interop · audit | DDI check | No | Yes |
| J-05* | Lab order → specimen → result review | Clinician · Lab Tech · Clinician | orders · laboratory · interop · patient-chart · communication · audit | — | partial (lab) | Yes |
| J-06* | Radiology order → imaging study → report | Clinician · Radiologist | orders · radiology · interop · patient-chart · document · audit | report-drafting (AIGW) | No | Yes |
| J-07* | Immunization campaign enrollment → dose → HMIS export | Immunization Nurse · Public Health | immunizations · patient-chart · population-health · interop · audit | — | Yes (field clinics) | Yes |
| J-08* | Virtual visit → clinical note → billing | Patient · Clinician | patient-portal · virtual-care · communication · patient-chart · billing · claims · audit | scribe draft | — | Yes |
| J-09 | Patient portal self-registration → link to chart | Patient · Reg. Clerk | patient-portal · identity · registration · communication · audit | identity-matching hint | — | — |
| J-10* | Patient books appointment via portal | Patient | patient-portal · scheduling · provider-directory · communication · audit | — | — | Yes |
| J-11* | Provider offline clinic → sync on reconnect | Provider (mobile) | patient-chart · registration · immunizations · orders · vitals · audit | — | Yes (Realm) | Yes |
| J-12 | Lab result released to patient portal | Lab Tech → Patient | laboratory · patient-chart · patient-portal · communication · audit | — | — | — |
| J-13 | Care plan creation → task assignment → follow-up | Clinician · Patient · Care Coord. | care-plan · patient-chart · communication · scheduling · audit | plan suggest | Yes | — |
| J-14* | Claim submission → remittance → reconciliation | Billing Clerk · Payer | billing · claims · interop · audit | coding hint | — | Yes |
| J-15* | HMIS indicator export (monthly MoPH) | Population Health Analyst | population-health · patient-chart · laboratory · immunizations · interop · audit | — | — | Yes |
| J-16* | Consent change → downstream revocation | Patient · all services reading PHI | identity · patient-portal · audit · + all PHI consumers | — | Yes | Yes |
| J-17* | Break-glass access → audit review | Clinician (emergency) · Compliance | identity · patient-chart · audit | — | Yes (offline break-glass queue) | Yes |
| J-18 | Medication reconciliation at admission | Pharmacist · Clinician | medication · patient-chart · eprescribing-gateway · orders · audit | reconciliation assist | Yes | — |
| J-19* | Multi-tenant cross-facility referral | Clinician A → Clinician B | provider-directory · interop · patient-chart · orders · communication · audit | — | — | Yes |
| J-20 | Document upload → OCR → chart linkage | Reg. Clerk | document · patient-chart · audit | OCR + classification | — | — |
| J-21* | DSAR — patient data export | Patient (DPO for minor) | patient-portal · audit · + all PHI owners | — | — | Yes |
| J-22 | Provider credentialing update → licensing gate | Credentialing Officer | provider-directory · identity · facility · audit | — | — | — |
| J-23* | Population outreach — screening reminder wave | Public Health Nurse | population-health · communication · patient-portal · audit | cohort segmentation | — | Yes |
| J-24 | Terminology update (ICD-11) platform rollout | Terminologist · all clinical services | terminology · config · audit · + all clinical readers | — | — | — |
| J-25* | Offline immunization field clinic → national registry | Nurse (mobile) · MoPH | immunizations · interop · population-health · audit | — | Yes (full offline) | Yes |
4.2 Cross-cutting invariants
- Every journey logs end-to-end traces carrying
trace_id,tenant_id,actor_id_hash, andcorrelation_idper 12 observability-telemetry. - Every journey respects WCAG 2.2 AA and LTR/RTL (Pashto, Dari, Arabic, English) per 08 design guidelines.
- Every journey that writes PHI emits an
audit.*event; loss of audit blocks the transaction. - Every offline journey must pass the sync conflict matrix per 16 offline-first.
4.3 Journey diagrams (anchors)
Detailed sequence + state diagrams live under docs/frontend/journeys/J-NN-<slug>.md. Each file MUST contain: actor list, preconditions, mermaid sequence, service call matrix, failure modes, E2E test IDs.
5. Epic synthesis rules
- Drive from FR not implementation — Epics reference FR IDs (see 06 traceability-matrix) and outcomes, not specific controllers.
- One aggregate rarely owns > 2 epics — If it does, split the aggregate.
- Legacy FR preservation — Merging multi-module services (e.g., identity-service consolidates iam + access-policy + licensing) preserves the legacy
FR-IAM-*/FR-ACCESS-*/FR-LIC-*refs in aLegacy refcolumn, mapped to the newFR-IDENT-*. - Slice labels — Each epic carries a slice label (
S0foundation,S1clinical MVP,S2add-ons,S3national interop,S4AI/analytics) for release planning. - Story sizing — Fibonacci points (1/2/3/5/8/13). Stories > 13 pts split mandatory.
6. Backlog governance
| Concern | Rule |
|---|---|
| Prefix uniqueness | Enforced by CI lint rule scanning services/**/EPICS.md and **/USER_STORIES.md. |
| Cross-service link | Dependencies field declares {OTHER_PREFIX}-EPIC-NN / -US-NNN explicitly. |
| Coverage | Every epic lists ≥ 1 FR; every story lists ≥ 1 FR. CI fails on empty FR columns. |
| Traceability | 06 traceability-matrix links FR → Epic → Story → Test ID → PR. |
| Jira sync | Each doc is Jira-ready CSV-importable; round-trip keeps IDs stable. |
7. Open Questions
- Whether population-health epics should split further into "chronic registries" vs "outbreak response" once the MoPH indicator set stabilises.
- Journey numbering above 25 — reserve J-26..J-40 for virtual care secondary use cases and research consent flows as those emerge.