# dcampuzano101/support-agent-demo architecture

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

- Interactive diagram: https://gitdiagram.com/dcampuzano101/support-agent-demo
- Repository: https://github.com/dcampuzano101/support-agent-demo

## Overview

This repository implements an airline customer-support voice agent with a companion FastAPI booking/refund service. The main workflow is caller speech through LiveKit, conversation triage, clarification or specialist dispatch, then a spoken reply or human handoff. Booking and refund specialists use the HTTP client to reach the backend; policy questions use semantic FAQ search. Source excerpts establish the agent routing, client operations, and backend persistence wiring. Other integrations are shown only where the excerpts support them.

Main entry points: [`agent/support_graph.py`](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/support_graph.py) (Turn router), [`agent/agent.py`](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/agent.py) (Voice session), [`mock_backend/main.py`](https://github.com/dcampuzano101/support-agent-demo/blob/main/mock_backend/main.py) (Booking and refund API), [`agent/order_api.py`](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/order_api.py) (Booking HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice and triage"]
  node_voice_entry["Voice session<br/>[agent.py]"]
  node_turn_router["Turn router<br/>[support_graph.py]"]
  node_classifier["Conversation triage<br/>[classifier.py]"]
  node_clarifier["Clarification response<br/>[support_graph.py]"]
  node_human_handoff["Human handoff<br/>[agent.py]"]
end

subgraph group_specialists["Support specialists"]
  node_booking_specialist["Booking lookup<br/>[subagents.py]"]
  node_refund_specialist["Refund handling<br/>[subagents.py]"]
  node_policy_specialist["Policy answers<br/>[subagents.py]"]
  node_faq_search["FAQ semantic search<br/>[policy_faq.py]"]
  node_booking_client["Booking HTTP client<br/>[order_api.py]"]
end

subgraph group_backend["Booking backend"]
  node_backend_api["Booking and refund API<br/>[main.py]"]
  node_api_schemas["API schemas<br/>[schemas.py]"]
  node_booking_models["Booking and refund models<br/>[models.py]"]
  node_db_session["Database sessions<br/>[db.py]"]
end

node_caller(("Caller"))
node_database[("Relational database")]
node_jev{{"Jev classifier service"}}
node_embedding_service{{"OpenAI embeddings"}}
node_livekit{{"LiveKit voice runtime"}}

node_caller -->|"speaks to"| node_voice_entry
node_voice_entry -->|"routes turns"| node_turn_router
node_turn_router -->|"triages conversation"| node_classifier
node_classifier -->|"classifies with"| node_jev
node_turn_router -->|"asks clarification"| node_clarifier
node_turn_router -->|"dispatches booking"| node_booking_specialist
node_turn_router -->|"dispatches refund"| node_refund_specialist
node_turn_router -->|"dispatches policy"| node_policy_specialist
node_voice_entry -->|"hands off"| node_human_handoff
node_booking_specialist -->|"requests booking"| node_booking_client
node_refund_specialist -->|"requests refund"| node_booking_client
node_policy_specialist -->|"searches FAQ"| node_faq_search
node_faq_search -->|"creates embeddings"| node_embedding_service
node_booking_client -->|"calls REST routes"| node_backend_api
node_backend_api -->|"validates responses"| node_api_schemas
node_backend_api -->|"queries and writes"| node_booking_models
node_backend_api -->|"uses sessions"| node_db_session
node_booking_models -->|"uses base"| node_db_session
node_db_session -->|"connects to"| node_database
node_voice_entry -->|"runs on"| node_livekit

click node_voice_entry "https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/agent.py"
click node_turn_router "https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/support_graph.py"
click node_classifier "https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/classifier.py"
click node_clarifier "https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/support_graph.py"
click node_human_handoff "https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/agent.py"
click node_booking_specialist "https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/subagents.py"
click node_refund_specialist "https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/subagents.py"
click node_policy_specialist "https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/subagents.py"
click node_faq_search "https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/policy_faq.py"
click node_booking_client "https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/order_api.py"
click node_backend_api "https://github.com/dcampuzano101/support-agent-demo/blob/main/mock_backend/main.py"
click node_api_schemas "https://github.com/dcampuzano101/support-agent-demo/blob/main/mock_backend/schemas.py"
click node_booking_models "https://github.com/dcampuzano101/support-agent-demo/blob/main/mock_backend/models.py"
click node_db_session "https://github.com/dcampuzano101/support-agent-demo/blob/main/mock_backend/db.py"

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_voice_entry,node_turn_router,node_classifier,node_clarifier,node_human_handoff toneBlue
class node_booking_specialist,node_refund_specialist,node_policy_specialist,node_faq_search,node_booking_client,node_database toneAmber
class node_backend_api,node_api_schemas,node_booking_models,node_db_session toneMint
class node_caller,node_jev,node_embedding_service,node_livekit toneIndigo
```

## Components

### Voice and triage

- [Voice session](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/agent.py): `agent/agent.py`
- [Turn router](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/support_graph.py): `agent/support_graph.py`
- [Conversation triage](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/classifier.py): `agent/classifier.py`
- [Clarification response](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/support_graph.py): `agent/support_graph.py`
- [Human handoff](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/agent.py): `agent/agent.py`

### Support specialists

- [Booking lookup](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/subagents.py): `agent/subagents.py`
- [Refund handling](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/subagents.py): `agent/subagents.py`
- [Policy answers](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/subagents.py): `agent/subagents.py`
- [FAQ semantic search](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/policy_faq.py): `agent/policy_faq.py`
- [Booking HTTP client](https://github.com/dcampuzano101/support-agent-demo/blob/main/agent/order_api.py): `agent/order_api.py`

### Booking backend

- [Booking and refund API](https://github.com/dcampuzano101/support-agent-demo/blob/main/mock_backend/main.py): `mock_backend/main.py`
- [API schemas](https://github.com/dcampuzano101/support-agent-demo/blob/main/mock_backend/schemas.py): `mock_backend/schemas.py`
- [Booking and refund models](https://github.com/dcampuzano101/support-agent-demo/blob/main/mock_backend/models.py): `mock_backend/models.py`
- [Database sessions](https://github.com/dcampuzano101/support-agent-demo/blob/main/mock_backend/db.py): `mock_backend/db.py`

### Other components

- **Caller**
- **Relational database**
- **Jev classifier service**
- **OpenAI embeddings**
- **LiveKit voice runtime**

## Connections

- Caller → Voice session: speaks to (evidence: `agent/agent.py`)
- Voice session → Turn router: routes turns (evidence: `agent/agent.py`)
- Turn router → Conversation triage: triages conversation (evidence: `agent/support_graph.py`)
- Conversation triage → Jev classifier service: classifies with (evidence: `agent/classifier.py`)
- Turn router → Clarification response: asks clarification (evidence: `agent/support_graph.py`)
- Turn router → Booking lookup: dispatches booking (evidence: `agent/support_graph.py`)
- Turn router → Refund handling: dispatches refund (evidence: `agent/support_graph.py`)
- Turn router → Policy answers: dispatches policy (evidence: `agent/support_graph.py`)
- Voice session → Human handoff: hands off (evidence: `agent/agent.py`)
- Booking lookup → Booking HTTP client: requests booking (evidence: `agent/subagents.py`)
- Refund handling → Booking HTTP client: requests refund (evidence: `agent/subagents.py`)
- Policy answers → FAQ semantic search: searches FAQ (evidence: `agent/subagents.py`)
- FAQ semantic search → OpenAI embeddings: creates embeddings (evidence: `agent/policy_faq.py`)
- Booking HTTP client → Booking and refund API: calls REST routes (evidence: `agent/order_api.py`)
- Booking and refund API → API schemas: validates responses (evidence: `mock_backend/main.py`)
- Booking and refund API → Booking and refund models: queries and writes (evidence: `mock_backend/main.py`)
- Booking and refund API → Database sessions: uses sessions (evidence: `mock_backend/main.py`)
- Booking and refund models → Database sessions: uses base (evidence: `mock_backend/models.py`)
- Database sessions → Relational database: connects to (evidence: `mock_backend/db.py`)
- Voice session → LiveKit voice runtime: runs on (evidence: `agent/agent.py`)
