# osamaqh4/hospital-voice-agent architecture

> Architecture diagram of the GitHub repository osamaqh4/hospital-voice-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/osamaqh4/hospital-voice-agent
- Repository: https://github.com/osamaqh4/hospital-voice-agent

## Overview

This is a Telnyx voice assistant for hospital appointment administration across General Medicine, Pediatrics, and Dental. A caller speaks with the Telnyx assistant, whose conversation flow handles intent, FAQs, and emergency escalation. At call start, a signed webhook normalizes the caller identity, records the call, and supplies patient and department context. During the call, the assistant invokes MCP tools to check or change appointments, find slots, and send confirmations. Patient records use the shared actor-or-KV abstraction; department data and the same-day-slots flag use KV. The conversation flow is documented in the exported JSON; links among its individual nodes reflect that documentation.

Main entry points: [`mcp-server/src/index.ts`](https://github.com/osamaqh4/hospital-voice-agent/blob/main/mcp-server/src/index.ts) (MCP tool server), [`docs/conversation-flow.json`](https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json) (Identify intent), [`webhook-function/src/index.ts`](https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/index.ts) (Dynamic variables handler), [`webhook-function/src/lib/patientRecords.ts`](https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/lib/patientRecords.ts) (Patient record selector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice conversation"]
  node_assistant["Telnyx AI assistant"]
  node_intent["Identify intent"]
  node_existing["Existing appointment"]
  node_booking["Book appointment"]
  node_faq["Department FAQ"]
  node_emergency["Emergency escalation"]
  node_closing["Close call"]
end

subgraph group_webhook["Call initialization"]
  node_webhook_handler["Dynamic variables handler<br/>[index.ts]"]
  node_phone["Phone normalization<br/>[phone.ts]"]
end

subgraph group_mcp["Appointment tools"]
  node_mcp_handler["MCP tool server<br/>[index.ts]"]
  node_patient_client["Patient record client"]
  node_slots["Slot scheduling<br/>[scheduling.ts]"]
  node_sms_sender["SMS sender<br/>[telnyxApi.ts]"]
end

subgraph group_data["State and integrations"]
  node_record_api["Patient record selector<br/>[patientRecords.ts]"]
  node_actor["Patient actor<br/>[patientActor.ts]"]
  node_patient_kv[("Patient records KV<br/>[patientRecords.ts]")]
  node_directory[("Department KV data<br/>[kv.ts]")]
end

node_caller(("Caller"))
node_telnyx_messaging["Telnyx Messaging"]

node_caller -->|"calls"| node_assistant
node_assistant -->|"requests call context"| node_webhook_handler
node_assistant -->|"invokes tools"| node_mcp_handler
node_assistant -->|"runs flow"| node_intent
node_intent -->|"routes appointment requests"| node_existing
node_intent -->|"routes booking"| node_booking
node_intent -->|"routes questions"| node_faq
node_intent -->|"escalates emergencies"| node_emergency
node_faq -->|"escalates emergencies"| node_emergency
node_existing -->|"ends call"| node_closing
node_booking -->|"ends call"| node_closing
node_faq -->|"ends call"| node_closing
node_emergency -->|"ends call"| node_closing
node_webhook_handler -->|"normalizes caller"| node_phone
node_webhook_handler -->|"records call"| node_record_api
node_webhook_handler -->|"reads directory and flag"| node_directory
node_webhook_handler -->|"returns dynamic variables"| node_assistant
node_record_api -.->|"selects when enabled"| node_actor
node_record_api -->|"reads and writes fallback"| node_patient_kv
node_mcp_handler -->|"normalizes patient number"| node_phone
node_mcp_handler -->|"dispatches patient operations"| node_patient_client
node_patient_client -->|"accesses patient records"| node_record_api
node_mcp_handler -->|"reads slots flag and directory"| node_directory
node_mcp_handler -->|"computes available slots"| node_slots
node_mcp_handler -->|"sends confirmation"| node_sms_sender
node_sms_sender -->|"sends SMS"| node_telnyx_messaging

click node_intent "https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json"
click node_existing "https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json"
click node_booking "https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json"
click node_faq "https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json"
click node_emergency "https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json"
click node_closing "https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json"
click node_webhook_handler "https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/index.ts"
click node_phone "https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/lib/phone.ts"
click node_record_api "https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/lib/patientRecords.ts"
click node_actor "https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/actors/patientActor.ts"
click node_patient_kv "https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/lib/patientRecords.ts"
click node_directory "https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/lib/kv.ts"
click node_mcp_handler "https://github.com/osamaqh4/hospital-voice-agent/blob/main/mcp-server/src/index.ts"
click node_patient_client "https://github.com/osamaqh4/hospital-voice-agent/blob/main/mcp-server/src/lib/patientActorClient.ts"
click node_slots "https://github.com/osamaqh4/hospital-voice-agent/blob/main/mcp-server/src/lib/scheduling.ts"
click node_sms_sender "https://github.com/osamaqh4/hospital-voice-agent/blob/main/mcp-server/src/lib/telnyxApi.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_assistant,node_intent,node_existing,node_booking,node_faq,node_emergency,node_closing toneBlue
class node_webhook_handler,node_phone toneAmber
class node_mcp_handler,node_patient_client,node_slots,node_sms_sender toneMint
class node_record_api,node_actor,node_patient_kv,node_directory toneRose
class node_caller,node_telnyx_messaging toneIndigo
```

## Components

### Voice conversation

- **Telnyx AI assistant**
- [Identify intent](https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json): `docs/conversation-flow.json`
- [Existing appointment](https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json): `docs/conversation-flow.json`
- [Book appointment](https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json): `docs/conversation-flow.json`
- [Department FAQ](https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json): `docs/conversation-flow.json`
- [Emergency escalation](https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json): `docs/conversation-flow.json`
- [Close call](https://github.com/osamaqh4/hospital-voice-agent/blob/main/docs/conversation-flow.json): `docs/conversation-flow.json`

### Call initialization

- [Dynamic variables handler](https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/index.ts): `webhook-function/src/index.ts`
- [Phone normalization](https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/lib/phone.ts): `webhook-function/src/lib/phone.ts`

### Appointment tools

- [MCP tool server](https://github.com/osamaqh4/hospital-voice-agent/blob/main/mcp-server/src/index.ts): `mcp-server/src/index.ts`
- [Patient record client](https://github.com/osamaqh4/hospital-voice-agent/blob/main/mcp-server/src/lib/patientActorClient.ts): `mcp-server/src/lib/patientActorClient.ts`
- [Slot scheduling](https://github.com/osamaqh4/hospital-voice-agent/blob/main/mcp-server/src/lib/scheduling.ts): `mcp-server/src/lib/scheduling.ts`
- [SMS sender](https://github.com/osamaqh4/hospital-voice-agent/blob/main/mcp-server/src/lib/telnyxApi.ts): `mcp-server/src/lib/telnyxApi.ts`

### State and integrations

- [Patient record selector](https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/lib/patientRecords.ts): `webhook-function/src/lib/patientRecords.ts`
- [Patient actor](https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/actors/patientActor.ts): `webhook-function/src/actors/patientActor.ts`
- [Patient records KV](https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/lib/patientRecords.ts): `webhook-function/src/lib/patientRecords.ts`
- [Department KV data](https://github.com/osamaqh4/hospital-voice-agent/blob/main/webhook-function/src/lib/kv.ts): `webhook-function/src/lib/kv.ts`

### Other components

- **Caller**
- **Telnyx Messaging**

## Connections

- Caller → Telnyx AI assistant: calls
- Telnyx AI assistant → Dynamic variables handler: requests call context
- Telnyx AI assistant → MCP tool server: invokes tools
- Telnyx AI assistant → Identify intent: runs flow
- Identify intent → Existing appointment: routes appointment requests
- Identify intent → Book appointment: routes booking
- Identify intent → Department FAQ: routes questions
- Identify intent → Emergency escalation: escalates emergencies
- Department FAQ → Emergency escalation: escalates emergencies
- Existing appointment → Close call: ends call
- Book appointment → Close call: ends call
- Department FAQ → Close call: ends call
- Emergency escalation → Close call: ends call
- Dynamic variables handler → Phone normalization: normalizes caller
- Dynamic variables handler → Patient record selector: records call
- Dynamic variables handler → Department KV data: reads directory and flag
- Dynamic variables handler → Telnyx AI assistant: returns dynamic variables
- Patient record selector → Patient actor: selects when enabled
- Patient record selector → Patient records KV: reads and writes fallback
- MCP tool server → Phone normalization: normalizes patient number
- MCP tool server → Patient record client: dispatches patient operations
- Patient record client → Patient record selector: accesses patient records
- MCP tool server → Department KV data: reads slots flag and directory
- MCP tool server → Slot scheduling: computes available slots
- MCP tool server → SMS sender: sends confirmation
- SMS sender → Telnyx Messaging: sends SMS