Clinical Data Hierarchy Architecture

Patient
   |
   +-- Longitudinal Health Record (LHR) <-- AGGREGATE VIEW (computed, not stored)
   |       |
   |       +-- Problems (can be linked to episodes)
   |       +-- Medications (from encounters, linked to episodes)
   |       +-- Vitals/Measurements (from encounters)
   |       +-- Assessments (from encounters, trended by episode)
   |       +-- Encounter History (grouped by episode)
   |       +-- Health Score (computed from problems, vitals, medications)
   |
   +-- Episodes of Care <-- PROGRAM CONTAINERS (stored)
   |       |
   |       +-- Episode: "Post-ACL Rehab" (physiotherapy)
   |       |       +-- Treatment Goals
   |       |       +-- Progress Notes
   |       |       +-- Encounters (1..N physio sessions)
   |       |
   |       +-- Episode: "Anxiety Treatment" (therapy)
   |       |       +-- Treatment Goals
   |       |       +-- Safety Plans
   |       |       +-- Encounters (1..N therapy sessions)
   |       |
   |       +-- Episode: "Weight Management" (nutrition)
   |               +-- Meal Plans
   |               +-- Nutritional Assessments
   |               +-- Encounters (1..N consultations)
   |
   +-- Standalone Encounters <-- NO EPISODE
           +-- One-off visits
           +-- Acute care
           +-- Walk-in appointments

# LHR aggregates data from:
- Patient.episodes_of_care.active      # Current treatment programs
- Patient.encounters                   # All visits (with and without episodes)
- Patient.problems                     # Tracked conditions
- Patient.medications                  # Active and historical medications
- Patient.clinical_measurements        # All vitals from all encounters
- Patient.assessment_responses         # All assessments from all encounters

class EpisodeOfCare
  belongs_to :patient
  belongs_to :clinic
  belongs_to :primary_provider, class_name: 'User'

  has_many :encounters
  has_many :treatment_goals
  has_many :progress_notes

  # Episode metadata
  # - episode_type: therapy | physio | nutrition | chronic_care
  # - status: active | on_hold | completed | discharged
  # - total_sessions_planned
  # - sessions_completed
  # - frequency: weekly | biweekly | monthly | as_needed
end

class Encounter
  belongs_to :patient
  belongs_to :clinic
  belongs_to :episode_of_care, optional: true  # Can be standalone

  has_many :encounter_documents   # 1:N documents per encounter
  has_many :clinical_measurements # Vitals, ROM, anthropometrics
  has_many :assessment_responses  # PHQ-9, GAD-7, etc.
  has_many :encounter_notes       # Clinical notes with visibility
  has_many :encounter_attachments # Files, images, videos
end

Encounter (atomic)
    |
    +-- Creates: Vitals, Medications, Notes, Assessments
    |
    v
Episode of Care (if linked)
    |
    +-- Aggregates: Session count, Goal progress, Treatment timeline
    |
    v
Longitudinal Health Record (computed)
    |
    +-- Aggregates: All data across all encounters and episodes
    +-- Computes: Health score, trends, alerts

Longitudinal Health Record
    |
    +-- Displays: Active Episodes with progress
    |
    v
Episode of Care
    |
    +-- Lists: All sessions in this treatment program
    |
    v
Encounter
    |
    +-- Shows: Full clinical documentation for this visit

+-----------------------------------------------------------+
| LHR Dashboard                                              |
| +-------------------------------------------------------+ |
| | Active Episodes                      [View All ->]    | |
| | * Post-ACL Rehab (5/12 sessions)     [Open Episode]   | |
| | * Anxiety Treatment (3/10)           [Open Episode]   | |
| +-------------------------------------------------------+ |
| +-------------------------------------------------------+ |
| | Recent Encounters                    [View All ->]    | |
| | * Dec 24 - Physio (in Post-ACL)      [Open]           | |
| | * Dec 20 - Therapy (in Anxiety)      [Open]           | |
| | * Dec 18 - GP Visit (standalone)     [Open]           | |
| +-------------------------------------------------------+ |
+-----------------------------------------------------------+

+-----------------------------------------------------------+
| Episode: Post-ACL Rehab                [<- Back to LHR]   |
| Patient: John Doe                      [View Full LHR]    |
| --------------------------------------------------------- |
| Progress: ████████░░░░ 5/12 sessions                      |
| +-------------------------------------------------------+ |
| | Sessions in this Episode                              | |
| | * Session 5 - Dec 24                [Open Encounter]  | |
| | * Session 4 - Dec 17                [Open Encounter]  | |
| | * ...                                                 | |
| +-------------------------------------------------------+ |
| [+ Add Session]                                           |
+-----------------------------------------------------------+

+-----------------------------------------------------------+
| Encounter: Physio Session #5           [<- Back to Episode]|
| Episode: Post-ACL Rehab                [View Full LHR]    |
| Patient: John Doe                                         |
| --------------------------------------------------------- |
| [Encounter content: ROM, exercises, notes, etc.]          |
+-----------------------------------------------------------+

For encounter within episode:
  Patient: John Doe > Episodes > Post-ACL Rehab > Session 5

For standalone encounter:
  Patient: John Doe > Encounters > Dec 18 GP Visit

For LHR view:
  Patient: John Doe > Health Record

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

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

GET    /api/v1/episodes_of_care/:id/treatment_goals
POST   /api/v1/episodes_of_care/:id/treatment_goals

GET    /api/v1/clinics/:clinic_id/patients/:patient_id/longitudinal_health_record
GET    /api/v1/clinics/:clinic_id/patients/:patient_id/longitudinal_health_record/problems
GET    /api/v1/clinics/:clinic_id/patients/:patient_id/longitudinal_health_record/vitals_trends
GET    /api/v1/clinics/:clinic_id/patients/:patient_id/longitudinal_health_record/medications_timeline

{
  "patient": { ... },
  "health_score": 78,
  "active_episodes": [
    {
      "id": 123,
      "episode_type": "physio",
      "title": "Post-ACL Rehab",
      "status": "active",
      "sessions_completed": 5,
      "total_sessions_planned": 12,
      "primary_provider": { "id": 456, "name": "Dr. Smith" },
      "next_session": "2025-12-27T10:00:00Z"
    }
  ],
  "recent_encounters": [
    {
      "id": 789,
      "date": "2025-12-24",
      "type": "physio_session",
      "episode_id": 123,
      "episode_title": "Post-ACL Rehab"
    }
  ],
  "problems": [ ... ],
  "vitals_trends": [ ... ],
  "medications": [ ... ]
}