Service Readiness Gates
Execution-layer artifact. Companion to ROADMAP.md. Defines "ready" for each service at each milestone.
1. Level Definitions
| Level | Name | Definition | Escalation |
|---|---|---|---|
| L0 | Not started | No code exists | — |
| L1 | Skeleton | Domain model + basic API; unit tests only; not customer-facing | Team lead reviews |
| L2 | Internal | Functional for internal use; integration tests; staging-deployable | Eng manager reviews |
| L3 | Customer-facing MVP | Meets target SLOs; security review passed; FHIR conformance verified; offline sync operational (if applicable); production-deployable | Architecture + Security sign-off |
| L4 | Feature-complete | All spec FRs implemented; full test coverage (80%+); pen-test clean; load-tested; runbook complete | VP Eng sign-off for GA |
Escalation rule: A service cannot regress. If a service was L3 at M1, it must remain L3+ at M2. Regressions require incident review.
2. Eight Canonical Gates
G1 — Domain Ready
- All aggregate roots have invariants codified in constructor + command methods.
- Pure TypeScript domain layer; no framework imports.
- FHIR resource mapping verified (if service owns FHIR resources).
- Unit test coverage ≥ 80% on domain layer.
- Tenant scoping enforced on all entities.
G2 — API Ready
- FHIR endpoints (if applicable) conform to FHIR R4 spec.
- REST endpoints follow API baseline (OpenAPI 3.1, problem-json errors, cursor pagination).
- Idempotency on all state-changing endpoints.
- Versioned (URL path or header).
- Contract tests against API specs.
G3 — Events Ready
- All domain events published via NATS JetStream outbox.
- CloudEvents envelope with correct
source,type,tenantId. - Event schemas registered in schema registry.
- All consumers idempotent (inbox pattern).
- DLQ configured for failed consumption.
- Contract tests between publisher and known consumers.
G4 — Sync Ready (applicable services only)
- Service registers replicable aggregates with sync engine.
- Conflict resolution policy declared per aggregate (LWW, server-authority, merge).
- SQLite offline schema defined and frozen.
- Idempotent mutation replay verified.
- Device binding enforced (only registered devices sync).
- Stale-data age propagated to UI.
G5 — AI Ready (applicable services only)
- All AI consumption goes through
AIClientport → AI orchestrator gateway. - Provenance invariant enforced (model, prompt version, timestamp on all AI outputs).
- Prompts registered + versioned in prompt registry.
- Safety classifier active for AI-generated content.
- PII redaction before cloud AI calls.
- Graceful degradation when AI unavailable.
- Per-tenant AI budget respected.
G6 — Observability Ready
- SLOs defined (latency p50/p95/p99, error rate, availability).
- OTel instrumentation end-to-end (trace ID propagation).
- Prometheus metrics exported.
- Grafana dashboard created.
- Runbook written (alert → diagnosis → remediation).
- Health probes (
/health/live,/health/ready) functional.
G7 — Performance Ready
- Load test meeting SLO targets (API p95 < 500ms, page load < 2s).
- Degradation plan documented (what happens under 2x, 5x, 10x load).
- Connection pooling configured.
- Caching strategy documented and implemented.
- No N+1 queries.
G8 — Security Ready
- Tenant isolation test green (cross-tenant access attempt rejected).
- Threat model updated for service's attack surface.
- Pen-test findings closed (if applicable at this milestone).
- Audit events emitted for all PHI access/modification.
- PHI encrypted at rest.
- Kong JWT validation on all public routes.
- Rate limiting configured.
- No hardcoded secrets.
- ModuleEntitlementGuard on all public controllers.
3. Service × Milestone × Level Matrix
Platform Services
| Service | M0 | M1 | M2 | M3 | M4 | M5 |
|---|---|---|---|---|---|---|
| iam | G1–G8: L3 | L3 | L3 | L4 (MFA depth) | L4 | L4 |
| tenant | G1–G8: L3 | L3 | L3 | L4 | L4 | L4 |
| hierarchy | G1–G8: L3 | L3 | L3 | L4 | L4 | L4 |
| licensing | G1–G8: L3 | L3 | L3 | L4 | L4 | L4 |
| access-policy | G1–G3,G6–G8: L2; G4–G5: N/A | L3 | L3 | L4 (ABAC full) | L4 | L4 |
| audit | G1–G3,G6–G8: L3 | L3 | L3 | L4 | L4 | L4 |
| config-resolver | G1–G3,G6–G8: L3 | L3 | L3 | L3 | L4 | L4 |
| fhir-gateway | G1–G2: L2; G6–G8: L2 | L3 | L3 | L4 | L4 | L4 |
| terminology | G1–G2: L2 | L3 (seed) | L4 (full) | L4 | L4 | L4 |
| ai-orchestrator | G1–G3,G5: L2 | L3 | L3 | L3 | L4 (ONNX) | L4 |
| platform-admin | G1–G2: L2 | L3 | L3 | L3 | L4 | L4 |
Clinical Services
| Service | M0 | M1 | M2 | M3 | M4 | M5 |
|---|---|---|---|---|---|---|
| registration | — | G1–G4,G6–G8: L3 | L3 | L4 | L4 | L4 |
| scheduling | — | G1–G4,G6–G8: L3 | L3 | L4 | L4 | L4 |
| provider-directory | — | G1–G3,G6–G8: L3 | L3 | L4 | L4 | L4 |
| facility-management | — | G1–G3,G6–G8: L3 | L3 | L4 | L4 | L4 |
| patient-chart | — | G1–G4,G6–G8: L3 | L3 | L4 | L4 | L4 |
| clinical-notes | — | G1–G5,G6–G8: L3 | L3 | L4 | L4 | L4 |
| vitals | — | G1–G4,G6–G8: L3 | L3 | L4 | L4 | L4 |
| problem-list | — | G1–G3,G6–G8: L3 | L3 | L4 | L4 | L4 |
| allergies | — | G1–G3,G6–G8: L3 | L3 | L4 | L4 | L4 |
| medication-management | — | G1–G5,G6–G8: L3 | L3 | L4 | L4 | L4 |
Diagnostic & Financial Services
| Service | M0 | M1 | M2 | M3 | M4 | M5 |
|---|---|---|---|---|---|---|
| orders-cpoe | — | — | G1–G4,G6–G8: L3 | L3 | L4 | L4 |
| results | — | — | G1–G4,G6–G8: L3 | L3 | L4 | L4 |
| billing | — | — | G1–G2,G6–G8: L2 | L3 | L4 | L4 |
| document-management | — | — | G1–G4,G6–G8: L3 | L3 | L4 | L4 |
| laboratory-lis | — | — | — | G1–G4,G6–G8: L3 | L4 | L4 |
| pharmacy | — | — | — | G1–G4,G6–G8: L3 | L4 | L4 |
| ghasi-e-prescribing-gw | — | — | — | G1–G3,G6–G8: L3 | L4 | L4 |
| insurance | — | — | — | G1–G2,G6–G8: L2 | L4 | L4 |
Engagement & Population Health Services
| Service | M0 | M1 | M2 | M3 | M4 | M5 |
|---|---|---|---|---|---|---|
| patient-portal-api | — | — | — | G1–G4,G6–G8: L3 | L4 | L4 |
| digital-communication | — | — | — | G1–G3,G6–G8: L3 | L4 | L4 |
| radiology-pacs | — | — | — | — | G1–G4,G6–G8: L3 | L4 |
| claims | — | — | — | — | G1–G3,G6–G8: L3 | L4 |
| health-population | — | — | — | — | G1–G3,G5–G8: L3 | L4 |
| immunizations | — | — | — | — | G1–G3,G6–G8: L3 | L4 |
| care-plans | — | — | — | — | G1–G3,G6–G8: L3 | L4 |
| hl7v2-interop | — | — | — | — | G1–G3,G6–G8: L3 | L4 |
Desktop & Infrastructure
| Service | M0 | M1 | M2 | M3 | M4 | M5 |
|---|---|---|---|---|---|---|
| desktop-electron | DESK-01,02: L3 | DESK-03: L3 | +orders: L3 | +LIS,pharm: L3 | +imaging,billing,pophealth,AI: L3 | DESK-11: L4 |
| seed-runner | L2 | L3 | L3 | L3 | L3 | L3 |
4. Milestone Exit Summary
| Milestone | Services that must reach L3+ | Services that must reach L4 |
|---|---|---|
| M0 | iam, tenant, hierarchy, licensing, audit, config-resolver, desktop-electron (shell+sync) | — |
| M1 | + registration, scheduling, provider-directory, facility-management, patient-chart, clinical-notes, vitals, problem-list, allergies, medication-management, fhir-gateway, terminology, ai-orchestrator | — |
| M2 | + orders-cpoe, results, document-management | terminology |
| M3 | + laboratory-lis, pharmacy, ghasi-e-prescribing-gw, patient-portal-api, digital-communication | iam, tenant, hierarchy, licensing, registration, scheduling, provider-directory, facility-management, patient-chart, clinical-notes, vitals, problem-list, allergies, medication-management |
| M4 | + radiology-pacs, claims, health-population, immunizations, care-plans, hl7v2-interop, billing (full), insurance (full) | All M3 L4 services + orders-cpoe, results, document-management, laboratory-lis, pharmacy, ghasi-e-prescribing-gw, ai-orchestrator |
| M5 | — | All services L4 |
5. Governance
Change control
- Level assignments reviewed at each milestone gate.
- Level change requires PR to this document with justification.
- Architecture team owns the matrix; eng managers own individual service levels.
Regressions
- A service cannot drop below its previous milestone level.
- If a regression is detected (e.g., failing gate tests), the service owner has 1 sprint to remediate.
- Unremediated regressions block the milestone gate.
Exceptions
- Exceptions require VP Eng approval + documented risk acceptance.
- Exception expiry: next milestone. Must be resolved or re-approved.