Episode of Care Comprehensive Implementation Plan

Status: In Progress (Refined & Aligned with Codebase Architecture)
Priority: High
Target Branch: feature/episodes-of-care
Architecture Principle: Maximum reuse of existing Clinical Domain models, controllers, blueprints, and CMS components.

Executive Summary & Current Architecture Baseline
Entity Relationships & Data Architecture
Database Schema & Delta Migrations
Episode Lifecycle & State Machine
Appointment & CMS Queue Integration (Maximum Reuse)
Multi-Specialty Integrated Care
API Surface & Controller Re-use
Frontend & UI Integration Strategy
Permissions, Authorization & Security
Re-Baselined Implementation Roadmap
Appendices
- Appendix A: Codebase File References
- Appendix B: FHIR R4 EpisodeOfCare Specification Mapping

1. Executive Summary & Current Architecture Baseline

1.1 Purpose

An Episode of Care represents a longitudinal course of clinical treatment spanning multiple encounters and scheduled appointments. It groups sessions, tracks progress against multi-disciplinary treatment goals, and connects acute and chronic encounters into coherent care plans.

1.2 Architectural Realignment (Codebase Audit)

A critical audit of the kulcare-platform revealed that key foundations are already built. Rather than recreating tables or creating parallel endpoints, this plan extends existing structures and hooks directly into the running domain architecture:

System Layer	Current Codebase Baseline	Plan Strategy
Database Schema	`clinical.episodes_of_care` and `clinical.treatment_goals` exist in `db/structure.sql` with native PG Enums, UUIDv7, and RLS.	Apply incremental non-breaking migrations (`ALTER TABLE`) to add integrated care, session quotas, and appointment FK.
Core Models	`Clinical::EpisodeOfCare` and `Clinical::TreatmentGoal` models exist with transition state machines and validations.	Enhance models with session calculations, integrated care helpers, and quota validations.
Routing & APIs	Endpoints already live under `/clinical/episodes_of_care` and `/clinical/treatment_goals` in `domains/clinical/routes.rb`.	Reuse all existing REST endpoints. Add `episode_of_care_id` to `appointment_params` in `AppointmentsController`.
CMS Queue	Driven by `QueueController` using `Queue::GenerateToday` and `AppointmentBlueprint (view: :queue)`.	Extend `AppointmentBlueprint`'s queue view to serialize episode context and preload associations to maintain O(1) query performance.
CMS Frontend	Existing pages in `frontend/apps/cms/src/features/episode/` (`EpisodeListPage`, `EpisodeDetailPage`, `EpisodeFormPage`, `EpisodeStatusBadge`).	Retain existing CMS pages and `@kulcare/shared-services` hooks; add CMS Queue badges, filter controls, and session linker modals.
Patient App (PHR)	Contains patient appointments, visits, and timeline in `patient/src/features/`.	Introduce the patient-facing "My Care Programs" tab using serialized episode summaries.

2. Entity Relationships & Data Architecture

2.1 High-Level Architecture

2.2 Session Lifecycle (Appointment to Encounter)

An Episode tracks both scheduled sessions (appointments) and delivered care (encounters):

2.3 Complete Entity Relationship Diagram

2.4 Multi-Specialty (Integrated Care) Model

For complex care pathways (e.g., Post-Surgical ACL Rehabilitation, Bariatric Program, Cardiac Rehab), sessions and goals span multiple specialties under a single episode container:

3. Database Schema & Delta Migrations

3.1 Existing Baseline Tables (structure.sql)

The database already defines the core tables:

clinical.episodes_of_care:
- Status ENUM: planned, waitlist, active, onhold, finished, cancelled, entered_in_error.
- Type ENUM: rehabilitation, chronic_care, mental_health, maternity, oncology, preventive, acute.
- Columns: id (uuidv7), tenant_id, patient_id, facility_id, managing_practitioner_id, status, type, diagnosis_codes, period_start, period_end, description, patient_facility_id, timestamps.
- RLS: FORCE ROW LEVEL SECURITY is already active.
clinical.treatment_goals:
- Status ENUM: proposed, planned, accepted, active, on_hold, achieved, cancelled, entered_in_error.
- Priority ENUM: high, medium, low.
- Columns: id (uuidv7), tenant_id, episode_of_care_id, description, status, priority, target_date, outcome, timestamps.
clinical.encounters:
- Already has episode_of_care_id UUID and foreign key constraint fk_encounters_episode_of_care referencing clinical.episodes_of_care(tenant_id, id).

3.2 Migration: Extend episodes_of_care

Create migration db/migrate/YYYYMMDDHHMMSS_extend_clinical_episodes_of_care.rb:

class ExtendClinicalEpisodesOfCare < ActiveRecord::Migration[7.2]
  def change
    add_column :episodes_of_care, :is_integrated_care, :boolean, default: false, null: false
    add_column :episodes_of_care, :primary_specialty_id, :uuid
    add_column :episodes_of_care, :total_sessions_planned, :integer, default: 0, null: false
    add_column :episodes_of_care, :sessions_completed, :integer, default: 0, null: false
    add_column :episodes_of_care, :period_end_target, :date
    add_column :episodes_of_care, :metadata, :jsonb, default: {}, null: false

    add_index :episodes_of_care, [:tenant_id, :is_integrated_care]
    add_index :episodes_of_care, [:tenant_id, :primary_specialty_id]
  end
end

3.3 Migration: Add episode_of_care_id to appointments

Create migration db/migrate/YYYYMMDDHHMMSS_add_episode_of_care_to_appointments.rb:

class AddEpisodeOfCareToAppointments < ActiveRecord::Migration[7.2]
  disable_ddl_transaction!

  def change
    add_column :appointments, :episode_of_care_id, :uuid

    # Concurrent index to prevent table lock in production
    add_index :appointments,
              [:tenant_id, :episode_of_care_id],
              name: 'idx_appointments_tenant_episode',
              algorithm: :concurrently

    add_foreign_key :appointments,
                    :episodes_of_care,
                    column: :episode_of_care_id,
                    on_delete: :nullify,
                    validate: false
  end
end

(A subsequent migration runs validate_foreign_key :appointments, :episodes_of_care to ensure zero lock contention).

3.4 Migration: Extend treatment_goals

Create migration db/migrate/YYYYMMDDHHMMSS_extend_clinical_treatment_goals.rb:

class ExtendClinicalTreatmentGoals < ActiveRecord::Migration[7.2]
  def change
    add_column :treatment_goals, :progress_percentage, :integer, default: 0, null: false
    add_column :treatment_goals, :specialty_id, :uuid
    add_column :treatment_goals, :created_by_id, :uuid

    add_check_constraint :treatment_goals,
                         'progress_percentage >= 0 AND progress_percentage <= 100',
                         name: 'chk_treatment_goals_progress_range'
    add_index :treatment_goals, [:tenant_id, :specialty_id]
  end
end

3.5 Multi-Tenancy & Row Level Security (RLS)

All tables exist in the clinical schema and inherit Shared::Concerns::TenantScoped. PostgreSQL enforces RLS:

ALTER TABLE ONLY clinical.episodes_of_care FORCE ROW LEVEL SECURITY;
ALTER TABLE ONLY clinical.treatment_goals FORCE ROW LEVEL SECURITY;
ALTER TABLE ONLY clinical.appointments FORCE ROW LEVEL SECURITY;

Every query issued by Rails automatically includes tenant_id = current_setting('app.current_tenant_id').

4. Episode Lifecycle & State Machine

4.1 Status Definitions & FHIR R4 Alignment

Internal Status	FHIR R4 Status	Meaning
`planned`	`planned`	Episode created but therapy has not commenced.
`waitlist`	`waitlist`	Patient is waiting for slot/specialist availability.
`active`	`active`	Care is currently ongoing; sessions can be held.
`onhold`	`onhold`	Care temporarily suspended (patient travelling, post-op rest).
`finished`	`finished`	Treatment plan concluded; goals met or course done.
`cancelled`	`cancelled`	Patient withdrew or program discontinued prior to completion.
`entered_in_error`	`entered-in-error`	Record made in error; marked invalid.

4.2 Valid Transition Matrix

Transition Truth Table

From \ To	`planned`	`waitlist`	`active`	`onhold`	`finished`	`cancelled`	`entered_in_error`
`planned`	—	✅	✅	❌	✅	✅	✅
`waitlist`	❌	—	✅	❌	✅	✅	✅
`active`	❌	❌	—	✅	✅	✅	✅
`onhold`	❌	❌	✅	—	✅	✅	✅
`finished`	❌	❌	❌	❌	—	❌	✅
`cancelled`	❌	❌	❌	❌	❌	—	✅
`entered_in_error`	❌	❌	❌	❌	❌	❌	—

4.3 State Transition Methods & Model Logic

The model Clinical::EpisodeOfCare already implements these state transitions:

activate!: Sets period_start ||= Date.current and transitions to :active.
put_on_hold!: Transitions to :onhold.
resume!: Transitions from :onhold back to :active.
finish!: Sets period_end ||= Date.current and transitions to :finished.
cancel!: Sets period_end ||= Date.current and transitions to :cancelled.

# In Clinical::EpisodeOfCare
def can_transition_to?(new_status)
  VALID_TRANSITIONS[status.to_sym]&.include?(new_status.to_sym) || false
end

4.4 Business Rules & Action Matrix

Operation	`planned`	`waitlist`	`active`	`onhold`	`finished`	`cancelled`	`entered_in_error`
Book / Add New Appointment	✅	❌	✅	❌	❌	❌	❌
Link Existing Encounter	✅	❌	✅	❌	❌	❌	❌
Add / Edit Treatment Goals	✅	✅	✅	✅	❌	❌	❌
Update Progress Percentage	❌	❌	✅	❌	❌	❌	❌
Auto-completion Check	❌	❌	Triggered when `sessions_completed >= total_sessions_planned`	❌	N/A	N/A	N/A

5. Appointment & CMS Queue Integration (Maximum Reuse)

5.1 Appointment Linking Architecture

Appointments scheduled in CMS or through online booking can belong directly to an Episode.

In Clinical::Appointment:

belongs_to :episode_of_care, class_name: 'Clinical::EpisodeOfCare', optional: true

In Clinical::AppointmentsController: Permit :episode_of_care_id in appointment_params.

5.2 Extending AppointmentBlueprint (Zero-New-Endpoint Queue Data)

The CMS Queue is powered by QueueController using AppointmentBlueprint.render_as_hash(..., view: :queue). By extending the existing :queue view in AppointmentBlueprint, queue responses automatically include episode details without requiring any new queue APIs:

# In domains/clinical/blueprints/appointment_blueprint.rb
view :queue do
  # ... existing fields (status, waiting_room, patient, practitioner, encounter) ...

  field :episode_of_care do |appt, _|
    next nil unless appt.episode_of_care.present?

    episode = appt.episode_of_care
    {
      id: episode.id,
      type: episode.type,
      status: episode.status,
      description: episode.description,
      is_integrated_care: episode.is_integrated_care,
      sessions_completed: episode.sessions_completed,
      total_sessions_planned: episode.total_sessions_planned,
      progress_percentage: episode.total_sessions_planned.positive? ?
        ((episode.sessions_completed.to_f / episode.total_sessions_planned) * 100).round : 0
    }
  end
end

5.3 Performance: Preloading in Queue::GenerateToday

To avoid N+1 queries across the queue listing, update Queue::GenerateToday#fetch_todays_appointments:

# In domains/clinical/services/queue/generate_today.rb
Clinical::Appointment
  .for_practitioner(@practitioner.id)
  .for_facility(@facility.id)
  .for_date(@date, @timezone)
  .includes(
    :patient,
    :facility,
    :practitioner,
    :episode_of_care, # <-- Add eager loading here
    encounter: { video_sessions: :participants }
  )
  .order(:start_time)

5.4 Dual-Sync Rule: Synchronous Appointment-Encounter Linking

When an appointment with an episode_of_care_id starts:

Encounters::StartService creates the Clinical::Encounter and copies appointment.episode_of_care_id to encounter.episode_of_care_id.
When the encounter is finished, Encounters::StatusService increments episode.sessions_completed if linked.
If a provider retroactively links a standalone encounter to an episode, its parent appointment is updated simultaneously.

# In domains/clinical/services/episodes_of_care/link_encounter_service.rb
class LinkEncounterService < Shared::BaseService
  def initialize(encounter:, episode:)
    @encounter = encounter
    @episode = episode
  end

  def call
    ActiveRecord::Base.transaction do
      @encounter.update!(episode_of_care: @episode)
      @encounter.appointment&.update!(episode_of_care: @episode)
      @episode.increment!(:sessions_completed)
    end
    Success(@encounter)
  end
end

5.5 Retroactive & Batch Linking Services

Providers can link an existing encounter or appointment directly from the queue or encounter summary:

Direct update via existing endpoint:

PATCH /clinical/encounters/:id
Content-Type: application/json

{
  "encounter": {
    "episode_of_care_id": "019234a5-b67c-7890-abcd-1234567890ab"
  }
}

Direct appointment link via existing endpoint:

PATCH /clinical/appointments/:id
Content-Type: application/json

{
  "appointment": {
    "episode_of_care_id": "019234a5-b67c-7890-abcd-1234567890ab"
  }
}

5.6 CMS Queue UI Integration

5.6.1 Queue Row with Episode Badge

┌─────────────────────────────────────────────────────────────────────────────┐
│ CMS QUEUE - TODAY'S APPOINTMENTS                                            │
├─────────────────────────────────────────────────────────────────────────────┤
│ 10:00 AM  │ John Doe (M, 32)      │ Physio Session 6    │ [Start Encounter] │
│           │ Walk-in               │ Dr. Physio          │                   │
│           │ [Badge: Post-Surgery Recovery (5/12 • 42%)] │ [Episode Options▼]│
├───────────┼───────────────────────┼─────────────────────┼───────────────────┤
│ 10:30 AM  │ Jane Smith (F, 28)    │ Consultation        │ [Start Encounter] │
│           │ Fixed                 │ Dr. General         │                   │
│           │ No Episode Linked                           │ [+ Link Episode]  │
└─────────────────────────────────────────────────────────────────────────────┘

5.6.2 Queue Filter by Episode

The CMS queue includes an episode filter populated from GET /clinical/episodes_of_care?active=true&facility_id=:facility_id:

Filters: [All Episodes ▼] | Post-Surgery Recovery (4) | Knee Rehab Program (2) | No Episode (8)

6. Multi-Specialty Integrated Care

6.1 Single vs Integrated Episode Models

Single Specialty: e.g., 12-session Physiotherapy program where all sessions belong to one practitioner type.
Integrated Care (is_integrated_care: true): e.g., Comprehensive Post-Surgical Rehab involving Physiotherapist, Nutritionist, and Psychologist.

6.2 Specialty Quota & Session Distribution

In an integrated care program, quotas are tracked by specialty:

{
  "total_sessions_planned": 26,
  "sessions_completed": 10,
  "specialty_distribution": {
    "physiotherapy": { "planned": 12, "completed": 5 },
    "nutrition": { "planned": 6, "completed": 3 },
    "psychology": { "planned": 8, "completed": 2 }
  }
}

6.3 Multi-Specialty Progress Aggregation

In Clinical::EpisodeOfCareBlueprint (view: :detailed), aggregate counts dynamically:

field :specialty_breakdown do |episode|
  next nil unless episode.is_integrated_care

  episode.encounters.group(:specialty_id).count
end

7. API Surface & Controller Re-use

All APIs operate under the standard Rails routing scope :clinical, module: 'clinical' in domains/clinical/routes.rb.

7.1 Existing Clinical Endpoints (To Reuse Directly)

Operation	Existing HTTP Route	Controller & Action
List Episodes	`GET /clinical/episodes_of_care`	`Clinical::EpisodesOfCareController#index`
Show Episode	`GET /clinical/episodes_of_care/:id`	`Clinical::EpisodesOfCareController#show`
Create Episode	`POST /clinical/episodes_of_care`	`Clinical::EpisodesOfCareController#create`
Update Episode	`PATCH /clinical/episodes_of_care/:id`	`Clinical::EpisodesOfCareController#update`
Delete Episode	`DELETE /clinical/episodes_of_care/:id`	`Clinical::EpisodesOfCareController#destroy`
Transition Status	`POST /clinical/episodes_of_care/:id/transition`	`Clinical::EpisodesOfCareController#transition`
List Episode Goals	`GET /clinical/episodes_of_care/:id/goals`	`Clinical::EpisodesOfCareController#goals`
List Episode Encounters	`GET /clinical/episodes_of_care/:id/encounters`	`Clinical::EpisodesOfCareController#encounters`
List Episode Notes	`GET /clinical/episodes_of_care/:id/notes`	`Clinical::EpisodesOfCareController#notes`
Export FHIR	`GET /clinical/episodes_of_care/:id/export`	`Clinical::EpisodesOfCareController#export`
Patient Episodes	`GET /clinical/patients/:id/episodes_of_care`	Handled via `index?patient_id=:id`
List Treatment Goals	`GET /clinical/treatment_goals`	`Clinical::TreatmentGoalsController#index`
Create Treatment Goal	`POST /clinical/treatment_goals`	`Clinical::TreatmentGoalsController#create`
Update Treatment Goal	`PATCH /clinical/treatment_goals/:id`	`Clinical::TreatmentGoalsController#update`
Transition Goal	`POST /clinical/treatment_goals/:id/transition`	`Clinical::TreatmentGoalsController#transition`
Achieve Goal	`POST /clinical/treatment_goals/:id/achieve`	`Clinical::TreatmentGoalsController#achieve`

7.2 Parameter Extensions on Existing Controllers

1. In `Clinical::EpisodesOfCareController#episode_params`

Add the new attributes to permitted parameters:

def episode_params
  params.require(:episode_of_care).permit(
    :patient_id, :facility_id, :managing_practitioner_id,
    :status, :type, :period_start, :period_end, :period_end_target,
    :is_integrated_care, :primary_specialty_id,
    :total_sessions_planned, :description,
    diagnosis_codes: [
      :text, :role, :rank,
      { coding: %i[system code display] }
    ],
    metadata: {}
  )
end

2. In `Clinical::AppointmentsController#appointment_params`

Permit :episode_of_care_id:

def appointment_params
  params.require(:appointment).permit(
    :appointment_type, :start_time, :end_time,
    :patient_instruction, :note, :episode_of_care_id,
    reason_codes: [:text, { coding: %i[system code display] }]
  )
end

3. In `Clinical::TreatmentGoalsController#goal_params`

Permit :progress_percentage, :specialty_id, :created_by_id:

def goal_params
  params.require(:treatment_goal).permit(
    :episode_of_care_id, :description, :status, :priority,
    :target_date, :progress_percentage, :specialty_id, :outcome
  )
end

7.3 Detailed Endpoint Contracts

Status Transition Contract

POST /clinical/episodes_of_care/019234a5-b67c-7890-abcd-1234567890ab/transition
Content-Type: application/json

{
  "status": "active"
}

Response (200 OK):

{
  "id": "019234a5-b67c-7890-abcd-1234567890ab",
  "status": "active",
  "type": "rehabilitation",
  "period_start": "2026-10-06",
  "period_end": null,
  "duration_days": 0,
  "active": true,
  "terminal": false,
  "clinical_summary": "Rehabilitation Episode (active) - John Doe at City Clinic since 2026-10-06",
  "allowed_transitions": ["onhold", "finished", "cancelled", "entered_in_error"],
  "encounter_count": 0,
  "goal_count": 3
}

8. Frontend & UI Integration Strategy

8.1 Existing CMS Episode Components (To Reuse & Extend)

Located in frontend/apps/cms/src/features/episode/:

EpisodeListPage.tsx: Displays list of episodes filterable by patient and status.
EpisodeDetailPage.tsx: Overview card, progress display, sessions, and linked goals.
EpisodeFormPage.tsx: Creation/editing form.
EpisodeStatusBadge.tsx: Visual badge for episode status.
EpisodeCard.tsx: Summary card widget.
useEpisode.ts: Hook importing from @kulcare/shared-services:
- useEpisodeList, useEpisode, useEpisodeEncounters, useCreateEpisode, useUpdateEpisode, useDeleteEpisode, useTransitionEpisode.

8.2 CMS Queue Components (Delta Deliverables)

Located in frontend/apps/cms/src/features/queue/:

QueueEpisodeBadge.tsx: Displays badge directly in queue appointment rows using appointment.episode_of_care.
QueueEpisodeDropdown.tsx: Dropdown to quickly link an unlinked appointment to an active episode.
QueueEpisodeFilter.tsx: Filter queue items by active episode name.

8.3 LHR (Provider) View Integration

Located in frontend/apps/cms/src/features/patient-record/:

Add "Active Programs" section to the Patient Summary dashboard.
In Encounter History: Group encounters belonging to the same Episode into a collapsible section with progress indicator.

8.4 PHR (Patient Web App) Care Programs Integration

Located in patient/src/features/:

Add "My Care Programs" tab displaying:
- Program Title and Care Team members.
- Visual progress bar (sessions_completed / total_sessions_planned).
- Treatment Goals list with progress badges.
- Upcoming scheduled sessions with quick calendar view.

9. Permissions, Authorization & Security

9.1 Pundit Policy Architecture

All episode operations are gated through the existing policy Clinical::EpisodeOfCarePolicy:

# domains/clinical/policies/episode_of_care_policy.rb
def index?
  tenant_member? && has_any_permission?(:view_episodes, :manage_episodes, :view_patients)
end

def show?
  index? && record_in_tenant?
end

def create?
  tenant_member? && has_any_permission?(:create_episodes, :manage_episodes)
end

def update?
  has_any_permission?(:manage_episodes, :create_episodes) && record_in_tenant?
end

def transition?
  has_any_permission?(:manage_episodes, :create_episodes) && record_in_tenant?
end

9.2 Role-Based Access Control (RBAC) Matrix

Action	Admin	Staff	Practitioner	Patient (PHR)
View Episode Details	✅	✅	✅	✅ (Own programs only)
Create Episode	✅	✅	✅	❌
Update Episode Metadata	✅	✅	✅	❌
Transition Episode Status	✅	✅	✅	❌
Link Appointment / Encounter	✅	✅	✅	❌
View Treatment Goals	✅	✅	✅	✅ (Own goals only)
Create / Update Goals	✅	✅	✅	❌
Delete Episode	✅	❌	❌	❌

9.3 Multi-Tenant Isolation Enforcement

Every table enforces PostgreSQL Row Level Security (RLS).
Data leaking across tenants is physically blocked at the database engine level via tenant session variables.

10. Re-Baselined Implementation Roadmap

10.1 Phase 1: Database Delta Migrations & Model Extensions

Run migration ExtendClinicalEpisodesOfCare (is_integrated_care, total_sessions_planned, etc.).
Run concurrent migration AddEpisodeOfCareToAppointments (episode_of_care_id on appointments).
Run migration ExtendClinicalTreatmentGoals (progress_percentage, specialty_id).
Update Clinical::EpisodeOfCare with integrated care validations and session calculation scopes.
Add belongs_to :episode_of_care to Clinical::Appointment.

10.2 Phase 2: Serializer & Linking Service Enhancements

Extend Clinical::AppointmentBlueprint (view: :queue) with episode_of_care metadata.
Update Queue::GenerateToday#fetch_todays_appointments with .includes(:episode_of_care).
Permit :episode_of_care_id in AppointmentsController#appointment_params.
Implement LinkEncounterService to keep appointment and encounter episode links in sync.

10.3 Phase 3: CMS Queue & LHR Integration

Implement QueueEpisodeBadge and QueueEpisodeFilter in CMS Queue UI.
Add "Link to Episode" action dropdown to unlinked queue appointments.
Update CMS EpisodeDetailPage to display multi-specialty breakdown charts.
Add episode grouping to EncounterHistory component in LHR.

10.4 Phase 4: Patient PHR Care Programs Module

Create "My Care Programs" screen in patient web app (patient/).
Render program progress bars, goal completion status, and upcoming sessions.
Add episode tag to patient appointment cards.

10.5 Phase 5: Verification, Tests & Documentation

Add RSpec request specs for episode linking in AppointmentsController.
Add RSpec unit specs for Queue::GenerateToday eager loading.
Add frontend integration tests for CMS Queue episode filtering.
Validate end-to-end multi-specialty session flow in staging environment.

Standard: HL7 FHIR Release 4 - EpisodeOfCare
Mapped fields:
- identifier -> episodes_of_care.id (UUIDv7)
- status -> episodes_of_care.status (native enum)
- type -> episodes_of_care.type (native enum)
- diagnosis.condition -> episodes_of_care.diagnosis_codes
- patient -> episodes_of_care.patient_id
- managingOrganization -> episodes_of_care.facility_id
- period.start / period.end -> episodes_of_care.period_start / period_end
- careManager -> episodes_of_care.managing_practitioner_id

Episode of Care Comprehensive Implementation Plan

Table of ContentsCopy Anchor Link

1. Executive Summary & Current Architecture BaselineCopy Anchor Link

1.1 PurposeCopy Anchor Link

1.2 Architectural Realignment (Codebase Audit)Copy Anchor Link

2. Entity Relationships & Data ArchitectureCopy Anchor Link

2.1 High-Level ArchitectureCopy Anchor Link

2.2 Session Lifecycle (Appointment to Encounter)Copy Anchor Link

2.3 Complete Entity Relationship DiagramCopy Anchor Link

2.4 Multi-Specialty (Integrated Care) ModelCopy Anchor Link

3. Database Schema & Delta MigrationsCopy Anchor Link

3.1 Existing Baseline Tables (structure.sql)Copy Anchor Link

3.2 Migration: Extend episodes_of_careCopy Anchor Link

3.3 Migration: Add episode_of_care_id to appointmentsCopy Anchor Link

3.4 Migration: Extend treatment_goalsCopy Anchor Link

3.5 Multi-Tenancy & Row Level Security (RLS)Copy Anchor Link

4. Episode Lifecycle & State MachineCopy Anchor Link

4.1 Status Definitions & FHIR R4 AlignmentCopy Anchor Link

4.2 Valid Transition MatrixCopy Anchor Link

Transition Truth TableCopy Anchor Link

4.3 State Transition Methods & Model LogicCopy Anchor Link

4.4 Business Rules & Action MatrixCopy Anchor Link

5. Appointment & CMS Queue Integration (Maximum Reuse)Copy Anchor Link

5.1 Appointment Linking ArchitectureCopy Anchor Link

5.2 Extending AppointmentBlueprint (Zero-New-Endpoint Queue Data)Copy Anchor Link

5.3 Performance: Preloading in Queue::GenerateTodayCopy Anchor Link

5.4 Dual-Sync Rule: Synchronous Appointment-Encounter LinkingCopy Anchor Link

5.5 Retroactive & Batch Linking ServicesCopy Anchor Link

5.6 CMS Queue UI IntegrationCopy Anchor Link

5.6.1 Queue Row with Episode BadgeCopy Anchor Link

5.6.2 Queue Filter by EpisodeCopy Anchor Link

6. Multi-Specialty Integrated CareCopy Anchor Link

6.1 Single vs Integrated Episode ModelsCopy Anchor Link

6.2 Specialty Quota & Session DistributionCopy Anchor Link

6.3 Multi-Specialty Progress AggregationCopy Anchor Link

7. API Surface & Controller Re-useCopy Anchor Link

7.1 Existing Clinical Endpoints (To Reuse Directly)Copy Anchor Link

7.2 Parameter Extensions on Existing ControllersCopy Anchor Link

1. In Clinical::EpisodesOfCareController#episode_paramsCopy Anchor Link

2. In Clinical::AppointmentsController#appointment_paramsCopy Anchor Link

3. In Clinical::TreatmentGoalsController#goal_paramsCopy Anchor Link

7.3 Detailed Endpoint ContractsCopy Anchor Link

Status Transition ContractCopy Anchor Link

8. Frontend & UI Integration StrategyCopy Anchor Link

8.1 Existing CMS Episode Components (To Reuse & Extend)Copy Anchor Link

8.2 CMS Queue Components (Delta Deliverables)Copy Anchor Link

8.3 LHR (Provider) View IntegrationCopy Anchor Link

8.4 PHR (Patient Web App) Care Programs IntegrationCopy Anchor Link

9. Permissions, Authorization & SecurityCopy Anchor Link

9.1 Pundit Policy ArchitectureCopy Anchor Link

9.2 Role-Based Access Control (RBAC) MatrixCopy Anchor Link

9.3 Multi-Tenant Isolation EnforcementCopy Anchor Link

10. Re-Baselined Implementation RoadmapCopy Anchor Link

10.1 Phase 1: Database Delta Migrations & Model ExtensionsCopy Anchor Link

10.2 Phase 2: Serializer & Linking Service EnhancementsCopy Anchor Link

10.3 Phase 3: CMS Queue & LHR IntegrationCopy Anchor Link

10.4 Phase 4: Patient PHR Care Programs ModuleCopy Anchor Link

10.5 Phase 5: Verification, Tests & DocumentationCopy Anchor Link

11. AppendicesCopy Anchor Link

Appendix A: Codebase File ReferencesCopy Anchor Link

Appendix B: FHIR R4 EpisodeOfCare Specification MappingCopy Anchor Link

On this page

Table of Contents