Ghasi eHealth — Delivery Roadmap (Execution Layer, v1)

This is the execution layer. The end-state specification lives in specs/README.md, architecture baseline in specs/architecture/, and module specs in specs/modules/. This roadmap sequences how to ship the full product without rework.

This file is the index. Detailed execution artifacts live under docs/roadmap/.

Companion Documents

File	Purpose
Slice → Epic → Story Mapping	Every module epic mapped to a slice + milestone + sprint-ready backlog
Service Readiness Gates	Per-service "ready" definitions per milestone (domain, API, events, sync, AI, security, perf)
Architectural Freeze Points	Which contracts must freeze before each milestone (FHIR, Sync, Events, AI, Offline)
Team Capacity & Load Model	Team composition per milestone, critical-path teams, parallelization
Slice-Level Risk Register	Risks, severity, impact, mitigation, owner per slice
Slice Release Readiness	Functional, NFR, AI, offline, security, multi-tenant, observability, docs gates per slice
Customer-Facing Packaging	What customers see, buy, pricing tier, onboarding, docs, support per slice
Migration & Backward Compatibility	Schema versioning, tenant migration, FHIR versioning, offline DB migration, AI prompt evolution
Jira Sprint Distribution Rules	Automation rules for distributing epics and stories into Jira sprints when stories have labels
Jira Epic-Based Sprint Ruleset (No Labels)	Sprint distribution driven by parent epic mapping when stories have no Jira labels

0. Guiding Principles

Every slice ships to real clinics. No dormant code. No "phase 2 dumping." Each milestone produces a deployable product increment used by real healthcare workers.
Foundations once, reused N times. Tenant isolation, FHIR gateway, event envelope, AI orchestrator, sync protocol, and Keycloak integration are built in M0 and never re-architected.
Offline-first from M0. This is the highest-priority differentiator. The Electron desktop shell, SQLite local store, sync engine, and conflict resolution are foundation-layer concerns — not bolt-on features. Every subsequent slice inherits offline capability.
AI-first from M1. AI orchestrator ships in M0 as skeleton; clinical AI assistance (note suggestions, drug safety, order recommendations) appears in M1 and deepens every milestone. AI is assistive-first (never autonomous diagnosis).
FHIR is the canonical model. Internal data models map to FHIR R4+ resources. Non-FHIR standards (HL7v2, DICOM) enter via adapters. This is non-negotiable from M0.
Architecture is non-negotiable. DDD boundaries, Clean Architecture, event-only integration, multi-tenant at every layer. Velocity comes from skipping features, never architecture.
Freeze before build. Contracts (FHIR profiles, event schemas, sync protocol, API surfaces) freeze before the code that uses them — see architectural-freeze-points.md.
Security and compliance from day one. HIPAA/GDPR-aligned audit, ABAC, consent management, and PHI encryption are M0 requirements, not post-GA hardening.

1. Executive Roadmap

Milestone	Name	Duration	Cumulative	Customers	Primary Value	Revenue
M0	Platform Foundation	3 mo	M+3	Internal only	Tenant iso, FHIR gateway, event spine, AI orchestrator skeleton, sync engine, Keycloak, Kong, audit, offline shell	—
M1	First Marketable Product (FMP)	3 mo	M+6	3–5 pilot clinics (Afghanistan)	Core EHR: registration, scheduling, chart, notes, vitals, allergies, meds, problems + offline patient intake + AI note assist	Pilot fees / donor-funded
M2	First Sellable Product (FSP)	3 mo	M+9	Paid clinic subscriptions	Orders/CPOE, results, billing, document management + offline orders queue + AI order suggestions	First recurring revenue
M3	Competitive Differentiator	3 mo	M+12	Hospitals + diagnostic centers	Laboratory/LIS, pharmacy, e-prescribing, patient portal, digital communication + AI drug interaction + offline LIS workflows	Enterprise contracts
M4	Full Platform GA	3 mo	M+15	General availability	Radiology/PACS, full billing/claims/insurance, population health, immunizations, care plans, HL7v2 interop, full AI orchestrator	GA pricing, multi-tenant SaaS
M5	Post-GA Expansion	3 mo	M+18	Scale + international	Multi-region, mobile (Expo), SMART on FHIR, national HMIS, advanced AI analytics, white-label	Expansion + government contracts

Fastest path to first revenue: M+9 (M2 complete — core EHR + orders + billing live).

Competitive advantage sequence:

Milestone	Advantage
M0	Offline-first architecture baked in — competitors bolt on later
M1	Only EHR with offline patient intake + AI clinical notes in low-connectivity settings
M2	Full CPOE with offline queuing — no competitor offers this for Afghan/emerging markets
M3	Integrated LIS + pharmacy + e-prescribing with FHIR interop — replaces 3–4 point solutions
M4	Complete EHR platform with PACS, billing, population health — full OpenMRS/Bahmni alternative with modern architecture
M5	National-scale deployment with HMIS, SMART on FHIR, multi-region — government-ready

Month:   0      3          6          9          12         15         18
         │      │          │          │          │          │          │
Stream A │ M0 Platform Foundation     │
Stream A │      │   M1 FMP (Core EHR + Offline + AI Notes)
Stream B │                 │   M2 FSP (Orders + Results + Billing)
Stream B │                            │   M3 Differentiator (LIS + Pharmacy + Portal)
Stream C │                                       │   M4 GA (PACS + Claims + Pop Health)
Stream D │                                                  │   M5 Scale (Mobile + National + Multi-region)

         ▲          ▲                      ▲                            ▲
       Design    First Active           First Revenue               GA & National
      Partners   Clinicians                                          Scale

2. Slice-to-Milestone Mapping

Each slice is independently deployable. Full story-level mapping in slice-epic-story-mapping.md.

Slice	Milestone	Headline	Modules Involved	Epic Count
S0 Foundation	M0	Tenant + FHIR + events + AI skeleton + sync + offline shell + audit	iam, tenant, hierarchy, licensing, access-policy, audit, config-resolver, fhir-gateway, terminology (seed), ai-orchestrator (skeleton), platform-admin, desktop-electron (shell)	~48 epics
S1 Core Clinical	M1	Registration + scheduling + chart + notes + vitals + allergies + meds + problems + offline intake + AI notes	registration, scheduling, provider-directory, facility-management, patient-chart, clinical-notes, vitals, problem-list, allergies, medication-management, desktop-electron (EHR core)	~52 epics
S2 Orders & Diagnostics Entry	M2	CPOE + results + terminology (full) + billing (basic) + document management + offline orders	orders-cpoe, results, terminology (deep), billing (basic), document-management, desktop-electron (orders workflows)	~38 epics
S3 Integrated Care	M3	LIS + pharmacy + e-prescribing + patient portal + digital communication + insurance	laboratory-lis, pharmacy, ghasi-e-prescribing-gateway, patient-portal-api, digital-communication, insurance, desktop-electron (LIS + pharmacy)	~49 epics
S4 Full Platform	M4	PACS + full billing/claims + population health + immunizations + care plans + HL7v2 + full AI	radiology-pacs, billing (full), claims, health-population, immunizations, care-plans, hl7v2-interop, ai-orchestrator (full), desktop-electron (full offline)	~44 epics
S5 National Scale	M5	Multi-region + mobile + SMART on FHIR + HMIS + advanced AI + white-label	All services (hardening), mobile (Expo), FHIR bulk export, national interop, desktop-electron (hardening + a11y + perf)	~remaining epics

3. Critical Path Analysis

3.1 Critical path to working offline-first product (M+6)

  iam ──► tenant ──► hierarchy ──► licensing ──► access-policy ──► PLATFORM SKELETON
    │                                                                       │
    ▼                                                                       ▼
  keycloak (OIDC) ──► kong (gateway) ──► fhir-gateway ──► FHIR FOUNDATION
    │
    ▼
  desktop-electron (shell + IPC + SQLite) ──► sync-engine ──► offline protocol ──► OFFLINE FOUNDATION (M0 end)
    │                                                                                        │
    ▼                                                                                        ▼
  registration ──► scheduling ──► patient-chart ──► clinical-notes ──► CORE CLINICAL (M1)
    │                   │                                │
    ▼                   ▼                                ▼
  provider-directory   facility-management              vitals + allergies + meds + problems
    │
    ▼
  desktop-electron (offline patient intake + offline chart view + offline notes) ──► FIRST OFFLINE EHR (M+6)

3.2 Critical path to first revenue (M+9)

  CORE CLINICAL (M+6) ──► orders-cpoe ──► results ──► DIAGNOSTIC ORDERING (M+8)
                              │                             │
                              ▼                             ▼
                        terminology (full) ──► document-management ──► CLINICAL DOCS
                              │
                              ▼
                        billing (charge capture + invoicing) ──► FIRST REVENUE (M+9)

3.3 Parallelizable workstreams

Can run in parallel from M0	Rationale
Platform (iam, tenant, hierarchy, licensing, access-policy, audit)	Foundation — no clinical dependency
FHIR gateway + terminology (seed)	Standards infrastructure
Desktop Electron shell + SQLite + sync engine	Client-side foundation
AI orchestrator skeleton + prompt registry	AI infrastructure
Kong + Keycloak + config-resolver	Gateway and auth infrastructure
Observability + security tooling	Cross-cutting
Frontend design system (RTL-safe)	No domain dependency

Unlocks at M0 end	Waiting stream
registration, scheduling, provider-directory, facility-management	Depend on tenant + hierarchy + licensing
patient-chart, clinical-notes	Depend on registration + FHIR gateway
Desktop offline workflows	Depend on sync engine + SQLite schema
AI clinical features	Depend on AI orchestrator + prompt registry

Unlocks at M1 end	Waiting stream
orders-cpoe, results	Depend on clinical-notes + medication-management
billing	Depends on orders-cpoe for charge capture
laboratory-lis	Depends on orders-cpoe + results
pharmacy	Depends on medication-management

3.4 Architectural elements that must freeze early

Contract	Freeze by	Impact if changed later
FHIR R4 resource profiles (Patient, Encounter, Observation, etc.)	M0 end	Every service maps to FHIR; changing profiles forces cascade
Event envelope (CloudEvents + NATS subjects)	M0 end	Every service publishes/subscribes; breaking changes cascade
Sync protocol (pull/push/conflict resolution)	M0 end	Desktop SQLite schema and sync engine depend on this
Tenant isolation model (tenantId + hierarchy DAG)	M0 end	Every entity, every query, every API scoped to tenant
Kong gateway routes + plugin chain	M0 end	All clients route through Kong; changing routes breaks clients
Keycloak realm/client structure	M0 end	OIDC tokens carry tenant claims; changing structure breaks auth
Desktop IPC channel contracts	M0 end	Main ↔ renderer communication; changing breaks all desktop features
SQLite local schema (offline store)	M0 end	Offline data; migration path must be additive-only after freeze
AI orchestrator API + prompt format	M0 end	All AI consumers depend on gateway API shape
Audit event schema	M0 end	Compliance; changing audit schema requires migration of tamper-evident logs

See architectural-freeze-points.md for full details.

4. Slicing Strategy

Each slice is documented in detail in slice-epic-story-mapping.md. Per-slice readiness gates in slice-release-readiness.md. Per-slice risks in slice-risk-register.md. Per-slice customer packaging in customer-facing-packaging.md. Per-slice migration rules in migration-backward-compatibility.md.

Summary:

Slice 0 — Platform Foundation (M0)

Multi-tenant platform skeleton with FHIR gateway, event backbone, AI orchestrator skeleton, sync protocol, Keycloak SSO, Kong API gateway, tamper-evident audit, desktop Electron shell with SQLite. No patient-facing product. Customer impact: internal only (pilot clinic agreements in progress).

Capabilities:

Tenant provisioning + hierarchy (DAG org units)
IAM via Keycloak (OIDC/OAuth2, MFA)
RBAC baseline + access-policy skeleton
Module licensing enforcement (ModuleEntitlementGuard)
Tamper-evident audit logging
FHIR R4 gateway (resource routing, search)
NATS JetStream event spine (CloudEvents)
Kong gateway (TLS, JWT validation, rate limiting)
Config-resolver (tenant themes, feature flags)
Terminology seed (ICD-10, LOINC, SNOMED CT basics)
Desktop Electron shell (OIDC login, IPC, SQLite init)
Sync engine (pull/push, conflict resolution, outbox)
AI orchestrator skeleton (gateway, prompt registry, safety classifier, PII redactor)
Platform-admin (user management, tenant ops)

Offline requirements: Desktop shell boots offline, SQLite initialized, sync engine ready to queue mutations. AI requirements: Gateway live with complete, moderate, redact-pii routes. Prompt registry with system prompts. Budget math per tenant.

Slice 1 — Core Clinical (M1)

Core EHR workflows: patient registration, scheduling, provider directory, facility management, patient chart aggregation, clinical documentation, vitals, problem list, allergies, medication management. Desktop offline patient intake, offline chart viewing, offline note drafting. AI clinical note assistance. Customer impact: 3–5 pilot clinics; first real clinicians using the system.

Capabilities:

Patient registration with duplicate detection + multi-identifier
Appointment scheduling with provider calendars
Provider directory + facility/department management
Longitudinal patient chart (medical/surgical/family history)
SOAP clinical notes with templates
Vital signs capture + trending + pediatric growth charts
Problem list (active/historical diagnoses)
Allergy recording with severity + reaction tracking
Medication prescribing with drug-drug interaction checks
Desktop: offline patient intake → sync queue → server
Desktop: offline chart read (cached FHIR bundles)
Desktop: offline clinical note drafting → sync on reconnect
AI: clinical note auto-suggestions from chief complaint
AI: drug safety alert enrichment

Offline requirements: Patient intake works fully offline. Chart viewing works from cached data. Clinical notes draft offline and sync. Vitals capture offline. All mutations idempotent with client mutation IDs. AI requirements: AI note assistance via cloud (graceful degradation when offline). Drug interaction checks run locally when AI orchestrator unavailable.

Slice 2 — Orders & Diagnostics Entry (M2)

CPOE for lab/radiology/nursing orders, results management with trending and critical alerts, full terminology service, basic billing (charge capture + invoicing), document management. Customer impact: first paying clinics; clinicians can order labs and see results.

Capabilities:

Lab, radiology, nursing, diet, therapy, consultation orders
Order safety checks (duplicate, allergy cross-check)
Results reception, trending, critical-value alerts
Full terminology (ICD-10, LOINC, SNOMED CT, RxNorm)
Charge capture per encounter
Invoice generation + patient statements
PDF template management + document scanning
Desktop: offline order queuing with safety checks
Desktop: offline results viewing from cache
AI: order recommendation based on diagnosis
AI: result interpretation assistance

Offline requirements: Orders queue offline with local safety checks. Results viewable from cache. Charge capture queues offline. AI requirements: AI order suggestions. AI result interpretation. AI-assisted coding (ICD-10).

Slice 3 — Integrated Care (M3)

Laboratory information system, pharmacy dispensing, e-prescribing gateway, patient portal, digital communication (messaging + notifications + virtual care), insurance eligibility. Customer impact: hospitals and diagnostic centers; integrated care workflows replace point solutions.

Capabilities:

LIS: specimen tracking, accessioning, worklists, instrument interfaces, QC
Pharmacy: dispensing workflows, inventory awareness
E-prescribing: national medication spine (FHIR MedicationRequest/Dispense)
Patient portal: record access (consent-sliced), appointment requests, results viewing
Digital communication: secure messaging, outbound notifications, virtual visits (Jitsi)
Insurance: eligibility verification, pre-authorization
Desktop: LIS worklist + result entry offline
Desktop: pharmacy dispensing offline queue
AI: drug interaction AI for pharmacists
AI: clinical decision support alerts

Offline requirements: LIS worklists and specimen tracking work offline. Pharmacy dispensing queues offline. Messaging queues offline. AI requirements: AI drug interaction analysis. AI clinical decision support. AI-powered search in patient portal.

Slice 4 — Full Platform (M4)

Radiology/PACS with DICOM integration, full billing + claims + insurance, population health + HMIS, immunizations, care plans, HL7v2 interoperability, full AI orchestrator (cloud + local ONNX). Customer impact: general availability; feature-complete EHR platform.

Capabilities:

PACS: imaging orders, DICOM/DICOMweb, viewer, report lifecycle
Full billing: patient accounting, payment plans, financial assistance
Claims: generation, submission, denial tracking, appeals
Population health: cohorts, registries, quality metrics, HMIS reporting
Immunizations: schedule management, catch-up, reporting
Care plans: templates, goal tracking, team coordination
HL7v2: ADT/ORM/ORU/SIU adapters (inbound/outbound)
Full AI orchestrator: local ONNX models + cloud inference
Desktop: full offline capability for all workflows
Desktop: local ONNX inference for AI features

Offline requirements: All clinical workflows functional offline. PACS viewer works with cached images. Claims queue offline. AI requirements: Local ONNX models for offline AI. Cloud AI for complex analysis. Population health AI insights.

Slice 5 — National Scale (M5)

Multi-region deployment, mobile app (Expo React Native), SMART on FHIR, FHIR Bulk Data Access, national HMIS integration, advanced AI analytics, white-label. Customer impact: national-scale deployments; government contracts; international expansion.

Capabilities:

Multi-region data residency + deployment
Mobile: Expo React Native with OIDC/PKCE, push notifications
SMART on FHIR: third-party app integration
FHIR Bulk Data Access: secondary use, research
National HMIS: indicator catalog, aggregate reporting
Advanced AI: population health predictions, quality improvement
White-label: full theming per tenant hierarchy node
Desktop: hardening + a11y + performance + lazy bundles
Localization depth: Dari, Pashto, Arabic RTL, Hijri/Solar Hijri calendars

Offline requirements: Mobile offline support. Multi-device sync. Remote wipe capability. AI requirements: Predictive analytics. Population health AI insights. AI-powered HMIS reporting.

5. Engineering Roadmap (Detailed)

M0 — Platform Foundation (Months 1–3)

Capabilities delivered:

Multi-tenant platform with hierarchy-based org units
Keycloak OIDC with MFA support
RBAC + ABAC baseline via access-policy service
Module licensing enforcement across all services
Tamper-evident audit logging
FHIR R4 gateway with resource routing
NATS JetStream event spine with CloudEvents
Kong API gateway (DB-less) with JWT validation
Config-resolver for tenant-specific configuration
Terminology seed data (ICD-10, LOINC, SNOMED CT)
Electron desktop shell with OIDC + IPC + SQLite
Sync engine (pull/push/conflict resolution/outbox)
AI orchestrator skeleton (gateway routes, prompt registry, safety)
Platform-admin (tenant ops, user management)

Microservices involved: iam, tenant, hierarchy, licensing, access-policy, audit, config-resolver, fhir-gateway, terminology, ai-orchestrator, platform-admin

Frontend surfaces: Desktop Electron shell (login, tenant selector, capability map), platform-admin web (basic)

Offline-first features:

Desktop boots offline
SQLite initialized with tenant-scoped schema
Sync engine queues mutations in outbox
Conflict resolution policies defined per aggregate
Idempotency via client mutation IDs
PHI encrypted at rest in SQLite

AI-first features:

AI gateway live (/ai/complete, /ai/moderate, /ai/redact-pii)
Prompt registry with versioned system prompts
Safety classifier harness
PII redactor (pre-cloud-call sanitization)
Per-tenant AI budget tracking
Provenance invariant (all AI outputs tagged)

Dependencies: None (foundation layer)

Risks + mitigations:

Risk	Severity	Mitigation
Keycloak configuration complexity	S2	Automated realm provisioning scripts; documented playbook
SQLite schema freeze too early	S2	Additive-only migration strategy; version field in schema
NATS JetStream operational maturity	S3	Dedicated SRE spike in weeks 1–2; fallback to Redis Streams
FHIR profile disagreements	S2	Freeze profiles with clinical SME review before M0 end

Acceptance criteria:

Two-tenant CI suite passes (cross-tenant isolation verified)
OIDC login → Electron desktop → SQLite init → offline boot verified
Sync engine round-trip: create offline → sync → verify on server → pull to another device
AI gateway responds to /ai/complete with mocked provider
Audit log tamper detection verified (hash chain integrity)
Kong routes all services; direct service access blocked
Event spine: publish from service A → consume in service B verified
Licensing guard returns 422 for unlicensed module access

Release readiness: See slice-release-readiness.md § S0.

M1 — First Marketable Product (Months 4–6)

Capabilities delivered:

Patient registration with duplicate detection
Appointment scheduling with multi-provider calendars
Provider directory and facility management
Longitudinal patient chart aggregation
SOAP clinical documentation with templates
Vital signs capture, trending, growth charts
Problem list management
Allergy recording with safety alerts
Medication management with drug safety checks
Offline patient intake → sync → server
AI clinical note assistance

Microservices involved: registration, scheduling, provider-directory, facility-management, patient-chart, clinical-notes, vitals, problem-list, allergies, medication-management

Frontend surfaces: Desktop Electron (EHR core: registration, scheduling, chart, notes, vitals, meds), ehr-web (core clinical)

Offline-first features:

Offline patient registration (draft → queue → sync)
Offline appointment viewing (cached schedules)
Offline chart browsing (FHIR bundle cache)
Offline clinical note drafting → sync on reconnect
Offline vital signs capture
Offline allergy/problem recording
Conflict resolution for concurrent edits (LWW + server authority)
Stale-data indicators in UI

AI-first features:

AI clinical note auto-suggestions (SOAP from chief complaint)
AI drug-allergy cross-check enrichment
AI terminology code suggestions (ICD-10 from free text)
Graceful degradation when AI unavailable (feature hidden, not broken)

Dependencies: M0 complete (platform foundation, sync engine, AI gateway)

Risks + mitigations:

Risk	Severity	Mitigation
Clinical workflow complexity	S2	Clinical SME embedded in team; iterative pilot feedback
Offline conflict resolution edge cases	S1	Server-authority model; manual conflict UI for rare cases
Drug safety database licensing	S2	RxNorm (free) as baseline; commercial DB as optional add-on
RTL layout bugs in clinical forms	S3	RTL testing suite in CI; Dari/Pashto test data
Pilot clinic connectivity issues	S2	Pre-deployment connectivity audit; sync tuning per site

Acceptance criteria:

Register patient offline → sync → verify on server
Schedule appointment → check-in → start encounter → document notes → sign
Vital signs captured offline → trending chart renders with cached + synced data
Drug-drug interaction alert fires for known interaction pair
AI note suggestion appears within 3s of chief complaint entry
Full workflow functional with 10-minute network outage (airplane mode test)
RTL layout correct for Dari/Pashto in all clinical forms
3 pilot clinics operational for 2 weeks with <5 critical bugs

M2 — First Sellable Product (Months 7–9)

Capabilities delivered:

CPOE: lab, radiology, nursing, diet, consultation orders
Order safety checks (duplicate, allergy, interaction)
Results management with trending and critical alerts
Full terminology service (ICD-10, LOINC, SNOMED CT, RxNorm)
Basic billing: charge capture, invoice generation
Document management: templates, scanning, PDF generation
Offline order queuing with local safety checks
AI order recommendations

Microservices involved: orders-cpoe, results, terminology, billing (basic), document-management

Frontend surfaces: Desktop Electron (orders panel, results viewer, billing), ehr-web (orders, results, billing)

Offline-first features:

Orders queue offline with local safety validation
Results viewable from local cache
Charge capture records offline
Document viewing offline (cached PDFs)

AI-first features:

AI order recommendations based on diagnosis + history
AI result interpretation assistance
AI-assisted ICD-10/CPT coding

Dependencies: M1 complete (core clinical workflows)

Risks + mitigations:

Risk	Severity	Mitigation
Order safety check completeness	S1	Phased rollout: basic checks M2, full CDS M3–M4
Billing localization (AFN/AED/tax)	S2	Multi-currency from day one; tax rules configurable
Results integration complexity	S2	FHIR DiagnosticReport canonical model; adapter per lab system
Offline order safety with stale data	S1	Timestamp-aware checks; warning UI for stale reference data

Acceptance criteria:

Place lab order → route to pending → result posted → trending chart updated
Critical value alert fires and requires acknowledgment
Charge capture from completed encounter → invoice generated
Order placed offline → synced → routed correctly
AI suggests relevant orders for common diagnosis
Billing invoice in AFN and AED with correct formatting
First 3 paying clinic subscriptions signed

M3 — Competitive Differentiator (Months 10–12)

Capabilities delivered:

Laboratory LIS (specimen tracking, worklists, QC, instruments)
Pharmacy dispensing workflows
E-prescribing gateway (FHIR MedicationRequest ↔ MedicationDispense)
Patient portal (record access, appointment requests, results)
Digital communication (messaging, notifications, virtual care)
Insurance eligibility and pre-authorization
Offline LIS and pharmacy workflows
AI clinical decision support

Microservices involved: laboratory-lis, pharmacy, ghasi-e-prescribing-gateway, patient-portal-api, digital-communication, insurance

Frontend surfaces: Desktop (LIS worklist, pharmacy), ehr-web (full), patient-portal web, lab-portal web, pharmacy-portal web

Offline-first features:

LIS worklist + result entry offline
Pharmacy dispensing queue offline
Messaging queue offline
Prescription queue offline

AI-first features:

AI drug interaction analysis for pharmacists
AI clinical decision support alerts
AI-powered search in patient portal
AI triage for incoming messages

Dependencies: M2 complete (orders + results infrastructure)

Risks + mitigations:

Risk	Severity	Mitigation
LIS instrument integration diversity	S2	Standard ASTM/HL7 interface; adapter SDK for custom instruments
E-prescribing national spine readiness	S1	Mock spine for development; parallel track with MoPH
Patient portal data consent complexity	S2	Consent-sliced FHIR access; default deny for sensitive categories
Virtual care (Jitsi) reliability	S3	Jitsi self-hosted with fallback; video optional for M3

Acceptance criteria:

Specimen collected → accessioned → tested → result verified → auto-posted to chart
Prescription → e-prescribing gateway → pharmacy → dispensed → recorded
Patient views own records in portal (consent-sliced)
Secure message: provider → patient → response chain
Insurance eligibility check returns coverage details
LIS worklist functional in 30-minute offline window
First enterprise hospital contract signed

M4 — Full Platform GA (Months 13–15)

Capabilities delivered:

Radiology/PACS (DICOM, imaging worklists, viewer, reports)
Full billing (patient accounting, payment plans, statements)
Claims (generation, submission, denial tracking, appeals)
Population health (cohorts, registries, quality metrics, HMIS)
Immunizations (schedule, catch-up, reporting)
Care plans (templates, goals, team coordination)
HL7v2 interoperability (ADT/ORM/ORU/SIU adapters)
Full AI orchestrator (local ONNX + cloud)
Full desktop offline for all workflows

Microservices involved: radiology-pacs, billing (full), claims, health-population, immunizations, care-plans, hl7v2-interop, ai-orchestrator (full)

Frontend surfaces: All portals fully operational

Offline-first features:

Full offline capability for all clinical workflows
PACS viewer with cached DICOM images
Claims queue offline
Population health dashboards from cached data
Local ONNX AI models for offline inference

AI-first features:

Local ONNX models (note classification, code suggestion)
Cloud AI for complex clinical analysis
Population health AI insights (risk stratification, trends)
AI-assisted quality metric computation
AI immunization schedule recommendations

Dependencies: M3 complete (LIS, pharmacy, patient portal infrastructure)

Acceptance criteria:

Imaging order → DICOM study received → viewer displays → report finalized
Claim generated → submitted → denial tracked → appeal workflow
Population health cohort defined → quality metric computed → HMIS report generated
Immunization schedule generated for child with catch-up recommendations
HL7v2 ADT message received → patient record created/updated
Local ONNX model inference works in airplane mode
GA announcement published; SLA agreements in place

M5 — Post-GA Expansion (Months 16–18)

Capabilities delivered:

Multi-region data residency
Mobile app (Expo React Native) with OIDC/PKCE
SMART on FHIR (third-party app integration)
FHIR Bulk Data Access (research, secondary use)
National HMIS integration (indicator catalog)
Advanced AI (predictive analytics, population insights v2)
White-label (full theming per hierarchy node)
Desktop hardening (a11y, perf, lazy bundles)
Full localization (Dari, Pashto, Arabic, Hijri/Solar Hijri)

Microservices involved: All services (hardening + scale)

Frontend surfaces: Mobile app, all web portals (hardened), desktop (hardened)

Offline-first features:

Mobile offline support with background sync
Multi-device sync with conflict UI
Remote device wipe
Offline bundle management (pin/unpin/clear)

AI-first features:

Predictive analytics (disease outbreak, resource needs)
Population health AI v2 (board summaries, trend detection)
AI-powered HMIS report generation
AI content search (semantic)

Dependencies: M4 complete (full platform)

Acceptance criteria:

Mobile app: login → view chart → receive push notification
SMART on FHIR: third-party app launches in EHR context
FHIR Bulk Data: export full tenant data set
HMIS report generated matching national indicator catalog
Multi-region: tenant data resides in specified region
Remote wipe: device data cleared within 5 minutes of command
Government pilot deployment operational

6. Service Readiness (Summary)

Full per-service, per-milestone readiness in service-readiness-gates.md. Each service has eight canonical gates:

Domain ready — aggregates implemented with invariants; pure TS; unit-tested.
API ready — FHIR + REST endpoints published + versioned; idempotency + problem-json + cursor pagination.
Events ready — subjects + schemas registered; outbox + inbox; contract tests.
Sync ready — applicable services register with sync-engine; conflict policy declared; offline schemas frozen.
AI ready — consumers use AI orchestrator port; provenance invariant enforced; prompts registered + eval'd.
Observability ready — SLOs defined; OTel end-to-end; dashboards; runbook.
Performance ready — load test meeting target; degradation plan documented.
Security ready — tenant isolation test green; threat-model updated; pen-test findings closed; audit events emitted; PHI encryption verified.

Service	M0	M1	M2	M3	M4	M5
iam	L3	L3	L3	L4	L4	L4
tenant	L3	L3	L3	L4	L4	L4
hierarchy	L3	L3	L3	L4	L4	L4
licensing	L3	L3	L3	L4	L4	L4
access-policy	L2	L3	L3	L4	L4	L4
audit	L3	L3	L3	L4	L4	L4
config-resolver	L3	L3	L3	L3	L4	L4
fhir-gateway	L2	L3	L3	L4	L4	L4
terminology	L2	L3	L4	L4	L4	L4
ai-orchestrator	L2	L3	L3	L3	L4	L4
platform-admin	L2	L3	L3	L3	L4	L4
registration	—	L3	L3	L4	L4	L4
scheduling	—	L3	L3	L4	L4	L4
provider-directory	—	L3	L3	L4	L4	L4
facility-management	—	L3	L3	L4	L4	L4
patient-chart	—	L3	L3	L4	L4	L4
clinical-notes	—	L3	L3	L4	L4	L4
vitals	—	L3	L3	L4	L4	L4
problem-list	—	L3	L3	L4	L4	L4
allergies	—	L3	L3	L4	L4	L4
medication-management	—	L3	L3	L4	L4	L4
orders-cpoe	—	—	L3	L3	L4	L4
results	—	—	L3	L3	L4	L4
billing	—	—	L2	L3	L4	L4
document-management	—	—	L3	L3	L4	L4
laboratory-lis	—	—	—	L3	L4	L4
pharmacy	—	—	—	L3	L4	L4
ghasi-e-prescribing-gw	—	—	—	L3	L4	L4
patient-portal-api	—	—	—	L3	L4	L4
digital-communication	—	—	—	L3	L4	L4
insurance	—	—	—	L2	L4	L4
radiology-pacs	—	—	—	—	L3	L4
claims	—	—	—	—	L3	L4
health-population	—	—	—	—	L3	L4
immunizations	—	—	—	—	L3	L4
care-plans	—	—	—	—	L3	L4
hl7v2-interop	—	—	—	—	L3	L4
seed-runner	L2	L3	L3	L3	L3	L3

Level guide: L1 = skeleton-tested, not customer-facing. L2 = internally usable. L3 = customer-facing meeting target SLOs. L4 = feature-complete per spec. Gate definitions in service-readiness-gates.md.

7. Architectural Freeze Points (Summary)

See architectural-freeze-points.md for detail.

Contract	Frozen before	Owner	Evolution rule
FHIR R4 resource profiles	M0 end	Architecture	Profile additions OK; breaking → new profile version
`EventEnvelope` (CloudEvents) + NATS subjects	M0 end	Platform	Only additive; breaking → new `vN`
Tenant isolation model (tenantId + hierarchy DAG)	M0 end	Platform	Never change shape
Sync protocol (pull/push/resolve + vector clocks)	M0 end	Platform	Additive only; breaking → `/sync/v2/`
Kong route structure + plugin chain	M0 end	Platform	New routes additive; plugin removal requires migration
Keycloak realm/client/claim structure	M0 end	IAM	Additive claims only; realm structure stable
Desktop IPC channel contracts	M0 end	Desktop	New channels additive; existing channels stable
SQLite local schema (offline store)	M0 end	Desktop + Sync	Additive columns only; breaking → migration script
AI orchestrator API + prompt format	M0 end	AI	Additive endpoints; prompt versions append-only
Audit event schema	M0 end	Security	Immutable (tamper-evident chain depends on schema)
FHIR search parameters per resource	M1 end	FHIR Gateway	New params additive; existing params stable
Offline conflict resolution matrix	M0 end	Sync + DDD	Adding aggregates yes; changing policy rarely
Error code registry	M1 end	Platform	Codes never renamed; new codes additive
HL7v2 message mapping profiles	M3 end	Interop	ADL conformance is the contract
DICOM/DICOMweb integration profile	M4 start	Imaging	IHE profiles stable

8. Competitive Positioning

How the sequence beats competitors

vs. OpenMRS / Bahmni / GNU Health (open-source EHRs):

M0: Modern microservices architecture with multi-tenancy (they are monoliths)
M1: Offline-first with SQLite sync (they require constant connectivity or custom forks)
M2: AI-assisted ordering (they have no AI capability)
M3: Integrated LIS + pharmacy (they require separate systems)
M4: Full FHIR-native platform (they bolt on FHIR as an afterthought)

vs. DHIS2 / OpenHIM (national health platforms):

M0–M1: Clinical EHR capability (they are reporting/HIE platforms, not clinical systems)
M4: Population health + HMIS feeds (we produce the data they aggregate)
M5: National interoperability with FHIR Bulk (complementary, not competitive)

vs. Commercial EHRs (Epic, Cerner, Meditech):

M0–M1: Designed for low-connectivity (they assume reliable internet)
M1: Localized for Afghanistan/UAE (RTL, Dari, Pashto, Solar Hijri)
M2: Affordable per-clinic pricing (they target large hospital systems)
M3: Integrated e-prescribing for emerging markets (they target developed market pharmacies)
M5: Open FHIR-native (they are proprietary with FHIR adapters)

The moat is: offline-first + AI-first + FHIR-native + localized for underserved markets. No competitor has all four. The sequence ensures each milestone deepens the moat.

9. Timeline (ASCII Gantt)

Month:  1   2   3   4   5   6   7   8   9   10  11  12  13  14  15  16  17  18
        ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤

 M0 Platform Foundation
        ████████████
        IAM+Tenant+Hierarchy ████
        FHIR Gateway+Events  ████
        Sync+Offline Shell   ████████
        AI Orchestrator Skel ████████
        Audit+Security       ████████████
        Kong+Config          ████████

 M1 Core Clinical (FMP)
                    ████████████
        Registration+Sched       ████████
        Chart+Notes+Vitals       ████████████
        Allergies+Meds+Probs        ████████
        Desktop Offline EHR      ████████████
        AI Clinical Notes           ████████

 M2 Orders & Billing (FSP)
                            ████████████
        Orders-CPOE              ████████████
        Results+Trending             ████████
        Terminology (full)       ████████
        Billing (basic)              ████████████
        Document Mgmt                ████████
        Desktop Offline Orders       ████████

 M3 Integrated Care
                                    ████████████
        Laboratory-LIS                   ████████████
        Pharmacy+E-Prescribing           ████████████
        Patient Portal                   ████████████
        Digital Communication                ████████
        Insurance                            ████████
        Desktop LIS+Pharmacy             ████████████

 M4 Full Platform (GA)
                                                ████████████
        Radiology-PACS                               ████████████
        Billing+Claims (full)                        ████████████
        Population Health+HMIS                       ████████████
        Immunizations+Care Plans                     ████████
        HL7v2 Interop                                    ████████
        AI Orchestrator (full)                       ████████████
        Desktop Full Offline                         ████████████

 M5 Post-GA Expansion
                                                            ████████████
        Multi-region                                             ████████████
        Mobile (Expo)                                            ████████████
        SMART on FHIR+Bulk                                       ████████
        National HMIS                                            ████████████
        Advanced AI                                                  ████████
        White-label+Hardening                                    ████████████

        ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
        ▲           ▲               ▲                   ▲                   ▲
      Design     First Pilot     First $$$           GA Launch           National
     Partners    Clinicians     (Revenue)                                 Scale

Milestone Decision Gates

Gate	Decision	Stakeholders
M0 → M1	Platform isolation verified; sync E2E proven; freeze points accepted	Architecture, Security, Product
M1 → M2	3+ pilot clinics operational 2+ weeks; <5 critical bugs; offline workflow proven	Product, Clinical SME, Ops
M2 → M3	First revenue milestone hit; orders + results stable; billing functional	Product, Finance, CEO
M3 → M4	Hospital pilot operational; LIS + pharmacy integrated; enterprise contract signed	Product, Sales, Clinical
M4 → M5	GA readiness review passed; SLA agreements in place; all critical workflows offline	Product, Engineering, Legal

10. Cross-Cutting Checklists

Security (every milestone)

No hardcoded secrets in source
PHI encrypted at rest (server + SQLite)
Tenant isolation test suite green
RBAC + ABAC policies reviewed
Audit log integrity verified
Kong rate limiting configured
Keycloak realm hardened

Offline (every milestone)

Airplane-mode E2E test passes
Sync round-trip verified (create offline → sync → pull)
Conflict resolution tested (concurrent edits)
Stale-data indicators visible
Idempotency verified (duplicate mutation rejected)
SQLite encryption verified

AI (every milestone)

Provenance tag on all AI outputs
Safety classifier active
PII redaction before cloud calls
Per-tenant budget enforcement
Graceful degradation when AI unavailable
Prompt regression tests pass

Localization (every milestone)

RTL layout correct (Dari, Pashto, Arabic)
Calendar rendering (Gregorian + Hijri + Solar Hijri)
Currency formatting (AFN, AED)
Timezone handling (Asia/Kabul, Asia/Dubai)
PDF output RTL-safe with embedded fonts

Companion Documents​

0. Guiding Principles​

1. Executive Roadmap​

2. Slice-to-Milestone Mapping​

3. Critical Path Analysis​

3.1 Critical path to working offline-first product (M+6)​

3.2 Critical path to first revenue (M+9)​

3.3 Parallelizable workstreams​

3.4 Architectural elements that must freeze early​

4. Slicing Strategy​

Slice 0 — Platform Foundation (M0)​

Slice 1 — Core Clinical (M1)​

Slice 2 — Orders & Diagnostics Entry (M2)​

Slice 3 — Integrated Care (M3)​

Slice 4 — Full Platform (M4)​

Slice 5 — National Scale (M5)​

5. Engineering Roadmap (Detailed)​

M0 — Platform Foundation (Months 1–3)​

M1 — First Marketable Product (Months 4–6)​

M2 — First Sellable Product (Months 7–9)​

M3 — Competitive Differentiator (Months 10–12)​

M4 — Full Platform GA (Months 13–15)​

M5 — Post-GA Expansion (Months 16–18)​

6. Service Readiness (Summary)​

7. Architectural Freeze Points (Summary)​

8. Competitive Positioning​

How the sequence beats competitors​

9. Timeline (ASCII Gantt)​

Milestone Decision Gates​

10. Cross-Cutting Checklists​

Security (every milestone)​

Offline (every milestone)​

AI (every milestone)​

Localization (every milestone)​

Companion Documents

0. Guiding Principles

1. Executive Roadmap

2. Slice-to-Milestone Mapping

3. Critical Path Analysis

3.1 Critical path to working offline-first product (M+6)

3.2 Critical path to first revenue (M+9)

3.3 Parallelizable workstreams

3.4 Architectural elements that must freeze early

4. Slicing Strategy

Slice 0 — Platform Foundation (M0)

Slice 1 — Core Clinical (M1)

Slice 2 — Orders & Diagnostics Entry (M2)

Slice 3 — Integrated Care (M3)

Slice 4 — Full Platform (M4)

Slice 5 — National Scale (M5)

5. Engineering Roadmap (Detailed)

M0 — Platform Foundation (Months 1–3)

M1 — First Marketable Product (Months 4–6)

M2 — First Sellable Product (Months 7–9)

M3 — Competitive Differentiator (Months 10–12)

M4 — Full Platform GA (Months 13–15)

M5 — Post-GA Expansion (Months 16–18)

6. Service Readiness (Summary)

7. Architectural Freeze Points (Summary)

8. Competitive Positioning

How the sequence beats competitors

9. Timeline (ASCII Gantt)

Milestone Decision Gates

10. Cross-Cutting Checklists

Security (every milestone)

Offline (every milestone)

AI (every milestone)

Localization (every milestone)