Care Plan Service — Service Overview
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD
Purpose
The care-plan-service owns longitudinal, multidisciplinary care planning for every patient in the platform. It manages the full lifecycle of CarePlan, Goal, CareTeam, and Activity/Intervention records, including chronic disease management programs, post-acute follow-up plans, and preventive care protocols.
It is an optional licensed add-on (entitlement: ehr.care_plans). Unlicensed tenants receive 403 MODULE_NOT_LICENSED on all write endpoints.
Bounded Context Responsibilities
| In scope | Out of scope |
|---|---|
| CarePlan CRUD with versioning and review workflow | Clinical orders and CPOE (orders-service) |
| Goal management — status, coded targets, due dates | Medication prescribing (medication-service) |
| Activity/intervention tracking — assignment and completion | Lab/imaging task orchestration (orders-service) |
| CareTeam composition per plan | Population-level program aggregation (population-health-service) |
| FHIR R4 read/search surface: CarePlan, Goal, Task, CareTeam | FHIR write via FHIR HTTP (out of scope, REST-first write model) |
Optimistic concurrency via version field | Case management system integration (backlog) |
| Tenant-isolated storage with RLS | Direct payer reporting |
Upstream Dependencies
| Service | Why |
|---|---|
| registration-service | Patient identity (patientId) validation |
| scheduling-service | Encounter link (encounterId?) on plan creation |
| identity-service | JWT claims, tenantId, RBAC roles |
| terminology-service | Coded goals (SNOMED CT, ICD-10-CM, LOINC) |
| audit-service | Provenance and clinical audit pipeline |
| provider-directory-service | CareTeam practitioner identities |
Downstream Dependents
| Service | Dependency |
|---|---|
| patient-chart-service | Active care plan summaries for chart view |
| patient-portal-service | Read-only projection of active care plans for patients |
| population-health-service | Aggregated goal achievement metrics via NATS events |
| communication-service | Notifications on goal overdue / plan review due |
Key Architectural Decisions
- REST-first writes, FHIR read surface. All create/update operations use
/api/v1/care-plans/*. The FHIR R4 read surface (CarePlan,Goal,Task,CareTeam) is served viafhir-gateway. FHIR write interactions are explicitly out of scope until a platform release scopes them. - Optimistic concurrency. Mutating requests carry and return
version; stale writes return409 Conflict. - Transactional outbox. Domain events are reliably published to NATS JetStream via outbox; no events lost on process crash.
- Tenant isolation via RLS. All tables contain
tenant_id; Postgres RLS policies enforce zero cross-tenant reads. - Coded clinical concepts. Goals and activities reference terminology-service codings; free-text fallback is permitted.
Architecture Diagram
Slice Involvement
| Slice | Role |
|---|---|
| S1 — Clinical data capture | Care plan and goal creation |
| S2 — Team-based care | CareTeam coordination, multidisciplinary updates |
| S3 — Chronic care programs | Disease program templates (backlog) |
| S4 — Patient engagement | Portal read projection via fhir-gateway |
Source Reconciliation
Source: services/care-plan-service/_sources/care-plans/ — single module CLIN-CAREPLAN v1.2. No multi-module merge required. Legacy FR prefix FR-CP-* is preserved alongside new FR-CAREPL-* in the FR mapping table.