EncounterPage Functional Workflow Documentation

/encounter/:encounterId?patientId=X&appointmentId=Y&practitionerType=Z

1. Page URL is parsed for encounterId, patientId, appointmentId, practitionerType
2. Practitioner type is resolved from URL → encounter data → default
3. Encounter Type Config is fetched for the practitioner type
4. Encounter metadata is fetched from the clinical API (status, start time, practitioner, facility)
5. Patient details are fetched from the clinical API (name, age, gender, allergies, conditions)
6. All clinical data is fetched from the clinical API (vitals, observations, medications, etc.)
7. Clinical data is "seeded" into local state — the page becomes interactive

1. User clicks "Save" button
2. Button shows loading spinner (isSaving = true)
3. System identifies which tabs are active for the current practitioner type
4. All clinical data is sent to the batch save endpoint via saveBatch()
5. Batch endpoint persists vitals, observations, medications, investigations, etc.
6. If investigations were saved, the response contains server-assigned UUIDs
7. Local investigation state is updated with these UUIDs (prevents stale deletes)
8. hasUnsavedChanges = false
9. Success alert shown for 3 seconds
10. If error: error alert shown for 5 seconds

1. User clicks "Finalize" button
2. Button shows loading spinner (isCompleting = true)
3. completeEncounter() is called
4. Encounter status transitions to "completed" on the server
5. Encounter is re-fetched to show updated status
6. Success alert shown for 3 seconds
7. Page remains viewable but in read-only mode
8. If error: error alert shown for 5 seconds

┌─────────────────────────────────────────────────────────────┐
│ STEP 1: Page Load                                           │
├─────────────────────────────────────────────────────────────┤
│ User arrives from dashboard/queue with encounterId           │
│                                                             │
│ System parses URL → encounterId, patientId, appointmentId    │
│ System determines practitioner type (URL → encounter → default)
│ System fetches: encounter metadata, patient details,         │
│   encounter type config, all clinical data                   │
│                                                             │
│ Loading state: Full-page skeleton                           │
│                                                             │
│ Data arrives → Clinical data seeded into local state        │
│ Default tab set from encounter type config                  │
│ Page becomes interactive                                     │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 2: Review Patient Context                              │
├─────────────────────────────────────────────────────────────┤
│ Patient header shows: name, age, gender, phone              │
│ Medical context: allergies (highlighted), diseases           │
│ Encounter context: status badge, start time, practitioner    │
│                                                             │
│ User can toggle AI Scribe sidebar (if appointmentId exists) │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 3: Navigate Tabs & Fill Clinical Data                  │
├─────────────────────────────────────────────────────────────┤
│ User clicks through tabs (Vitals → Observations → etc.)    │
│ Each tab pre-populated with seeded data                     │
│                                                             │
│ On every change:                                            │
│   → Local state updated                                     │
│   → hasUnsavedChanges = true                                │
│   → Unsaved indicator appears below tabs                    │
│                                                             │
│ Tab-specific behavior:                                       │
│   • Vitals: Age/gender-aware reference ranges               │
│   • Observations: AI suggestions integration                │
│   • Medications: Allergy alerts, drug interaction checking  │
│   • Investigations: Lab/imaging/referral categorization    │
│   • Dental: Tooth chart selection, ADA codes                │
│   • Clinical History: Psychiatric history structured input   │
│   • Physical exams: Structured findings by system          │
│   • Procedures: Procedure codes, dates, notes               │
│   • Photo Documentation: File upload                        │
│   • Consent: Procedure consent tracking                    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 4: AI Scribe (Optional)                                │
├─────────────────────────────────────────────────────────────┤
│ If appointmentId exists and AI Scribe is enabled:           │
│   User opens AI Scribe sidebar                              │
│   Live transcription of consultation                        │
│   AI generates suggestions:                                  │
│     • Medication suggestions → click to add to Medications tab
│     • Test suggestions → click to add to Investigations tab │
│     • Diagnosis suggestions → appended to Observations tab   │
│                                                             │
│ Accept: Applies suggestion, marks as accepted                │
│ Reject: Dismisses suggestion, marks as rejected              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 5: Save Clinical Data                                  │
├─────────────────────────────────────────────────────────────┤
│ User clicks "Save" button                                   │
│                                                             │
│ Save button: Always visible, enabled even with no changes    │
│ Spinner shown while saving                                  │
│                                                             │
│ Success: Green alert "Encounter saved successfully"         │
│          hasUnsavedChanges = false                          │
│                                                             │
│ Error: Red alert "Failed to save clinical data"             │
│        Data remains in local state, user can retry          │
│                                                             │
│ Note: User should save before navigating away —            │
│       unsaved local state is lost on navigation             │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 6: Finalize Encounter (Optional)                       │
├─────────────────────────────────────────────────────────────┤
│ User clicks "Finalize" button                               │
│                                                             │
│ Only shown for practitioners with appropriate permissions    │
│                                                             │
│ On finalize:                                                │
│   → Encounter status → "completed" on server                 │
│   → Encounter re-fetched to sync status                      │
│   → "Finalized" badge shown in header                      │
│   → Further edits may be restricted depending on settings   │
│                                                             │
│ Note: Finalization is a one-way transition (to some states) │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ STEP 7: Navigate Away                                       │
├─────────────────────────────────────────────────────────────┤
│ User clicks "Cancel" or browser back                        │
│                                                             │
│ If hasUnsavedChanges = true:                                │
│   → No confirmation dialog is shown                         │
│   → Data is simply lost                                     │
│   → No warning to user                                      │
│                                                             │
│ If hasUnsavedChanges = false:                               │
│   → Clean navigation to dashboard                           │
└─────────────────────────────────────────────────────────────┘

URL Parameters
├── encounterId (required)
├── patientId (optional — fallback to encounter.patient_id)
├── appointmentId (optional — enables AI Scribe)
└── practitionerType (optional — fallback to encounter.practitioner_type → "doctor")

External API Data (fetched on load)
├── Encounter metadata (status, times, practitioner, facility)
├── Patient demographics (name, age, gender, allergies, conditions)
├── Encounter Type Config (tab visibility, defaults)
└── Clinical Data (all domain objects)

Local State (clinicalData)
├── 45+ domain objects managed via individual onChange handlers
├── Seeded once from API, then mutated locally
└── Persisted via batch save

UI State
├── activeTab: which tab is currently shown
├── hasUnsavedChanges: tracks if local edits need saving
├── saveSuccess / saveError: save feedback
├── isCompleting: finalize loading state
├── isAIScribeOpen: sidebar visibility
└── aiSuggestions: list of AI-generated suggestions