Kulcare Docs
DeveloperCare plansCare planArchive

Care Plan & Encounter Unification Plan

Status: SUPERSEDED

This planning document has been superseded by the actual implementation. Key differences from the original plan:

  • No EncounterEditPage: Instead of creating a separate encounter editor, all encounter flows navigate directly to the existing PrescriptionPage for clinical documentation
  • No RightSidebar components in encounter feature: Prescription preview and patient history are handled by the prescription feature
  • Simplified routing: /cms/encounters/:encounterId route was removed; encounters redirect to /cms/prescription/:appointmentId/:patientId/encounter

See the current implementation documentation:

Executive Summary

Goal: Unify the legacy prescription system with the new care-plan/encounter system into a single feature under frontend/apps/cms/src/features/encounter/.

Architecture Decision:

  • Create NEW dedicated Encounters API with RESTful canonical routes
  • Mock backend implementation initially
  • Reuse working legacy prescription functionality (copy previous, medicine groups, etc.)
  • Follow standard feature pattern used in CMS app

New Feature Location

frontend/apps/cms/src/features/encounter/
├── components/         # UI components
├── hooks/              # React Query hooks + custom hooks
├── services/           # API services (mocked initially)
│   └── api/            # API service classes
├── types/              # TypeScript interfaces
├── constants/          # Feature constants
├── utils/              # Transformers, validators
├── modals/             # Modal components
├── tabs/               # Tab content components
└── store/              # Zustand stores (if needed)

RESTful Routes Design

Frontend Routes (Canonical)

/cms/encounters                      # Dashboard - list encounters
/cms/encounters/new                  # New encounter (patient selection)
/cms/encounters/:encounterId         # View/Edit encounter
/cms/encounters/:encounterId/preview # Preview prescription

Backend API Endpoints (Mocked Initially)

# Encounters CRUD
POST   /api/v1/encounters                    # Create encounter
GET    /api/v1/encounters/:id                # Get encounter details
PUT    /api/v1/encounters/:id                # Update encounter
DELETE /api/v1/encounters/:id                # Delete (soft delete)
GET    /api/v1/encounters                    # List with filters

# Encounter Actions
POST   /api/v1/encounters/:id/finalize       # Finalize encounter
POST   /api/v1/encounters/:id/print          # Generate PDF
POST   /api/v1/encounters/:id/send           # Send to patient

# Request body for POST /encounters:
{
  patient_id: number,
  appointment_id?: number,  // Optional - link to existing appointment
  doctor_id: number,
  visit_type: 'in_person' | 'teleconsultation' | 'follow_up',
  chief_complaint?: string
}

Current Systems (Reference)

1. LEGACY PRESCRIPTION (Working - Reuse Components)
   Route: /cms/prescription/:appointmentId/:patientId/:source
   API: prescriptionApi.ts (12+ real endpoints)
   Features to Reuse: Copy Previous, Medicine Groups, Test Groups, Print

2. NEW CARE PLAN (Mock Data - Integrate AI Scribe)
   Route: /cms/careplan/patient/:patientId/:encounterId
   API: careplanApi.ts (mock mode)
   Features: AI Scribe, HIPAA Audit, Teleconsultation

3. AI SCRIBE (Keep As-Is)
   Location: frontend/apps/cms/src/features/aiScribe/
   Integration: Import into new encounter feature

UI Layout Design

+------------------------------------------------------------------------+
| [<] Pallak | 45y | Other | 8899297833        [Copy Rx] [AI Scribe]     |
|     In-Progress | Dr. Sarah Johnson           [Preview] [Save] [Finalize]
+------------------------------------------------------------------------+
| Vitals | Observations | Medications (2) | Investigations (1) | Advice | Next Visit |
+------------------------------------------------------------------------+
|                                              |                          |
| +------------------------------------------+ | [AI Scribe|History|Timeline]
| | [Copy Previous] Search...                | | +----------------------+ |
| +------------------------------------------+ | | Recording Controls   | |
| | My Groups      | Categories/Search       | | | [Start Recording]    | |
| | [Group 1]      | Common items grid       | | +----------------------+ |
| | [Group 2]      | with metadata           | | | Live Transcription   | |
| | [Group 3]      |                         | | | ...                  | |
| +------------------------------------------+ | +----------------------+ |
| | Added Items (count)                      | | | AI Suggestions       | |
| | - Item 1 with actions                    | | | [Accept] [Reject]    | |
| | - Item 2 with actions                    | | +----------------------+ |
| +------------------------------------------+ |                          |
+------------------------------------------------------------------------+

Design Decisions

  • Right Panel Default: AI Scribe tab (if enabled) or Patient History tab
  • Right Panel Tabs: AI Scribe | Patient History | Timeline | Preview
  • Copy Previous: Tab-level (granular) + Header-level (bulk "Copy Rx")
  • Doctor's Templates: Integrated into tabs (not dropdowns)

Implementation Phases

Phase 1: Feature Scaffold + Types + Mock API

Goal: Create feature structure with types and mocked API

Files to Create:

features/encounter/
├── types/
│   └── index.ts              # Encounter, Patient, Medication, etc.
├── services/
│   ├── encounterApi.ts       # CRUD operations (mocked)
│   └── index.ts
├── hooks/
│   ├── useEncounter.ts       # React Query hooks
│   ├── useEncounterList.ts
│   └── index.ts
├── constants/
│   └── index.ts
└── index.ts                  # Barrel export

Key Types:

interface Encounter {
  id: string
  patientId: string
  appointmentId?: string
  doctorId: string
  clinicId: string
  status: 'draft' | 'in_progress' | 'completed' | 'cancelled'
  visitType: 'in_person' | 'teleconsultation' | 'follow_up'
  chiefComplaint?: string
  vitals?: VitalsData
  observations?: ObservationsData
  medications: Medication[]
  investigations: Investigation[]
  advice: AdviceItem[]
  nextVisit?: NextVisitData
  createdAt: string
  updatedAt: string
}

Mock API Pattern (reuse from aiScribe):

const USE_MOCK = import.meta.env.VITE_USE_MOCK_ENCOUNTER_API === 'true'

export const encounterApi = {
  create: async (data: CreateEncounterRequest): Promise<Encounter> => {
    if (USE_MOCK) return mockCreate(data)
    return realCreate(data)
  },
  // ... other methods
}

Phase 2: Core Components + Pages

Goal: Build encounter pages and integrate with legacy components

Files to Create:

features/encounter/
├── components/
│   ├── EncounterHeader.tsx       # Patient info + actions
│   ├── EncounterTabs.tsx         # Tab navigation with badges
│   └── RightSidebar/
│       ├── RightSidebarTabs.tsx
│       ├── PatientHistoryPanel.tsx
│       ├── EncounterTimeline.tsx
│       └── PrescriptionPreview.tsx
├── tabs/
│   ├── VitalsTab.tsx             # Reuse legacy vitals
│   ├── ObservationsTab.tsx       # Reuse legacy observations
│   ├── MedicationsTab.tsx        # Reuse legacy + add groups
│   ├── InvestigationsTab.tsx     # Reuse legacy + add groups
│   ├── AdviceTab.tsx             # Reuse legacy + add groups
│   └── NextVisitTab.tsx          # Reuse legacy
└── pages/
    ├── EncounterListPage.tsx     # Dashboard
    ├── NewEncounterPage.tsx      # Patient selection
    └── EncounterEditPage.tsx     # Main editor

Reuse Strategy:

  • Import existing tab components from src/components/care-plan/
  • Wrap with new encounter-specific logic
  • Add Medicine Groups, Test Groups integration
  • Add Copy Previous functionality

Phase 3: AI Scribe Integration

Goal: Connect AI Scribe feature to encounter

Changes:

  • Import AIScribeSidebar from features/aiScribe/
  • Pass encounter context to AI Scribe
  • Handle AI suggestions → prescription updates
  • Integrate into RightSidebarTabs

Phase 4: Route Setup + Legacy Bridge

Goal: Setup routes and handle legacy redirects

Router Changes (App.tsx or routes file):

// New canonical routes
{ path: '/cms/encounters', element: <EncounterListPage /> },
{ path: '/cms/encounters/new', element: <NewEncounterPage /> },
{ path: '/cms/encounters/:encounterId', element: <EncounterEditPage /> },

// Legacy redirects (optional)
{ path: '/cms/careplan/*', element: <Navigate to="/cms/encounters" /> },

Navigation Updates:

  • Queue page → use new encounter routes
  • Appointments → link to encounters

Files Summary

Files to Create (New Feature)

FilePurpose
features/encounter/types/index.tsAll TypeScript interfaces
features/encounter/services/encounterApi.tsAPI with mock support
features/encounter/hooks/useEncounter.tsReact Query hooks
features/encounter/components/EncounterHeader.tsxHeader with actions
features/encounter/components/EncounterTabs.tsxTab navigation
features/encounter/components/RightSidebar/*Right panel components
features/encounter/tabs/*Tab content (wrapping legacy)
features/encounter/pages/*Page components

Files to Reference/Reuse (Legacy)

FileReuse For
components/care-plan/VitalsTab.tsxVitals functionality
components/care-plan/ObservationsTab.tsxObservations functionality
components/care-plan/MedicationsTab.tsxMedications base
components/care-plan/InvestigationsTab.tsxInvestigations base
features/prescription/services/prescriptionApi.tsAPI patterns
features/aiScribe/components/AIScribeSidebar.tsxAI Scribe integration

Validation Checklist

Phase 1 Complete When:

  • Feature folder structure created
  • Types defined for all entities
  • Mock API working (CRUD operations)
  • React Query hooks functional
  • Can create/read/update encounter via mock

Phase 2 Complete When:

  • All pages render correctly
  • Tab navigation works with badges
  • Legacy tab components integrated
  • Copy Previous works (tab + header level)
  • Doctor's groups integrated into tabs
  • Right sidebar tabs functional

Phase 3 Complete When:

  • AI Scribe sidebar integrated
  • Recording controls work
  • AI suggestions update encounter data
  • Right panel defaults correctly

Phase 4 Complete When:

  • Routes configured and working
  • Navigation from Queue works
  • Legacy routes redirect (if needed)
  • No broken links

Encounter-Prescription Integration Plan

Previous Page

Longitudinal Health Record Architecture

Next Page

On this page

Executive SummaryNew Feature LocationRESTful Routes DesignFrontend Routes (Canonical)Backend API Endpoints (Mocked Initially)Current Systems (Reference)UI Layout DesignDesign DecisionsImplementation PhasesPhase 1: Feature Scaffold + Types + Mock APIPhase 2: Core Components + PagesPhase 3: AI Scribe IntegrationPhase 4: Route Setup + Legacy BridgeFiles SummaryFiles to Create (New Feature)Files to Reference/Reuse (Legacy)Validation ChecklistPhase 1 Complete When:Phase 2 Complete When:Phase 3 Complete When:Phase 4 Complete When: