Architectural Freeze Points
Execution-layer artifact. Companion to ROADMAP.md. Enumerates contracts that must freeze before code depends on them.
1. Freeze Rules
- Freeze means: no breaking changes without a versioned migration path. Additive changes (new optional fields, new events, new endpoints) are always safe.
- Breaking changes after freeze require: ADR filed → Architecture review → migration script → deprecation window (minimum 1 sprint) → new version (
vN+1). - Enforcement: CI checks validate frozen schemas against committed baselines. A PR that modifies a frozen contract without a corresponding migration is auto-rejected.
- Ownership: Each contract has a single owner team. Only the owner can propose changes. Consumers file requests via the Architecture Decision Log.
2. Freeze Timeline
| # | Contract | Frozen before | Owner | Evolution rule |
|---|---|---|---|---|
| F01 | FHIR R4 resource profiles (Patient, Encounter, Observation, Condition, AllergyIntolerance, MedicationRequest, ServiceRequest, DiagnosticReport, Appointment, Schedule, Practitioner, Location, Organization) | M0 end | Architecture + Clinical SME | New profiles additive; changing existing profile → new profile version |
| F02 | EventEnvelope (CloudEvents v1.0 shape: id, source, type, tenantId, subject, time, data, datacontenttype) | M0 end | Platform | Only additive metadata; breaking → vN+1 with dual-publish during migration |
| F03 | NATS JetStream subject namespace (ehealth.{service}.{aggregate}.{action}.v{N}) | M0 end | Platform | New subjects additive; existing subjects stable; breaking → new version suffix |
| F04 | Tenant isolation model (tenantId UUID on all entities + hierarchy DAG HierarchyNode) | M0 end | Platform | Shape never changes; adding fields to HierarchyNode is additive only |
| F05 | Sync protocol (pull/push/resolve endpoints, vector clocks, conflict resolution envelope) | M0 end | Platform + Desktop | Additive fields only; breaking → /sync/v2/ with parallel v1 support |
| F06 | Kong gateway route structure (/api/{service}/*, /fhir/R4/*, /internal/*) | M0 end | DevOps | New routes additive; existing routes stable; plugin changes require migration window |
| F07 | Keycloak realm structure (realm name, client IDs, role hierarchy, custom claims: tenantId, hierarchyNodeIds, licensedModules) | M0 end | IAM | New claims additive; changing existing claims requires token migration |
| F08 | Desktop IPC channel contracts (main ↔ renderer channel names, message shapes) | M0 end | Desktop | New channels additive; existing channels never change shape |
| F09 | SQLite local schema (offline store: tables, columns, indexes, tenant scoping) | M0 end | Desktop + Sync | Additive columns only; new tables OK; dropping/renaming columns requires migration script |
| F10 | AI orchestrator API (/ai/complete, /ai/moderate, /ai/embeddings, /ai/redact-pii) + prompt format (system prompt schema with id, version, template, model, safety_level) | M0 end | AI | New endpoints additive; prompt versions append-only; breaking → /ai/v2/* |
| F11 | Audit event schema (AuditEvent structure: who, what, when, where, tenantId, action, resource, detail, hash) | M0 end | Security | Immutable — tamper-evident hash chain depends on schema stability |
| F12 | Error code registry (/openapi/errors.json: code → message mapping) | M1 end | Platform | Codes never renamed or removed; new codes additive |
| F13 | FHIR search parameters per resource (e.g., Patient: name, identifier, birthdate, gender, family) | M1 end | FHIR Gateway | New params additive; existing params stable |
| F14 | Offline conflict resolution matrix (aggregate → resolution strategy mapping) | M0 end | Sync + DDD | Adding new aggregates OK; changing resolution policy for existing aggregate requires ADR |
| F15 | PHI encryption key management scheme (key hierarchy, rotation schedule, algorithm) | M0 end | Security | Algorithm and key hierarchy stable; rotation schedule configurable |
| F16 | FHIR MedicationRequest/MedicationDispense profiles (e-prescribing) | M3 start | Interop | National spine conformance is the contract |
| F17 | HL7v2 message mapping profiles (ADT/ORM/ORU/SIU field mappings) | M3 end | Interop | Mapping additions OK; changing existing mappings requires adapter version bump |
| F18 | DICOM/DICOMweb integration profile (WADO-RS, STOW-RS, QIDO-RS endpoints) | M4 start | Imaging | IHE profiles are the contract; local extensions additive only |
| F19 | HMIS indicator catalog mapping (national indicators → FHIR Measure/MeasureReport) | M4 start | PopHealth | WHO/national catalog is the contract; local additions OK |
| F20 | SMART on FHIR launch context + scopes | M5 start | FHIR Gateway | SMART spec is the contract |
| F21 | Mobile app deep link schema (ghasi-ehealth:// URL patterns) | M5 start | Mobile | New routes additive; existing routes stable |
| F22 | Patient portal consent model (consent categories, default-deny rules, opt-in/opt-out semantics) | M3 start | Engagement + Legal | Categories additive; changing semantics of existing categories requires migration |
| F23 | Billing charge master schema (charge codes, modifiers, pricing rules) | M2 start | Finance | New codes additive; changing existing codes requires deprecation window |
| F24 | Webhook signature scheme (HMAC-SHA256 + nonce + timestamp) | M2 start | Platform | Never changed after first subscriber onboarded |
| F25 | Clinical note template schema (SOAP structure, field types, specialty mapping) | M1 start | Clinical | New templates additive; changing existing template structure → template version |
| F26 | PDF output template engine (variable substitution, RTL support, font embedding rules) | M2 start | Document Mgmt | New templates OK; engine contract stable |
3. Freeze Sequence Diagram
M0 Freeze Window (Month 3)
├── F01 FHIR R4 resource profiles ─────────────────────────────► frozen
├── F02 EventEnvelope (CloudEvents) ───────────────────────────► frozen
├── F03 NATS subject namespace ────────────────────────────────► frozen
├── F04 Tenant isolation model ────────────────────────────────► frozen
├── F05 Sync protocol ────────────────────────────────────────► frozen
├── F06 Kong route structure ──────────────────────────────────► frozen
├── F07 Keycloak realm structure ──────────────────────────────► frozen
├── F08 Desktop IPC channels ──────────────────────────────────► frozen
├── F09 SQLite local schema ───────────────────────────────────► frozen
├── F10 AI orchestrator API + prompt format ───────────────────► frozen
├── F11 Audit event schema ────────────────────────────────────► frozen
├── F14 Conflict resolution matrix ────────────────────────────► frozen
├── F15 PHI encryption key scheme ─────────────────────────────► frozen
M1 Freeze Window (Month 6)
├── F12 Error code registry ───────────────────────────────────► frozen
├── F13 FHIR search parameters ────────────────────────────────► frozen
├── F25 Clinical note template schema ─────────────────────────► frozen
M2 Freeze Window (Month 9)
├── F23 Billing charge master schema ──────────────────────────► frozen
├── F24 Webhook signature scheme ──────────────────────────────► frozen
├── F26 PDF output template engine ────────────────────────────► frozen
M3 Freeze Window (Month 12)
├── F16 E-prescribing FHIR profiles ──────────────────────────► frozen
├── F17 HL7v2 message mapping ─────────────────────────────────► frozen
├── F22 Patient portal consent model ──────────────────────────► frozen
M4 Freeze Window (Month 15)
├── F18 DICOM/DICOMweb profile ────────────────────────────────► frozen
├── F19 HMIS indicator catalog mapping ────────────────────────► frozen
M5 Freeze Window (Month 18)
├── F20 SMART on FHIR launch context ─────────────────────────► frozen
├── F21 Mobile deep link schema ───────────────────────────────► frozen
4. Review Cadence
- Weekly: Architecture team reviews pending freeze-point PRs.
- Per milestone gate: All freeze points for the upcoming milestone reviewed and accepted.
- Quarterly: Full freeze-point audit — are frozen contracts still correct? Any that need evolution?
- ADR required for: Any proposal to break a frozen contract.
5. Operational Guidance
For engineers
- Before modifying any contract listed above: check the freeze status.
- If frozen: only additive changes. New optional fields, new endpoints, new events.
- If you need a breaking change: file an ADR, get Architecture review, propose migration path.
- CI will block PRs that modify frozen schema baselines without a migration.
For architects
- Freeze points are defensive — they prevent cascade rework.
- A freeze point accepted too early constrains the design. A freeze point accepted too late means code depends on shifting sand.
- The right time to freeze: when 2+ services depend on the contract and at least 1 sprint of code has been built against it.
- Clinical SME review required for all FHIR profile freezes.