# wellington-roveder/reservabot architecture

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

- Interactive diagram: https://gitdiagram.com/wellington-roveder/reservabot
- Repository: https://github.com/wellington-roveder/reservabot

## Overview

ReservaBot is a conversational restaurant-reservation agent. A user submits a message in the Streamlit chat; the app classifies it and blocks an out-of-scope first message, or sends it to the LLM service. The service can iteratively dispatch tools for table listing, availability, reservation creation, lookup, and cancellation; repository queries enforce business rules and persist data in SQLite. The app and service also expose and record operational traces. Arrows are limited to relationships shown in excerpts or explicitly documented in the README; unsampled implementation details are not inferred.

Main entry points: [`services/openai_service.py`](https://github.com/wellington-roveder/reservabot/blob/main/services/openai_service.py) (LLM tool agent), [`app.py`](https://github.com/wellington-roveder/reservabot/blob/main/app.py) (Streamlit chat), [`services/nlu_config/nlu.py`](https://github.com/wellington-roveder/reservabot/blob/main/services/nlu_config/nlu.py) (Semantic gatekeeper), [`repository/queries.py`](https://github.com/wellington-roveder/reservabot/blob/main/repository/queries.py) (Reservation operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat experience"]
  node_chat["Streamlit chat<br/>[app.py]"]
end

subgraph group_conversation["Conversation services"]
  node_nlu["Semantic gatekeeper<br/>[nlu.py]"]
  node_intent_examples["Intent examples<br/>[intents.json]"]
  node_llm_agent["LLM tool agent<br/>[openai_service.py]"]
  node_tool_specs["Tool definitions<br/>[tools.json]"]
end

subgraph group_reservations["Reservation domain"]
  node_reservation_queries["Reservation operations<br/>[queries.py]"]
  node_connection_pool["SQLite connection pool<br/>[database.py]"]
  node_sqlite[("SQLite reservation store")]
end

subgraph group_observability["Observability"]
  node_telemetry["Trace and cost telemetry<br/>[telemetry.py]"]
end

node_user(("Restaurant customer"))
node_llm_provider{{"OpenAI-compatible API"}}

node_user -->|"sends message"| node_chat
node_chat -->|"classifies message"| node_nlu
node_nlu -->|"loads examples"| node_intent_examples
node_chat -->|"requests response"| node_llm_agent
node_llm_agent -->|"sends completions"| node_llm_provider
node_llm_agent -->|"loads tool definitions"| node_tool_specs
node_llm_agent -->|"dispatches tools"| node_reservation_queries
node_reservation_queries -->|"uses database"| node_connection_pool
node_connection_pool -->|"reads and writes"| node_sqlite
node_chat -->|"records turn trace"| node_telemetry
node_llm_agent -->|"calculates cost"| node_telemetry

click node_chat "https://github.com/wellington-roveder/reservabot/blob/main/app.py"
click node_nlu "https://github.com/wellington-roveder/reservabot/blob/main/services/nlu_config/nlu.py"
click node_intent_examples "https://github.com/wellington-roveder/reservabot/blob/main/services/nlu_config/intents.json"
click node_llm_agent "https://github.com/wellington-roveder/reservabot/blob/main/services/openai_service.py"
click node_tool_specs "https://github.com/wellington-roveder/reservabot/blob/main/services/tools.json"
click node_reservation_queries "https://github.com/wellington-roveder/reservabot/blob/main/repository/queries.py"
click node_connection_pool "https://github.com/wellington-roveder/reservabot/blob/main/repository/database.py"
click node_telemetry "https://github.com/wellington-roveder/reservabot/blob/main/services/telemetry.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_chat toneBlue
class node_nlu,node_intent_examples,node_llm_agent,node_tool_specs toneAmber
class node_reservation_queries,node_connection_pool,node_sqlite,node_llm_provider toneMint
class node_telemetry toneRose
class node_user toneIndigo
```

## Components

### Chat experience

- [Streamlit chat](https://github.com/wellington-roveder/reservabot/blob/main/app.py): `app.py`

### Conversation services

- [Semantic gatekeeper](https://github.com/wellington-roveder/reservabot/blob/main/services/nlu_config/nlu.py): `services/nlu_config/nlu.py`
- [Intent examples](https://github.com/wellington-roveder/reservabot/blob/main/services/nlu_config/intents.json): `services/nlu_config/intents.json`
- [LLM tool agent](https://github.com/wellington-roveder/reservabot/blob/main/services/openai_service.py): `services/openai_service.py`
- [Tool definitions](https://github.com/wellington-roveder/reservabot/blob/main/services/tools.json): `services/tools.json`

### Reservation domain

- [Reservation operations](https://github.com/wellington-roveder/reservabot/blob/main/repository/queries.py): `repository/queries.py`
- [SQLite connection pool](https://github.com/wellington-roveder/reservabot/blob/main/repository/database.py): `repository/database.py`
- **SQLite reservation store**

### Observability

- [Trace and cost telemetry](https://github.com/wellington-roveder/reservabot/blob/main/services/telemetry.py): `services/telemetry.py`

### Other components

- **Restaurant customer**
- **OpenAI-compatible API**

## Connections

- Restaurant customer → Streamlit chat: sends message (evidence: `app.py`)
- Streamlit chat → Semantic gatekeeper: classifies message (evidence: `app.py`)
- Semantic gatekeeper → Intent examples: loads examples (evidence: `services/nlu_config/nlu.py`)
- Streamlit chat → LLM tool agent: requests response (evidence: `app.py`)
- LLM tool agent → OpenAI-compatible API: sends completions (evidence: `services/openai_service.py`)
- LLM tool agent → Tool definitions: loads tool definitions (evidence: `services/openai_service.py`)
- LLM tool agent → Reservation operations: dispatches tools (evidence: `services/openai_service.py`)
- Reservation operations → SQLite connection pool: uses database (evidence: `repository/queries.py`)
- SQLite connection pool → SQLite reservation store: reads and writes (evidence: `repository/database.py`)
- Streamlit chat → Trace and cost telemetry: records turn trace (evidence: `app.py`)
- LLM tool agent → Trace and cost telemetry: calculates cost (evidence: `services/openai_service.py`)
