Immunization Record Feature

// frontend/apps/cms/src/features/encounter/types/pediatricTypes.ts

interface ImmunizationRecordData {
  vaccinations: VaccinationEntry[]  // List of all vaccination records
  generalNotes?: string            // Encounter-level immunization notes
}

interface VaccinationEntry {
  id: string                       // Unique identifier (client-generated)
  name: string                     // Vaccine name (e.g., "DPT-1", "BCG")
  ageRange: string                 // Schedule label (e.g., "Birth", "6 weeks")
  doseNumber?: DoseNumber           // Position in series: '0' | '1' | '2' | '3' | '4' | '5' | 'booster'
  dueDate?: string                 // YYYY-MM-DD — scheduled administration date
  givenDate?: string               // YYYY-MM-DD — actual administration date
  status: ImmunizationStatus       // 'given' | 'due' | 'overdue' | 'upcoming' | 'missed'
  // Clinical documentation fields
  lotNumber?: string               // Vaccine batch/lot number (for recall tracing)
  expirationDate?: string          // YYYY-MM-DD — vaccine expiration date
  manufacturer?: string            // Vaccine manufacturer (e.g., "Serum Institute")
  administeredBy?: string          // Name of administering healthcare provider
  administrationSite?: AdministrationSite  // Anatomical site of injection
  administrationRoute?: AdministrationRoute // IM, SC, ID, oral, nasal, other
  adverseReaction?: AdverseReaction        // none | mild | moderate | severe | anaphylaxis
  notes?: string                   // Free-text notes for this vaccination
}

Patient encounter opened
  │
  ▼
useEncounterClinicalData (hooks/useEncounterClinicalData.ts)
  │
  ├─► useObservations({ encounter_id })
  │     └─► API: GET /clinical/observations?encounter_id=...
  │
  ▼
obsByCategory.get('immunization_record')
  │
  ▼
parseImmunizationRecord()  (hooks/clinicalDataParsers.ts)
  │   └─► JSON.parse(observation.value) → ImmunizationRecordData
  │
  ▼
immunizationRecord passed to ImmunizationRecordTab as `record` prop

User modifies vaccination in ImmunizationRecordTab
  │
  ▼
onRecordChange({ ...record, vaccinations: [...] })
  │
  ▼
EncounterPage: setClinicalData(prev => ({ ...prev, immunizationRecord }))
  │
  ▼
User clicks Save / auto-save triggers
  │
  ▼
prepareClinicalDataForSave(data)
  │
  ├─► extracts immunizationRecord
  ├─► checks hasContent: vaccinations.length > 0 OR generalNotes exists
  │
  ├─► [Has content] → builds batch save payload:
  │     observations['immunization_record'] = [{
  │       code: { display: 'Immunization Record', text: 'Immunization Record' },
  │       value: JSON.stringify(immunizationRecord)
  │     }]
  │
  └─► [No content] → observation cleared on save (empty array)
        └─► DELETE /clinical/observations/:id (old record removed)

// frontend/apps/cms/src/features/encounter/pages/EncounterPage.tsx

// Patient birth date is extracted from clinicalPatientResponse
const normalizedPatient = useMemo(() => {
  // ...
  birth_date: p.birth_date || undefined,
  // ...
}, [clinicalPatientResponse, clinicalEncounter]);

// Passed to the tab for schedule due date calculation
{activeTab === "immunization" && (
  <ImmunizationRecordTab
    record={clinicalData.immunizationRecord}
    onRecordChange={handleImmunizationRecordChange}
    birthDate={normalizedPatient?.birth_date}
  />
)}

frontend/apps/cms/src/features/encounter/
├── types/
│   └── pediatricTypes.ts          # All immunization types, constants, schedule
├── components/tabs/
│   └── ImmunizationRecordTab.tsx   # Main component (add/edit/display)
└── hooks/
    ├── useEncounterClinicalData.ts      # Data fetching & parsing
    ├── clinicalDataParsers.ts           # parseImmunizationRecord()
    └── useEncounterTypeConfig.ts       # Tab registry (immunization tab)

// Immunization Status
IMMUNIZATION_STATUS_LABELS   // Display labels for each status
IMMUNIZATION_STATUS_COLORS   // Badge color classes per status

// Dose Numbers
DOSE_NUMBER_LABELS           // '0' → 'Birth Dose (0)', '1' → '1st Dose (1)', etc.

// Administration
ADMIN_ROUTE_LABELS           // IM, SC, ID, oral, nasal, other
ADMIN_SITE_LABELS            // Left Deltoid, Right Thigh, Buttock, etc.

// Adverse Reactions
ADVERSE_REACTION_LABELS      // none, mild, moderate, severe, anaphylaxis
ADVERSE_REACTION_COLORS     // Color-coded badge classes

// Schedule
STANDARD_VACCINATION_SCHEDULE  // 31 vaccines with ageDays offsets
calculateDueDate(birthDate, ageDays)  // Returns YYYY-MM-DD string