Episode of Care Implementation Plan

Status: Planned Priority: High Dependencies: None

Overview

An Episode of Care represents a longitudinal course of treatment spanning multiple encounters. It provides the container for grouping related clinical encounters into a cohesive treatment program.

Problem Statement

Current Limitation: Encounters exist independently without grouping into treatment programs.

Impact:

Physiotherapists cannot track progress across a 12-session rehab program
Therapists cannot monitor treatment goals over multiple sessions
Dietitians cannot measure outcomes across a weight management program
No way to track "sessions completed" vs "sessions planned"

Data Model

EpisodeOfCare Table

create_table :episodes_of_care do |t|
  t.references :patient, null: false, foreign_key: true
  t.references :clinic, null: false, foreign_key: true
  t.references :primary_provider, foreign_key: { to_table: :users }

  # Episode identification
  t.string :episode_type      # therapy | physio | nutrition | chronic_care
  t.string :status            # active | on_hold | completed | discharged
  t.string :reason            # chief complaint / referral reason
  t.string :title             # "Post-ACL Rehab" (optional display name)

  # Dates
  t.date :start_date
  t.date :end_date
  t.date :target_end_date

  # Session tracking
  t.integer :total_sessions_planned
  t.integer :sessions_completed, default: 0
  t.string :frequency         # weekly | biweekly | monthly | as_needed

  # Content
  t.text :long_term_goals
  t.text :discharge_summary
  t.jsonb :metadata, default: {}

  t.boolean :deleted, default: false
  t.timestamps
end

add_index :episodes_of_care, [:patient_id, :status]
add_index :episodes_of_care, [:clinic_id, :status]
add_index :episodes_of_care, :episode_type

Model Associations

class EpisodeOfCare < ApplicationRecord
  belongs_to :patient
  belongs_to :clinic
  belongs_to :primary_provider, class_name: 'User', optional: true

  has_many :encounters
  has_many :treatment_goals, dependent: :destroy
  has_many :progress_notes, dependent: :destroy

  enum status: {
    active: 'active',
    on_hold: 'on_hold',
    completed: 'completed',
    discharged: 'discharged'
  }

  enum episode_type: {
    therapy: 'therapy',
    physio: 'physio',
    nutrition: 'nutrition',
    chronic_care: 'chronic_care'
  }
end

Update Encounter Model

class Encounter < ApplicationRecord
  belongs_to :episode_of_care, optional: true  # Can be standalone

  # Existing associations remain unchanged
  belongs_to :patient
  belongs_to :clinic
  belongs_to :practitioner, polymorphic: true
end

# Migration
add_reference :encounters, :episode_of_care, foreign_key: true, null: true

TreatmentGoal Table

create_table :treatment_goals do |t|
  t.references :episode_of_care, null: false, foreign_key: true
  t.references :created_by, foreign_key: { to_table: :users }

  t.text :description
  t.string :status           # active | achieved | discontinued
  t.date :target_date
  t.date :achieved_date
  t.integer :progress_percentage, default: 0
  t.text :notes

  t.timestamps
end

API Endpoints

# Episode CRUD
GET    /api/v1/patients/:patient_id/episodes_of_care
POST   /api/v1/patients/:patient_id/episodes_of_care
GET    /api/v1/episodes_of_care/:id
PATCH  /api/v1/episodes_of_care/:id
DELETE /api/v1/episodes_of_care/:id

# Episode encounters
GET    /api/v1/episodes_of_care/:id/encounters
POST   /api/v1/episodes_of_care/:id/encounters

# Treatment goals
GET    /api/v1/episodes_of_care/:id/treatment_goals
POST   /api/v1/episodes_of_care/:id/treatment_goals
PATCH  /api/v1/episodes_of_care/:id/treatment_goals/:goal_id
DELETE /api/v1/episodes_of_care/:id/treatment_goals/:goal_id

# Progress notes
GET    /api/v1/episodes_of_care/:id/progress_notes
POST   /api/v1/episodes_of_care/:id/progress_notes

Frontend Components

New Components

Component	Purpose
`EpisodeList`	List all episodes for a patient
`EpisodeDetail`	Episode overview with progress, goals, sessions
`EpisodeCreate`	Create new treatment program
`EpisodeProgress`	Visual progress tracking (sessions, goals)
`TreatmentGoalManager`	CRUD for treatment goals within Episode

Updated Components

Component	Update
`PatientSummaryDashboard`	Add "Active Episodes" card
`EncounterHistory`	Group by Episode (collapsible)
`EncounterHeader`	Show Episode badge if linked
`EncounterCreate`	Option to link to existing Episode

UI/UX Design

Episode Detail View

+-----------------------------------------------------------+
| Episode: Post-ACL Rehab                [<- Back to LHR]   |
| Patient: John Doe                      [View Full LHR]    |
| --------------------------------------------------------- |
| Progress: ████████░░░░ 5/12 sessions                      |
| Frequency: Weekly | Started: Dec 1 | Target End: Feb 28   |
| --------------------------------------------------------- |
| Treatment Goals                        [+ Add Goal]       |
| +-------------------------------------------------------+ |
| | 1. Restore full ROM (90%)                   [Edit]    | |
| | 2. Return to sports activities (0%)         [Edit]    | |
| +-------------------------------------------------------+ |
| --------------------------------------------------------- |
| Sessions in this Episode               [+ Add Session]    |
| +-------------------------------------------------------+ |
| | Session 5 - Dec 24                  [Open Encounter]  | |
| | Session 4 - Dec 17                  [Open Encounter]  | |
| | Session 3 - Dec 10                  [Open Encounter]  | |
| | ...                                                   | |
| +-------------------------------------------------------+ |
+-----------------------------------------------------------+

LHR Active Episodes Card

+-----------------------------------------------------------+
| Active Episodes                          [View All ->]    |
| +-------------------------------------------------------+ |
| | Post-ACL Rehab (5/12)              [Open] [+ Session] | |
| | Anxiety Treatment (3/10)           [Open] [+ Session] | |
| +-------------------------------------------------------+ |
+-----------------------------------------------------------+

Implementation Steps

Phase 1: Database & Models

Create EpisodeOfCare migration
Create TreatmentGoal migration
Create ProgressNote migration
Add episode_of_care_id to encounters
Create models with validations and scopes

Phase 2: Backend API

Create EpisodesOfCareController
Create TreatmentGoalsController
Create serializers for Episode data
Add Episode context to LHR endpoint response

Phase 3: Frontend Components

Create Episode types and API hooks
Build EpisodeList and EpisodeDetail components
Build TreatmentGoalManager component
Update EncounterCreate with Episode linking

Phase 4: LHR Integration

Update PatientSummaryDashboard
Update EncounterHistory with Episode grouping
Add Episode filter to trends views

Backward Compatibility

Existing encounters: Continue to work without episode linking
Standalone encounters: Acute care, walk-ins remain standalone
Episode linking: Optional, not required
LHR aggregation: Shows all data regardless of episode grouping

Episode of Care Implementation Plan

OverviewCopy Anchor Link

Problem StatementCopy Anchor Link

Data ModelCopy Anchor Link

EpisodeOfCare TableCopy Anchor Link

Model AssociationsCopy Anchor Link

Update Encounter ModelCopy Anchor Link

TreatmentGoal TableCopy Anchor Link

API EndpointsCopy Anchor Link

Frontend ComponentsCopy Anchor Link

New ComponentsCopy Anchor Link

Updated ComponentsCopy Anchor Link

UI/UX DesignCopy Anchor Link

Episode Detail ViewCopy Anchor Link

LHR Active Episodes CardCopy Anchor Link

Implementation StepsCopy Anchor Link

Phase 1: Database & ModelsCopy Anchor Link

Phase 2: Backend APICopy Anchor Link

Phase 3: Frontend ComponentsCopy Anchor Link

Phase 4: LHR IntegrationCopy Anchor Link

Backward CompatibilityCopy Anchor Link

Related DocumentationCopy Anchor Link

On this page