08 — Conversation & Chat Interface Design¶

Unified Chat Endpoint¶

All patient-agent interaction: POST /api/v1/patients/{id}/chat

Orchestrator classifies intent, routes to sub-agent. Frontend = single conversation thread, no page navigation for clinical workflows.

Message Schema¶

class ChatMessage:
    message_id: str               # UUID
    patient_id: str
    tenant_id: str
    role: str                     # 'patient' | 'agent' | 'system'
    content: str                  # message text
    content_type: str             # 'text' | 'document_status' | 'match_result' | 'action_prompt'
    agent_name: str | None        # intake | clinical_context | match | explanation
    metadata: dict                # extracted data, suggested actions, progress
    attachments: list[dict]       # document references (R2 storage keys)
    correlation_id: str
    created_at: datetime          # UTC

Conversation State Management¶

State maintained in events table, not in-memory. Enables: - Conversation resumption across sessions, devices, server restarts - Each agent turn appends to conversation_history in events payload - LLM receives windowed history (last N turns) + full patient profile from PostgreSQL - No conversation data lost on server restart or deploy

Chat Request Format¶

POST /api/v1/patients/{id}/chat
{
  "message": "I have a knee X-ray report to share",
  "attachments": [
    {
      "document_id": "doc-uuid",
      "filename": "knee_xray.pdf",
      "storage_key": "tenant-apollo-001/patient-aisha/doc-uuid"
    }
  ],
  "context": {
    "current_view": "conversation",
    "locale": "ar"
  }
}

Chat Response Format¶

{
  "message_id": "msg-uuid",
  "role": "agent",
  "agent_name": "intake",
  "content": "Thank you for sharing your X-ray report. I'm analyzing it now...",
  "content_type": "text",
  "suggested_actions": [
    {"type": "upload", "label": "Upload blood work", "icon": "📋"},
    {"type": "info", "label": "Tell me about medications", "icon": "💊"}
  ],
  "metadata": {
    "intake_progress": 0.45,
    "documents_processing": ["doc-uuid"]
  }
}

Frontend Chat Components¶

Conversation Column (centered, max-width 720px)¶

Agent messages: Plain text on page background, left-aligned
Patient messages: Teal pills, right-aligned
Document cards: Inline upload progress / analysis results
Match result cards: Provider cards with scores and reasoning
Suggested action chips: Tappable buttons below agent messages
Typing indicator: Pulsing dots during LLM generation

Message Types by content_type¶

content_type	Rendering
`text`	Standard message bubble
`document_status`	Document card with progress bar and status badge
`match_result`	Provider cards with confidence, cost, differentiators
`action_prompt`	Chips / buttons for suggested next actions
`ehr_update`	Subtle inline notification ("Added: M17.11 osteoarthritis")
`progress_update`	Progress bar update in right strip