# patrikszepesi/voice-agents architecture

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

- Interactive diagram: https://gitdiagram.com/patrikszepesi/voice-agents
- Repository: https://github.com/patrikszepesi/voice-agents

## Overview

This repository implements a hotel voice assistant and a separate Streamlit conversation-log viewer. The main workflow is guest speech captured by the audio streamer, processed through a Bedrock streaming session, and returned as spoken audio; model tool requests can perform guest-profile and reservation operations against DynamoDB. The viewer parses the assistant log into conversation, event, and token-usage displays. The excerpts establish the audio queues, tool dispatch, and database access, but do not show all tool-routing details; the tool-execution link is therefore marked unverified.

Main entry points: [`hotel_agent.py`](https://github.com/patrikszepesi/voice-agents/blob/master/hotel_agent.py) (Bedrock Stream), [`db_setup.py`](https://github.com/patrikszepesi/voice-agents/blob/master/db_setup.py) (Demo Data Setup), [`app.py`](https://github.com/patrikszepesi/voice-agents/blob/master/app.py) (Conversation Viewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice Assistant"]
  node_audio["Audio I/O<br/>[hotel_agent.py]"]
  node_stream["Bedrock Stream<br/>[hotel_agent.py]"]
end

subgraph group_hotel["Hotel Operations"]
  node_tools["Hotel Tools<br/>[hotel_agent.py]"]
  node_dynamo[("DynamoDB")]
  node_seed["Demo Data Setup<br/>[db_setup.py]"]
end

subgraph group_viewer["Log Viewer"]
  node_log["Assistant Log"]
  node_viewer["Conversation Viewer<br/>[app.py]"]
end

node_guest(("Guest"))
node_bedrock["Amazon Bedrock"]

node_guest -->|"speaks to"| node_audio
node_audio -->|"queues audio"| node_stream
node_stream -->|"streams events"| node_bedrock
node_bedrock -->|"returns events"| node_stream
node_stream -.->|"dispatches tools"| node_tools
node_tools -->|"reads records"| node_dynamo
node_seed -->|"creates and seeds"| node_dynamo
node_stream -->|"queues audio output"| node_audio
node_audio -->|"plays response"| node_guest
node_log -->|"reads and parses"| node_viewer

click node_audio "https://github.com/patrikszepesi/voice-agents/blob/master/hotel_agent.py"
click node_stream "https://github.com/patrikszepesi/voice-agents/blob/master/hotel_agent.py"
click node_tools "https://github.com/patrikszepesi/voice-agents/blob/master/hotel_agent.py"
click node_seed "https://github.com/patrikszepesi/voice-agents/blob/master/db_setup.py"
click node_viewer "https://github.com/patrikszepesi/voice-agents/blob/master/app.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_audio,node_stream toneBlue
class node_tools,node_dynamo,node_seed toneAmber
class node_log,node_viewer toneMint
class node_guest,node_bedrock toneIndigo
```

## Components

### Voice Assistant

- [Audio I/O](https://github.com/patrikszepesi/voice-agents/blob/master/hotel_agent.py): `hotel_agent.py`
- [Bedrock Stream](https://github.com/patrikszepesi/voice-agents/blob/master/hotel_agent.py): `hotel_agent.py`

### Hotel Operations

- [Hotel Tools](https://github.com/patrikszepesi/voice-agents/blob/master/hotel_agent.py): `hotel_agent.py`
- **DynamoDB**
- [Demo Data Setup](https://github.com/patrikszepesi/voice-agents/blob/master/db_setup.py): `db_setup.py`

### Log Viewer

- **Assistant Log**
- [Conversation Viewer](https://github.com/patrikszepesi/voice-agents/blob/master/app.py): `app.py`

### Other components

- **Guest**
- **Amazon Bedrock**

## Connections

- Guest → Audio I/O: speaks to (evidence: `hotel_agent.py`)
- Audio I/O → Bedrock Stream: queues audio (evidence: `hotel_agent.py`)
- Bedrock Stream → Amazon Bedrock: streams events (evidence: `hotel_agent.py`)
- Amazon Bedrock → Bedrock Stream: returns events (evidence: `hotel_agent.py`)
- Bedrock Stream → Hotel Tools: dispatches tools (evidence: `hotel_agent.py`)
- Hotel Tools → DynamoDB: reads records (evidence: `hotel_agent.py`)
- Demo Data Setup → DynamoDB: creates and seeds (evidence: `db_setup.py`)
- Bedrock Stream → Audio I/O: queues audio output (evidence: `hotel_agent.py`)
- Audio I/O → Guest: plays response (evidence: `hotel_agent.py`)
- Assistant Log → Conversation Viewer: reads and parses (evidence: `app.py`)
