# aditya15128/atc-interruptible-trainer architecture

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

- Interactive diagram: https://gitdiagram.com/aditya15128/atc-interruptible-trainer
- Repository: https://github.com/aditya15128/atc-interruptible-trainer

## Overview

ATC Voice Simulator is a voice-first training demo centered on interruptible, spoken flight and hotel searches. A pilot connects from the browser, transmits audio over LiveKit, and the agent uses speech recognition, an LLM and cancellable search tools before speaking results with Rime. The browser also exposes push-to-talk, tool status, transcript and provider indicators. The sampled backend shows interruption and tool-cancel messages, but not outbound status/transcript publishing; those UI updates are therefore not wired to an agent edge here. Phraseology retrieval is described in the README but no implementation is evidenced in the sampled runtime.

Main entry points: [`frontend/src/App.tsx`](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/App.tsx) (Simulator UI), [`agent/main.py`](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/main.py) (Agent Entrypoint), [`frontend/src/components/PushToTalk.tsx`](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/components/PushToTalk.tsx) (Push To Talk), [`agent/state.py`](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/state.py) (Conversation State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Pilot Client"]
  node_app["Simulator UI<br/>[App.tsx]"]
  node_ptt["Push To Talk<br/>[PushToTalk.tsx]"]
  node_toolstatus["Tool Status<br/>[ToolStatus.tsx]"]
  node_transcript["Transcript View<br/>[Transcript.tsx]"]
  node_providerbadge["Provider Badge<br/>[ProviderBadge.tsx]"]
end

subgraph group_transport["Realtime Transport"]
  node_livekit["LiveKit Room"]
end

subgraph group_agent["Agent Runtime"]
  node_entrypoint["Agent Entrypoint<br/>[main.py]"]
  node_session["Agent Session<br/>[main.py]"]
  node_state["Conversation State<br/>[state.py]"]
  node_instructions["Voice Instructions<br/>[instructions.py]"]
  node_search["Search Tools<br/>[main.py]"]
end

subgraph group_providers["Voice Providers"]
  node_deepgram["Deepgram STT"]
  node_openai["OpenAI LLM"]
  node_rime["Rime TTS"]
  node_fallback["OpenAI TTS Fallback"]
end

node_pilot(("Pilot"))

node_pilot -->|"uses"| node_app
node_app -->|"renders"| node_ptt
node_app -->|"renders"| node_toolstatus
node_app -->|"renders"| node_transcript
node_app -->|"renders"| node_providerbadge
node_ptt -->|"publishes audio"| node_livekit
node_ptt -->|"reports interrupts"| node_app
node_toolstatus -->|"requests cancel"| node_app
node_app -->|"connects and sends data"| node_livekit
node_livekit -->|"delivers room events"| node_entrypoint
node_entrypoint -->|"connects agent"| node_livekit
node_entrypoint -->|"starts"| node_session
node_entrypoint -->|"updates"| node_state
node_entrypoint -->|"registers tools"| node_search
node_session -->|"uses"| node_instructions
node_session -->|"transcribes audio"| node_deepgram
node_session -->|"processes turns"| node_openai
node_session -->|"synthesizes speech"| node_rime
node_session -.->|"may synthesize speech"| node_fallback
node_openai -->|"dispatches tool calls"| node_search
node_search -->|"updates phase"| node_state
node_entrypoint -->|"records interrupt fence"| node_state

click node_app "https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/App.tsx"
click node_ptt "https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/components/PushToTalk.tsx"
click node_toolstatus "https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/components/ToolStatus.tsx"
click node_transcript "https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/components/Transcript.tsx"
click node_providerbadge "https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/components/ProviderBadge.tsx"
click node_entrypoint "https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/main.py"
click node_session "https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/main.py"
click node_state "https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/state.py"
click node_instructions "https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/instructions.py"
click node_search "https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/main.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_app,node_ptt,node_toolstatus,node_transcript,node_providerbadge toneBlue
class node_livekit toneAmber
class node_entrypoint,node_session,node_state,node_instructions,node_search toneMint
class node_deepgram,node_openai,node_rime,node_fallback toneRose
class node_pilot toneIndigo
```

## Components

### Pilot Client

- [Simulator UI](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Push To Talk](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/components/PushToTalk.tsx): `frontend/src/components/PushToTalk.tsx`
- [Tool Status](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/components/ToolStatus.tsx): `frontend/src/components/ToolStatus.tsx`
- [Transcript View](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/components/Transcript.tsx): `frontend/src/components/Transcript.tsx`
- [Provider Badge](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/frontend/src/components/ProviderBadge.tsx): `frontend/src/components/ProviderBadge.tsx`

### Realtime Transport

- **LiveKit Room**

### Agent Runtime

- [Agent Entrypoint](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/main.py): `agent/main.py`
- [Agent Session](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/main.py): `agent/main.py`
- [Conversation State](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/state.py): `agent/state.py`
- [Voice Instructions](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/instructions.py): `agent/instructions.py`
- [Search Tools](https://github.com/aditya15128/atc-interruptible-trainer/blob/main/agent/main.py): `agent/main.py`

### Voice Providers

- **Deepgram STT**
- **OpenAI LLM**
- **Rime TTS**
- **OpenAI TTS Fallback**

### Other components

- **Pilot**

## Connections

- Pilot → Simulator UI: uses
- Simulator UI → Push To Talk: renders
- Simulator UI → Tool Status: renders
- Simulator UI → Transcript View: renders
- Simulator UI → Provider Badge: renders
- Push To Talk → LiveKit Room: publishes audio
- Push To Talk → Simulator UI: reports interrupts
- Tool Status → Simulator UI: requests cancel
- Simulator UI → LiveKit Room: connects and sends data
- LiveKit Room → Agent Entrypoint: delivers room events
- Agent Entrypoint → LiveKit Room: connects agent
- Agent Entrypoint → Agent Session: starts
- Agent Entrypoint → Conversation State: updates
- Agent Entrypoint → Search Tools: registers tools
- Agent Session → Voice Instructions: uses
- Agent Session → Deepgram STT: transcribes audio
- Agent Session → OpenAI LLM: processes turns
- Agent Session → Rime TTS: synthesizes speech
- Agent Session → OpenAI TTS Fallback: may synthesize speech
- OpenAI LLM → Search Tools: dispatches tool calls
- Search Tools → Conversation State: updates phase
- Agent Entrypoint → Conversation State: records interrupt fence