# culyrh/agentic-kiosk architecture

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

- Interactive diagram: https://gitdiagram.com/culyrh/agentic-kiosk
- Repository: https://github.com/culyrh/agentic-kiosk

## Overview

This is a FastAPI voice-ordering kiosk backend: a customer streams speech, the server detects an utterance, transcribes it, and lets a LangChain agent choose menu and cart tools before returning streamed speech and kiosk actions. The product also exposes REST menu, cart, order, option, set, and semantic-search APIs. Its key internal layers are session-aware tools, hybrid menu retrieval, and SQLite persistence. Edges reflect the README or shown calls/import references; several detailed capabilities are documented but their implementation was not sampled.

Main entry points: [`api/main.py`](https://github.com/culyrh/agentic-kiosk/blob/main/api/main.py) (FastAPI app), [`db/sqlite.py`](https://github.com/culyrh/agentic-kiosk/blob/main/db/sqlite.py) (SQLite access), [`api/routes/stt.py`](https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/stt.py) (Voice WebSocket), [`app/agent.py`](https://github.com/culyrh/agentic-kiosk/blob/main/app/agent.py) (ReAct agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice interaction"]
  node_voice_ws["Voice WebSocket<br/>[stt.py]"]
  node_vad["Speech detection<br/>[vad_silero.py]"]
  node_stt["Speech recognition<br/>[stt.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
end

subgraph group_agent["Agent and retrieval"]
  node_agent_core["ReAct agent<br/>[agent.py]"]
  node_session["Session context<br/>[session_context.py]"]
  node_latency["Latency tracking<br/>[latency_tracker.py]"]
  node_menu_tools["Menu tools<br/>[menu_tools.py]"]
  node_cart_tools["Cart and payment tools<br/>[cart_tools.py]"]
  node_vector_search["Semantic retrieval<br/>[search.py]"]
end

subgraph group_ordering["Ordering API"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_menu_api["Menu API<br/>[menu.py]"]
  node_cart_api["Cart API<br/>[cart.py]"]
  node_order_api["Order API<br/>[order.py]"]
  node_search_api["Search API<br/>[search.py]"]
  node_options_api["Options API<br/>[options.py]"]
  node_sets_api["Sets API<br/>[sets.py]"]
end

subgraph group_data["Data and persistence"]
  node_chroma[("Vector index<br/>[chroma.py]")]
  node_sqlite_layer["SQLite access<br/>[sqlite.py]"]
  node_sqlite_store[("Menu and orders DB<br/>[ria_menu.db]")]
end

node_customer(("Kiosk customer"))

node_customer -.->|"sends requests"| node_fastapi
node_fastapi -->|"routes to"| node_voice_ws
node_fastapi -->|"routes to"| node_menu_api
node_fastapi -->|"routes to"| node_cart_api
node_fastapi -->|"routes to"| node_order_api
node_fastapi -->|"routes to"| node_search_api
node_fastapi -->|"routes to"| node_options_api
node_fastapi -->|"routes to"| node_sets_api
node_voice_ws -->|"detects speech"| node_vad
node_voice_ws -->|"transcribes utterance"| node_stt
node_voice_ws -->|"handles transcript"| node_agent_core
node_voice_ws -->|"synthesizes response"| node_tts
node_agent_core -->|"dispatches tools"| node_menu_tools
node_agent_core -->|"dispatches tools"| node_cart_tools
node_agent_core -->|"tracks conversation"| node_session
node_agent_core -->|"records timings"| node_latency
node_menu_tools -->|"searches vectors"| node_chroma
node_menu_tools -->|"queries menu data"| node_sqlite_store
node_cart_tools -->|"reads session ID"| node_session
node_cart_tools -->|"updates cart and orders"| node_sqlite_store
node_search_api -->|"calls search"| node_vector_search
node_vector_search -->|"runs similarity search"| node_chroma
node_menu_api -->|"queries menus"| node_sqlite_layer
node_cart_api -->|"reads and updates cart"| node_sqlite_layer
node_order_api -->|"queries orders"| node_sqlite_layer
node_options_api -->|"queries options"| node_sqlite_layer
node_sets_api -->|"queries sets"| node_sqlite_layer
node_sqlite_layer -->|"reads and writes"| node_sqlite_store

click node_fastapi "https://github.com/culyrh/agentic-kiosk/blob/main/api/main.py"
click node_voice_ws "https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/stt.py"
click node_vad "https://github.com/culyrh/agentic-kiosk/blob/main/voice/vad_silero.py"
click node_stt "https://github.com/culyrh/agentic-kiosk/blob/main/voice/stt.py"
click node_tts "https://github.com/culyrh/agentic-kiosk/blob/main/voice/tts.py"
click node_agent_core "https://github.com/culyrh/agentic-kiosk/blob/main/app/agent.py"
click node_session "https://github.com/culyrh/agentic-kiosk/blob/main/app/session_context.py"
click node_latency "https://github.com/culyrh/agentic-kiosk/blob/main/app/latency_tracker.py"
click node_menu_tools "https://github.com/culyrh/agentic-kiosk/blob/main/app/tools/menu_tools.py"
click node_cart_tools "https://github.com/culyrh/agentic-kiosk/blob/main/app/tools/cart_tools.py"
click node_vector_search "https://github.com/culyrh/agentic-kiosk/blob/main/app/rag/search.py"
click node_chroma "https://github.com/culyrh/agentic-kiosk/blob/main/app/rag/chroma.py"
click node_menu_api "https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/menu.py"
click node_cart_api "https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/cart.py"
click node_order_api "https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/order.py"
click node_search_api "https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/search.py"
click node_options_api "https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/options.py"
click node_sets_api "https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/sets.py"
click node_sqlite_layer "https://github.com/culyrh/agentic-kiosk/blob/main/db/sqlite.py"
click node_sqlite_store "https://github.com/culyrh/agentic-kiosk/blob/main/data/ria_menu.db"

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_ws,node_vad,node_stt,node_tts toneBlue
class node_agent_core,node_session,node_latency,node_menu_tools,node_cart_tools,node_vector_search toneAmber
class node_fastapi,node_menu_api,node_cart_api,node_order_api,node_search_api,node_options_api,node_sets_api toneMint
class node_chroma,node_sqlite_layer,node_sqlite_store toneRose
class node_customer toneIndigo
```

## Components

### Voice interaction

- [Voice WebSocket](https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/stt.py): `api/routes/stt.py`
- [Speech detection](https://github.com/culyrh/agentic-kiosk/blob/main/voice/vad_silero.py): `voice/vad_silero.py`
- [Speech recognition](https://github.com/culyrh/agentic-kiosk/blob/main/voice/stt.py): `voice/stt.py`
- [Speech synthesis](https://github.com/culyrh/agentic-kiosk/blob/main/voice/tts.py): `voice/tts.py`

### Agent and retrieval

- [ReAct agent](https://github.com/culyrh/agentic-kiosk/blob/main/app/agent.py): `app/agent.py`
- [Session context](https://github.com/culyrh/agentic-kiosk/blob/main/app/session_context.py): `app/session_context.py`
- [Latency tracking](https://github.com/culyrh/agentic-kiosk/blob/main/app/latency_tracker.py): `app/latency_tracker.py`
- [Menu tools](https://github.com/culyrh/agentic-kiosk/blob/main/app/tools/menu_tools.py): `app/tools/menu_tools.py`
- [Cart and payment tools](https://github.com/culyrh/agentic-kiosk/blob/main/app/tools/cart_tools.py): `app/tools/cart_tools.py`
- [Semantic retrieval](https://github.com/culyrh/agentic-kiosk/blob/main/app/rag/search.py): `app/rag/search.py`

### Ordering API

- [FastAPI app](https://github.com/culyrh/agentic-kiosk/blob/main/api/main.py): `api/main.py`
- [Menu API](https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/menu.py): `api/routes/menu.py`
- [Cart API](https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/cart.py): `api/routes/cart.py`
- [Order API](https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/order.py): `api/routes/order.py`
- [Search API](https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/search.py): `api/routes/search.py`
- [Options API](https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/options.py): `api/routes/options.py`
- [Sets API](https://github.com/culyrh/agentic-kiosk/blob/main/api/routes/sets.py): `api/routes/sets.py`

### Data and persistence

- [Vector index](https://github.com/culyrh/agentic-kiosk/blob/main/app/rag/chroma.py): `app/rag/chroma.py`
- [SQLite access](https://github.com/culyrh/agentic-kiosk/blob/main/db/sqlite.py): `db/sqlite.py`
- [Menu and orders DB](https://github.com/culyrh/agentic-kiosk/blob/main/data/ria_menu.db): `data/ria_menu.db`

### Other components

- **Kiosk customer**

## Connections

- Kiosk customer → FastAPI app: sends requests (evidence: `README.md`)
- FastAPI app → Voice WebSocket: routes to (evidence: `api/main.py`)
- FastAPI app → Menu API: routes to (evidence: `api/main.py`)
- FastAPI app → Cart API: routes to (evidence: `api/main.py`)
- FastAPI app → Order API: routes to (evidence: `api/main.py`)
- FastAPI app → Search API: routes to (evidence: `api/main.py`)
- FastAPI app → Options API: routes to (evidence: `api/main.py`)
- FastAPI app → Sets API: routes to (evidence: `api/main.py`)
- Voice WebSocket → Speech detection: detects speech (evidence: `api/routes/stt.py`)
- Voice WebSocket → Speech recognition: transcribes utterance (evidence: `api/routes/stt.py`)
- Voice WebSocket → ReAct agent: handles transcript (evidence: `api/routes/stt.py`)
- Voice WebSocket → Speech synthesis: synthesizes response (evidence: `api/routes/stt.py`)
- ReAct agent → Menu tools: dispatches tools (evidence: `app/agent.py`)
- ReAct agent → Cart and payment tools: dispatches tools (evidence: `app/agent.py`)
- ReAct agent → Session context: tracks conversation (evidence: `app/agent.py`)
- ReAct agent → Latency tracking: records timings (evidence: `app/agent.py`)
- Menu tools → Vector index: searches vectors (evidence: `app/tools/menu_tools.py`)
- Menu tools → Menu and orders DB: queries menu data (evidence: `app/tools/menu_tools.py`)
- Cart and payment tools → Session context: reads session ID (evidence: `app/tools/cart_tools.py`)
- Cart and payment tools → Menu and orders DB: updates cart and orders (evidence: `app/tools/cart_tools.py`)
- Search API → Semantic retrieval: calls search (evidence: `api/routes/search.py`)
- Semantic retrieval → Vector index: runs similarity search (evidence: `app/rag/search.py`)
- Menu API → SQLite access: queries menus (evidence: `api/routes/menu.py`)
- Cart API → SQLite access: reads and updates cart (evidence: `api/routes/cart.py`)
- Order API → SQLite access: queries orders (evidence: `api/routes/order.py`)
- Options API → SQLite access: queries options (evidence: `api/routes/options.py`)
- Sets API → SQLite access: queries sets (evidence: `api/routes/sets.py`)
- SQLite access → Menu and orders DB: reads and writes (evidence: `db/sqlite.py`)
