# pik1989/dental-appointment-system-using-langgraph architecture

> Architecture diagram of the GitHub repository pik1989/dental-appointment-system-using-langgraph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pik1989/dental-appointment-system-using-langgraph
- Repository: https://github.com/pik1989/dental-appointment-system-using-langgraph

## Overview

1. **System shape**
   - This repository is a single-process, conversational appointment manager for a dental clinic.
   - The architecture is centered on a **LangGraph-driven multi-agent workflow** rather than a traditional layered app or web service.

2. **Top-level runtime path**
   - `main.py` is the interactive entry point.
   - User messages enter the system from the CLI, are passed into the workflow graph, and the graph returns the assistant’s response back to the CLI.

3. **Orchestration layer**
   - `dental_agent/workflows/graph.py` defines the LangGraph state machine and the control flow between agents.
   - The graph is the main composition boundary: it decides when to classify intent, when to invoke a specialist agent, and when to terminate a conversation turn.

4. **Supervisor pattern**
   - `dental_agent/agents/supervisor.py` is the routing brain.
   - It classifies each user message into an intent such as info, booking, cancellation, rescheduling, or end, and selects the next specialized agent.
   - This is the key architectural control point for the whole system.

5. **Specialized agent boundaries**
   - `info_agent.py`, `booking_agent.py`, `cancellation_agent.py`, and `rescheduling_agent.py` each handle one appointment-related capability.
   - The design follows a narrow-responsibility model: each agent only needs the tools and context relevant to its task.
   - This makes the diagram naturally split into a coordinator plus four functional workers.

6. **Shared conversation state**
   - `dental_agent/models/state.py` defines the structured state passed through the graph.
   - The state likely carries message history, routing decisions, collected appointment fields, and tool outputs.
   - This shared state is what lets multiple agents cooperate across turns without a separate session database.

7. **Tool and data-access layer**
   - `dental_agent/tools/csv_reader.py` and `dental_agent/tools/csv_writer.py` are the persistence boundary.
   - Read tools support querying availability and existing appointments; write tools support booking, cancelling, and rescheduling.
   - The agents do not appear to manipulate CSV data directly; they call tools, which isolates business logic from storage logic.

8. **Single data store**
   - `doctor_availability.csv` is the system’s backing store.
   - It encodes appointment slots, doctor names, specializations, availability, and patient assignments.
   - Architecturally, this means the app is effectively file-backed rather than database-backed, which is important for diagramming the persistence layer.

9. **LLM and framework dependencies**
   - The project uses **LangChain** for LLM/tool integration and **LangGraph** for workflow orchestration.
   - The README indicates **Grok-4 via xAI** is the model provider.
   - These are not just implementation details; they define how routing, structured output, and tool use are performed.

10. **Configuration boundary**
   - `dental_agent/config/settings.py` centralizes environment-driven settings such as API key, model name, and temperature.
   - This keeps deployment/runtime concerns separate from the agent logic and graph definition.

11. **Validation and data shaping**
   - The repo uses **Pydantic** for structured state and output validation, per the README.
   - This matters because the supervisor’s routing decision and the appointment data exchanged between agents need predictable structure.

12. **Cross-cutting helpers**
   - `dental_agent/utils.py` likely contains shared helper functions used across agents or tools.
   - In the architecture diagram, this sits as a small shared utility layer, not as a primary subsystem.

13. **Primary data flow**
   - Input arrives in `main.py` → enters the LangGraph workflow → supervisor classifies intent → graph routes to the chosen specialist agent → that agent invokes CSV read/write tools as needed → updated state and response return to the CLI.
   - This is the core end-to-end path to show in an architecture diagram.

14. **Main architectural constraint**
   - The system is intentionally bounded to appointment management over a CSV file, with no evidence of external APIs beyond the LLM provider.
   - So the dominant boundaries are: CLI, orchestration graph, agent layer, tool layer, and file-based persistence.

Main entry points: [`dental_agent/agents/supervisor.py`](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agents/supervisor.py) (Supervisor), [`dental_agent/tools/csv_reader.py`](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/tools/csv_reader.py) (CSV reader), [`dental_agent/tools/csv_writer.py`](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/tools/csv_writer.py) (CSV writer), [`dental_agent/workflows/graph.py`](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/workflows/graph.py) (Workflow graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_py["CLI app<br/>entrypoint<br/>[main.py]"]
end

subgraph group_orchestration["Orchestration"]
  node_agent_py["Agent facade<br/>bootstrap<br/>[agent.py]"]
  node_graph_py{{"Workflow graph<br/>langgraph state machine<br/>[graph.py]"}}
end

subgraph group_agents["Agents"]
  node_supervisor_py["Supervisor<br/>router<br/>[supervisor.py]"]
  node_info_agent_py["Info agent<br/>specialist agent<br/>[info_agent.py]"]
  node_booking_agent_py["Booking agent<br/>specialist agent<br/>[booking_agent.py]"]
  node_cancellation_agent_py["Cancel agent<br/>specialist agent"]
  node_rescheduling_agent_py["Reschedule agent<br/>specialist agent"]
end

subgraph group_shared["Shared"]
  node_state_py["Conversation state<br/>pydantic state<br/>[state.py]"]
  node_settings_py["Settings<br/>config<br/>[settings.py]"]
  node_utils_py["Utils<br/>helpers<br/>[utils.py]"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_requirements["Dependencies<br/>package manifest<br/>[requirements.txt]"]
end

subgraph group_storage["Storage"]
  node_csv_reader_py["CSV reader<br/>read tool<br/>[csv_reader.py]"]
  node_csv_writer_py["CSV writer<br/>write tool<br/>[csv_writer.py]"]
  node_doctor_csv[("Availability data<br/>csv datastore")]
end

node_main_py -->|"starts"| node_agent_py
node_agent_py -->|"builds"| node_graph_py
node_graph_py -->|"routes via"| node_supervisor_py
node_supervisor_py -->|"info"| node_info_agent_py
node_supervisor_py -->|"booking"| node_booking_agent_py
node_supervisor_py -->|"cancel"| node_cancellation_agent_py
node_supervisor_py -->|"reschedule"| node_rescheduling_agent_py
node_graph_py -->|"shares state"| node_state_py
node_info_agent_py -->|"reads"| node_csv_reader_py
node_booking_agent_py -->|"checks"| node_csv_reader_py
node_booking_agent_py -->|"books"| node_csv_writer_py
node_cancellation_agent_py -->|"looks up"| node_csv_reader_py
node_cancellation_agent_py -->|"removes"| node_csv_writer_py
node_rescheduling_agent_py -->|"reads"| node_csv_reader_py
node_rescheduling_agent_py -->|"updates"| node_csv_writer_py
node_csv_reader_py -->|"loads from"| node_doctor_csv
node_csv_writer_py -->|"writes to"| node_doctor_csv
node_settings_py -->|"configures"| node_graph_py
node_settings_py -->|"configures"| node_supervisor_py
node_utils_py -.->|"supports"| node_supervisor_py
node_utils_py -.->|"supports"| node_csv_reader_py
node_utils_py -.->|"supports"| node_csv_writer_py
node_readme -.->|"documents"| node_requirements

click node_main_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/main.py"
click node_agent_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agent.py"
click node_graph_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/workflows/graph.py"
click node_supervisor_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agents/supervisor.py"
click node_info_agent_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agents/info_agent.py"
click node_booking_agent_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agents/booking_agent.py"
click node_cancellation_agent_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agents/cancellation_agent.py"
click node_rescheduling_agent_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agents/rescheduling_agent.py"
click node_state_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/models/state.py"
click node_settings_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/config/settings.py"
click node_utils_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/utils.py"
click node_csv_reader_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/tools/csv_reader.py"
click node_csv_writer_py "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/tools/csv_writer.py"
click node_doctor_csv "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/doctor_availability.csv"
click node_readme "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/README.md"
click node_requirements "https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/requirements.txt"

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_main_py toneBlue
class node_agent_py,node_graph_py toneAmber
class node_supervisor_py,node_info_agent_py,node_booking_agent_py,node_cancellation_agent_py,node_rescheduling_agent_py toneMint
class node_state_py,node_settings_py,node_utils_py,node_readme,node_requirements toneRose
class node_csv_reader_py,node_csv_writer_py,node_doctor_csv toneIndigo
```

## Components

### Runtime

Interactive CLI entrypoint and conversation loop

- [CLI app](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/main.py): entrypoint · Interactive command-line entry into the conversation loop · `main.py`

### Orchestration

LangGraph workflow and routing control

- [Agent facade](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agent.py): bootstrap · High-level package entry that wires the agent system together · `dental_agent/agent.py`
- [Workflow graph](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/workflows/graph.py): langgraph state machine · Defines turn flow, routing, and termination for each conversation turn · `dental_agent/workflows/graph.py`

### Agents

Supervisor and specialist conversation handlers

- [Supervisor](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agents/supervisor.py): router · Classifies intent and selects the next specialist agent · `dental_agent/agents/supervisor.py`
- [Info agent](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agents/info_agent.py): specialist agent · Handles clinic and appointment information requests · `dental_agent/agents/info_agent.py`
- [Booking agent](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agents/booking_agent.py): specialist agent · Handles new appointment booking flows · `dental_agent/agents/booking_agent.py`
- [Cancel agent](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agents/cancellation_agent.py): specialist agent · Handles appointment cancellation flows · `dental_agent/agents/cancellation_agent.py`
- [Reschedule agent](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/agents/rescheduling_agent.py): specialist agent · Handles appointment change flows · `dental_agent/agents/rescheduling_agent.py`

### Shared

Common state, settings, and helpers

- [Conversation state](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/models/state.py): pydantic state · Structured shared state passed across graph nodes and turns · `dental_agent/models/state.py`
- [Settings](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/config/settings.py): config · Environment-driven runtime and model configuration · `dental_agent/config/settings.py`
- [Utils](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/utils.py): helpers · Shared helper functions used across the system · `dental_agent/utils.py`
- [README](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/README.md): docs · Project overview and usage notes · `README.md`
- [Dependencies](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/requirements.txt): package manifest · Python dependency list including LangChain and LangGraph · `requirements.txt`

### Storage

CSV-backed appointment data

- [CSV reader](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/tools/csv_reader.py): read tool · Reads availability and appointment data from the CSV store · `dental_agent/tools/csv_reader.py`
- [CSV writer](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/dental_agent/tools/csv_writer.py): write tool · Persists booking, cancellation, and rescheduling updates · `dental_agent/tools/csv_writer.py`
- [Availability data](https://github.com/pik1989/dental-appointment-system-using-langgraph/blob/main/doctor_availability.csv): csv datastore · File-backed source of appointments, doctors, and availability · `doctor_availability.csv`

## Connections

- CLI app → Agent facade: starts · CLI hands user input to the agent runtime
- Agent facade → Workflow graph: builds · Entry layer constructs or invokes the workflow graph
- Workflow graph → Supervisor: routes via · Graph delegates intent selection to the supervisor
- Supervisor → Info agent: info · Routes informational queries to the info specialist
- Supervisor → Booking agent: booking · Routes booking requests to the booking specialist
- Supervisor → Cancel agent: cancel · Routes cancellation requests to the cancellation specialist
- Supervisor → Reschedule agent: reschedule · Routes rescheduling requests to the rescheduling specialist
- Workflow graph → Conversation state: shares state · Graph passes structured conversation state between nodes
- Info agent → CSV reader: reads · Info flows query stored availability and appointments
- Booking agent → CSV reader: checks · Booking logic checks availability before writing
- Booking agent → CSV writer: books · Booking logic writes new appointments to storage
- Cancel agent → CSV reader: looks up · Cancellation logic finds existing appointments
- Cancel agent → CSV writer: removes · Cancellation logic updates the CSV store
- Reschedule agent → CSV reader: reads · Rescheduling logic checks current slots and appointments
- Reschedule agent → CSV writer: updates · Rescheduling logic persists changed appointment details
- CSV reader → Availability data: loads from · Reader accesses the file-backed appointment store
- CSV writer → Availability data: writes to · Writer persists changes into the CSV datastore
- Settings → Workflow graph: configures · Runtime settings influence model and workflow behavior
- Settings → Supervisor: configures · Routing behavior depends on configured model settings
- Utils → Supervisor: supports · Shared helpers support routing and message handling
- Utils → CSV reader: supports · Utilities assist common data handling
- Utils → CSV writer: supports · Utilities assist common data handling
- README → Dependencies: documents · Documentation describes the dependency set and runtime stack
