How pik1989/dental-appointment-system-using-langgraph works
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: supervisor.py Supervisor · csv_reader.py CSV reader · csv_writer.py CSV writer · graph.py Workflow graph
Components 16
Runtime
Interactive CLI entrypoint and conversation loop
- CLI app · Interactive command-line entry into the conversation loop
main.py
Orchestration
LangGraph workflow and routing control
- Agent facade · High-level package entry that wires the agent system together
dental_agent/agent.py - Workflow graph · Defines turn flow, routing, and termination for each conversation turn
dental_agent/workflows/graph.py
Agents
Supervisor and specialist conversation handlers
- Supervisor · Classifies intent and selects the next specialist agent
dental_agent/agents/supervisor.py - Info agent · Handles clinic and appointment information requests
dental_agent/agents/info_agent.py - Booking agent · Handles new appointment booking flows
dental_agent/agents/booking_agent.py - Cancel agent · Handles appointment cancellation flows
dental_agent/agents/cancellation_agent.py - Reschedule agent · Handles appointment change flows
dental_agent/agents/rescheduling_agent.py
Shared
Common state, settings, and helpers
- Conversation state · Structured shared state passed across graph nodes and turns
dental_agent/models/state.py - Settings · Environment-driven runtime and model configuration
dental_agent/config/settings.py - Utils · Shared helper functions used across the system
dental_agent/utils.py - README · Project overview and usage notes
README.md - Dependencies · Python dependency list including LangChain and LangGraph
requirements.txt
Storage
CSV-backed appointment data
- CSV reader · Reads availability and appointment data from the CSV store
dental_agent/tools/csv_reader.py - CSV writer · Persists booking, cancellation, and rescheduling updates
dental_agent/tools/csv_writer.py - Availability data · File-backed source of appointments, doctors, and availability
doctor_availability.csv
Connections 23
- 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