# aksh0411/ai_receptionist architecture

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

- Interactive diagram: https://gitdiagram.com/aksh0411/ai_receptionist
- Repository: https://github.com/aksh0411/ai_receptionist

## Overview

FrontDesk AI is a dental-clinic receptionist backend. A customer chats through the web page or POST /chat; the agent builds a prompt from clinic data, asks an OpenAI-compatible model for a reply or tool calls, and the executor runs those calls. Booking is confirmed only when the booking tool saves it and returns a reference. The JSON file is the system of record for clinic data, appointments, conversations, and tool-call logs. The README documents capabilities beyond the sampled excerpts; those are represented where the tool registry and README support them.

Main entry points: [`app/db/json_store.py`](https://github.com/aksh0411/ai_receptionist/blob/main/app/db/json_store.py) (JSON clinic store), [`app/agent/executor.py`](https://github.com/aksh0411/ai_receptionist/blob/main/app/agent/executor.py) (Tool executor), [`app/agent/controller.py`](https://github.com/aksh0411/ai_receptionist/blob/main/app/agent/controller.py) (Agent loop), [`app/channels/chat.py`](https://github.com/aksh0411/ai_receptionist/blob/main/app/channels/chat.py) (Chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Chat entry"]
  node_web["Chat page<br/>[chat.html]"]
  node_api["Chat API<br/>[chat.py]"]
  node_app["App startup<br/>[main.py]"]
end

subgraph group_agent["Reception agent"]
  node_controller["Agent loop<br/>[controller.py]"]
  node_prompt["Prompt builder<br/>[prompts.py]"]
  node_specs["Tool schemas<br/>[tool_specs.py]"]
  node_executor["Tool executor<br/>[executor.py]"]
  node_config["LLM settings<br/>[config.py]"]
end

subgraph group_clinic["Clinic operations"]
  node_availability["Availability checks<br/>[booking.py]"]
  node_booking["Book appointment<br/>[booking.py]"]
  node_changes["Cancel and reschedule<br/>[booking.py]"]
  node_customer_lookup["Customer lookup<br/>[booking.py]"]
  node_clinic_info["Clinic information<br/>[booking.py]"]
  node_escalation["Human escalation<br/>[booking.py]"]
end

subgraph group_state["Clinic state"]
  node_store[("JSON clinic store<br/>[json_store.py]")]
end

node_customer(("Customer"))
node_model{{"LLM provider"}}

node_customer -.->|"chats through"| node_web
node_customer -->|"sends message"| node_api
node_web -.->|"submits chat"| node_api
node_app -->|"mounts route"| node_api
node_app -->|"initializes"| node_store
node_api -->|"creates and calls"| node_controller
node_controller -->|"builds prompt"| node_prompt
node_controller -->|"provides tools"| node_specs
node_controller -->|"reads settings"| node_config
node_controller -->|"loads and saves chat"| node_store
node_prompt -->|"reads clinic data"| node_store
node_controller -->|"sends prompt and tools"| node_model
node_model -->|"returns reply or calls"| node_controller
node_controller -->|"dispatches tool calls"| node_executor
node_executor -->|"dispatches availability"| node_availability
node_executor -->|"dispatches booking"| node_booking
node_executor -->|"dispatches changes"| node_changes
node_executor -->|"dispatches lookup"| node_customer_lookup
node_executor -->|"dispatches information"| node_clinic_info
node_executor -->|"dispatches escalation"| node_escalation
node_executor -->|"logs tool attempts"| node_store
node_availability -->|"reads clinic and bookings"| node_store
node_booking -->|"saves customer and booking"| node_store
node_changes -->|"reads and updates bookings"| node_store
node_customer_lookup -->|"reads customer records"| node_store
node_clinic_info -->|"reads clinic details"| node_store
node_escalation -.->|"records escalation"| node_store

click node_web "https://github.com/aksh0411/ai_receptionist/blob/main/app/static/chat.html"
click node_api "https://github.com/aksh0411/ai_receptionist/blob/main/app/channels/chat.py"
click node_app "https://github.com/aksh0411/ai_receptionist/blob/main/app/main.py"
click node_controller "https://github.com/aksh0411/ai_receptionist/blob/main/app/agent/controller.py"
click node_prompt "https://github.com/aksh0411/ai_receptionist/blob/main/app/agent/prompts.py"
click node_specs "https://github.com/aksh0411/ai_receptionist/blob/main/app/agent/tool_specs.py"
click node_executor "https://github.com/aksh0411/ai_receptionist/blob/main/app/agent/executor.py"
click node_availability "https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py"
click node_booking "https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py"
click node_changes "https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py"
click node_customer_lookup "https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py"
click node_clinic_info "https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py"
click node_escalation "https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py"
click node_config "https://github.com/aksh0411/ai_receptionist/blob/main/app/config.py"
click node_store "https://github.com/aksh0411/ai_receptionist/blob/main/app/db/json_store.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_web,node_api,node_app toneBlue
class node_controller,node_prompt,node_specs,node_executor,node_config toneAmber
class node_availability,node_booking,node_changes,node_customer_lookup,node_clinic_info,node_escalation toneMint
class node_store toneRose
class node_customer,node_model toneIndigo
```

## Components

### Chat entry

- [Chat page](https://github.com/aksh0411/ai_receptionist/blob/main/app/static/chat.html): `app/static/chat.html`
- [Chat API](https://github.com/aksh0411/ai_receptionist/blob/main/app/channels/chat.py): `app/channels/chat.py`
- [App startup](https://github.com/aksh0411/ai_receptionist/blob/main/app/main.py): `app/main.py`

### Reception agent

- [Agent loop](https://github.com/aksh0411/ai_receptionist/blob/main/app/agent/controller.py): `app/agent/controller.py`
- [Prompt builder](https://github.com/aksh0411/ai_receptionist/blob/main/app/agent/prompts.py): `app/agent/prompts.py`
- [Tool schemas](https://github.com/aksh0411/ai_receptionist/blob/main/app/agent/tool_specs.py): `app/agent/tool_specs.py`
- [Tool executor](https://github.com/aksh0411/ai_receptionist/blob/main/app/agent/executor.py): `app/agent/executor.py`
- [LLM settings](https://github.com/aksh0411/ai_receptionist/blob/main/app/config.py): `app/config.py`

### Clinic operations

- [Availability checks](https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py): `app/tools/booking.py`
- [Book appointment](https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py): `app/tools/booking.py`
- [Cancel and reschedule](https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py): `app/tools/booking.py`
- [Customer lookup](https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py): `app/tools/booking.py`
- [Clinic information](https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py): `app/tools/booking.py`
- [Human escalation](https://github.com/aksh0411/ai_receptionist/blob/main/app/tools/booking.py): `app/tools/booking.py`

### Clinic state

- [JSON clinic store](https://github.com/aksh0411/ai_receptionist/blob/main/app/db/json_store.py): `app/db/json_store.py`

### Other components

- **Customer**
- **LLM provider**

## Connections

- Customer → Chat page: chats through (evidence: `README.md`)
- Customer → Chat API: sends message (evidence: `README.md`)
- Chat page → Chat API: submits chat (evidence: `README.md`)
- App startup → Chat API: mounts route (evidence: `app/main.py`)
- App startup → JSON clinic store: initializes (evidence: `app/main.py`)
- Chat API → Agent loop: creates and calls (evidence: `app/channels/chat.py`)
- Agent loop → Prompt builder: builds prompt (evidence: `app/agent/controller.py`)
- Agent loop → Tool schemas: provides tools (evidence: `app/agent/controller.py`)
- Agent loop → LLM settings: reads settings (evidence: `app/agent/controller.py`)
- Agent loop → JSON clinic store: loads and saves chat (evidence: `app/agent/controller.py`)
- Prompt builder → JSON clinic store: reads clinic data (evidence: `app/agent/prompts.py`)
- Agent loop → LLM provider: sends prompt and tools (evidence: `app/agent/controller.py`)
- LLM provider → Agent loop: returns reply or calls (evidence: `app/agent/controller.py`)
- Agent loop → Tool executor: dispatches tool calls (evidence: `app/agent/controller.py`)
- Tool executor → Availability checks: dispatches availability (evidence: `app/agent/executor.py`)
- Tool executor → Book appointment: dispatches booking (evidence: `app/agent/executor.py`)
- Tool executor → Cancel and reschedule: dispatches changes (evidence: `app/agent/executor.py`)
- Tool executor → Customer lookup: dispatches lookup (evidence: `app/agent/executor.py`)
- Tool executor → Clinic information: dispatches information (evidence: `app/agent/executor.py`)
- Tool executor → Human escalation: dispatches escalation (evidence: `app/agent/executor.py`)
- Tool executor → JSON clinic store: logs tool attempts (evidence: `app/agent/executor.py`)
- Availability checks → JSON clinic store: reads clinic and bookings (evidence: `app/tools/booking.py`)
- Book appointment → JSON clinic store: saves customer and booking (evidence: `app/tools/booking.py`)
- Cancel and reschedule → JSON clinic store: reads and updates bookings (evidence: `app/tools/booking.py`)
- Customer lookup → JSON clinic store: reads customer records (evidence: `app/tools/booking.py`)
- Clinic information → JSON clinic store: reads clinic details (evidence: `app/tools/booking.py`)
- Human escalation → JSON clinic store: records escalation (evidence: `app/tools/booking.py`)