Backend and Service Map (Desktop EHR)
Version: 1.0
Date: 2026-03-31
Companion: SPEC.md, ../../../MODULE_INDEX.md
This document maps personas/features to module specs, service folders under apps/services, and API documentation entry points. It includes a sync/offline write column: whether the platform currently exposes documented idempotent writes suitable for outbound replay (verify in code before claiming “done”).
Legend — Offline write posture:
| Value | Meaning |
|---|---|
| Yes (partial) | At least one write path has known idempotency (Idempotency-Key / clientMutationId) in service code or module API docs. |
| Planned | Module spec targets offline; server idempotency may be incomplete — implement read/cache + queue only after TR verification. |
| Online-first | Depends on live external systems, realtime, or internal-only routes — expect online-only or heavy degradation offline. |
1. Governance, identity, and platform configuration
Used by all personas for login, tenant, licensing, and effective config.
| Concern | Module folder | Service folder | API / docs pointer | Offline write |
|---|---|---|---|---|
| IAM / identity | modules/iam/ | iam | API_DOCS.md | Online-first (token issuance) |
| Hierarchy | modules/hierarchy/ | hierarchy | API_DOCS.md | Online-first |
| Access policy | modules/access-policy/ | access-policy | API_DOCS.md | Online-first (evaluate live) |
| Config resolver | modules/config-resolver/ | config-resolver | API_DOCS.md, CONFIG_MODEL.md | Cache reads offline; writes online-first |
| Licensing | modules/licensing/ | licensing | API_DOCS.md | Cache entitlement snapshot; admin changes online-first |
| Tenant | modules/tenant/ | tenant | API_DOCS.md | Online-first for admin mutations |
| Platform admin | modules/platform-admin/ | platform-admin | API_DOCS.md | Online-first |
| Audit | modules/audit/ | audit | API_DOCS.md | Client emits via APIs that reach audit; follow module flows |
Edge routing: API_PATH_CONVENTIONS.md — browser/desktop use Kong-public /api/... and /v1/... as exposed; never ship /internal/... from the desktop client.
2. Clinical EHR (clinician / nurse personas)
| Feature area | Module folder | Service folder | API docs | Offline write |
|---|---|---|---|---|
| Patient chart | modules/patient-chart/ | patient-chart-service | API_DOCS.md | Planned — verify versioning |
| Registration | modules/registration/ | registration | API_DOCS.md | Yes (partial) — POST /v1/patients idempotency (see offline-first pack) |
| Clinical notes | modules/clinical-notes/ | clinical-notes | API_DOCS.md | Planned — signing rules may need online |
| Orders / CPOE | modules/orders-cpoe/ | orders | API_DOCS.md | Yes (partial) — orders service supports Idempotency-Key on create |
| Results | modules/results/ | results | API_DOCS.md | Online-first for fresh feeds; cache reads offline |
| Medications | modules/medication-management/ | medication | API_DOCS.md | Planned |
| Allergies | modules/allergies/ | allergies | API_DOCS.md | Planned |
| Vitals | modules/vitals/ | vitals | API_DOCS.md | Planned |
| Problem list | modules/problem-list/ | problem-list | API_DOCS.md | Planned |
| Immunizations | modules/immunizations/ | immunizations | API_DOCS.md | Planned (licensed add-on) |
| Care plans | modules/care-plans/ | care-plans-service | API_DOCS.md | Planned (licensed add-on) |
| Provider directory | modules/provider-directory/ | provider-directory | API_DOCS.md | Cache offline |
| Scheduling | modules/scheduling/ | scheduling | API_DOCS.md, SPEC.md FR-DSK-015/016, UI_AND_DESIGN_PARITY.md §8 | Online-first for live free/busy and instant holds; cached calendars + queued intents offline; rich UI + OS notifications on desktop per product |
| Facility | modules/facility-management/ | facility | API_DOCS.md | Admin-heavy; online-first |
| Requisitions / referrals | Retired — orders-cpoe, document-management | orders, document-management | RETIRED.md, ADR-0046 | CPOE + DMS |
| Terminology | modules/terminology/ | terminology | API_DOCS.md | Cache reads offline |
3. Financial, insurance, and add-on clinical systems
| Feature area | Module folder | Service folder | API / docs | Offline write |
|---|---|---|---|---|
| Billing | modules/billing/ | billing | — | Online-first for live financial posts |
| Claims | modules/claims/ | claims | — | Online-first (clearinghouse / submission) |
| Insurance | modules/insurance/ | insurance | — | Online-first for eligibility / payers |
| Laboratory LIS | modules/laboratory-lis/ | laboratory-lis | — | Online-first for live lab interfaces |
| Radiology PACS | modules/radiology-pacs/ | radiology-pacs | — | Online-first for streaming / DICOMweb |
| Messaging | modules/messaging/ | messaging | API_DOCS.md, NOTIFICATIONS_PLATFORM.md | Online-first for live delivery |
| AI orchestrator | modules/ai-orchestrator/ | ai-orchestrator | Cloud: AI_PLATFORM.md — HTTPS to Kong /v1/ai/... only; offline unless local engine enabled. Local on-device inference does not replace server audit/orchestrator obligations unless product defines hybrid sync — see SOLUTION_DESIGN.md §11, TECHNICAL_REQUIREMENTS.md §10 | |
| Patient portal (server) | modules/patient-portal/ | patient-portal-api | N/A for desktop EHR persona focus |
4. Interoperability gateways
| Surface | Module / app | Notes |
|---|---|---|
| FHIR R4 | modules/fhir-gateway/, fhir-gateway | Use /fhir/R4/... per API_PATH_CONVENTIONS.md when FHIR is the contract. |
| HL7 v2 | modules/hl7v2-interop/ | Server-side; not a desktop broker. |
5. Suggested dependency order for desktop vertical slices
- Shell + auth + session (IAM, token storage, tenant selection).
- Licensing + config-resolver cached snapshot + guards (match
ehr-webbehavior). - Registration — strong idempotency story for offline create.
- Patient chart + chart submodules — read-heavy cache, then writes per module TR.
- Orders — partial idempotency already in codebase.
- Scheduling — rich calendar/agenda UI + notifications (SPEC.md FR-DSK-015/016); align with
schedulingonline-first rules. - AI assist — cloud orchestrator integration; optional local engine behind policy flags (AI_PLATFORM.md).
- Admin / platform flows last or web-only depending on product.
6. Maintenance
When a module gains idempotent offline replay, update this table and TRACEABILITY_MATRIX.md. Source of truth for REST shapes remains each module API_DOCS.md and Kong infra/kong/*.yml.