Kulcare Docs
DeveloperCare plansCare plan

Clinical Documentation System

Single Source of Truth for Care Plan, Longitudinal Health Record (LHR), Episodes, and Encounters

Clinical Data Hierarchy

Kulcare's clinical documentation system is built around a three-level hierarchy:

Patient
   |
   +-- Longitudinal Health Record (LHR)     <-- AGGREGATE VIEW
   |       |                                    (patient's complete health story)
   |       +-- Problems
   |       +-- Medications
   |       +-- Vitals/Measurements
   |       +-- Health Score
   |       +-- Encounter History
   |
   +-- Episodes of Care                     <-- PROGRAM CONTAINERS [PLANNED]
   |       |                                    (treatment programs)
   |       +-- "Post-ACL Rehab" (physio)
   |       +-- "Anxiety Treatment" (therapy)
   |       +-- "Weight Management" (nutrition)
   |
   +-- Encounters                           <-- ATOMIC CLINICAL EVENTS
           |                                    (single visit/session)
           +-- Prescriptions (doctors)
           +-- Session Notes (therapists)   [PLANNED]
           +-- Physio Documentation         [PLANNED]
           +-- Nutrition Consultations      [PLANNED]

Key Concepts:

ConceptDefinitionScopeStorage
LHRPatient-centric aggregate viewEntire patient historyComputed
Episode of CareProgram-specific treatment containerOne treatment programStored
EncounterSingle visit/sessionOne appointmentStored

See Architecture: Clinical Data Hierarchy for complete details.


Documentation Structure

docs/care-plan/
|
+-- README.md                  # This file - overview and navigation
|
+-- architecture/              # Core concepts and data models
|   +-- clinical-data-hierarchy.md      # LHR/Episode/Encounter relationships
|   +-- multi-practitioner-encounter-types.md  # EncounterDocument model
|
+-- current-state/             # What's implemented TODAY
|   +-- README.md              # Current implementation overview
|   +-- lhr-feature.md         # LHR implementation details
|   +-- care-plan-feature.md   # Care Plan/Prescription details
|   +-- lhr-architecture.md    # LHR technical architecture
|
+-- future-state/              # What's PLANNED for future
|   +-- README.md              # Roadmap overview
|   +-- episode-of-care.md     # Episode implementation plan
|   +-- multi-practitioner-documents.md  # EncounterDocument plan
|
+-- guides/                    # Usage and troubleshooting
|   +-- usage.md               # How to use current features
|   +-- troubleshooting.md     # Common issues and solutions
|   +-- mock-data.md           # Mock data for development
|
+-- backend/                   # Backend implementation details
|   +-- backend-endpoints.md
|   +-- system-design.md
|   +-- implementation-progress.md
|   +-- (other backend docs)
|
+-- testing/                   # Testing documentation
|   +-- manual-test-plan.md
|   +-- manual-testing-guide.md
|
+-- e-prescription/            # E-Prescription feature
|   +-- e-prescription-prd.md
|   +-- e-prescription-technical-spec.md
|   +-- (other e-prescription docs)
|
+-- lhr/                       # LHR detailed architecture
|   +-- database-design.md
|   +-- api-design.md
|   +-- service-architecture.md
|   +-- (other LHR architecture docs)
|
+-- reference/                 # Original requirements docs
|   +-- care-plan-prd.md
|   +-- care-plan-spec.md
|
+-- archive/                   # Superseded documents
    +-- (old plans and legacy docs)

Quick Navigation

Understanding the System

Start HereDescription
Clinical Data HierarchyCore concepts: LHR, Episode, Encounter
Current State OverviewWhat's implemented today
Future State OverviewWhat's planned

Current Implementation

DocumentDescription
LHR FeatureLongitudinal Health Record implementation
Care Plan FeatureCare Plan/Prescription implementation
Usage GuideHow to use current features

Future Plans

DocumentDescription
Episode of CarePlanned: Treatment program containers
Multi-Practitioner DocumentsPlanned: Practitioner-specific documentation

Technical Details

DocumentDescription
Backend EndpointsAPI documentation
System DesignBackend architecture
LHR Database DesignDatabase schemas

Implementation Status

Implemented (Current State)

FeatureStatusRoute
Longitudinal Health RecordComplete/careplan/patient/:patientId
Care Plan / PrescriptionComplete/prescription/:appointmentId/:patientId/*
AI ScribeCompleteSidebar in Prescription
HIPAA Audit TrailCompleteSettings > Security
Encounter ManagementCompleteIntegrated with Prescription

Planned (Future State)

FeatureStatusPriority
Episode of CarePlanningHigh
Multi-Practitioner DocumentsPlanningHigh
Clinical MeasurementsPlanningMedium
Assessment InstrumentsPlanningMedium

Key Relationships

LHR and Encounters

  • LHR is a computed view that aggregates data from all encounters
  • LHR provides the "big picture" of patient health
  • Encounters contribute data to LHR (vitals, medications, problems)

Episodes and Encounters (Planned)

  • Episode is a container for related encounters
  • Encounters can exist with or without an Episode
  • Episodes track treatment progress and goals

Context-Dependent Navigation

User RolePrimary EntryRationale
Doctor (general)LHR DashboardNeeds full patient context
PhysiotherapistEpisode ViewWorks within specific program
PsychologistEpisode ViewTracks therapy progress
DietitianEpisode ViewManages nutrition program
ReceptionistEncounter ListSchedules appointments

Frontend Code

ComponentLocation
LongitudinalHealthRecordfrontend/apps/cms/src/pages/care-plan/LongitudinalHealthRecord.tsx
CarePlanDashboardfrontend/apps/cms/src/pages/care-plan/CarePlanDashboard.tsx
EncounterPagefrontend/apps/cms/src/pages/care-plan/EncounterPage.tsx
AI Scribefrontend/apps/cms/src/features/aiScribe/
Encounter APIfrontend/apps/cms/src/services/longitudinalHealthRecordApi.ts

Backend Code

ModuleLocation
Care Planbackend/parts/care_plan/
Prescriptionsbackend/parts/prescriptions/
Encountersbackend/parts/clinic/models/encounter.rb
LHR Controllerbackend/parts/clinic/controllers/clinic_patients_lhr_controller.rb

Last Updated: December 2025 Maintainer: Development Team

On this page