# vigneshwaran100/patient-appointment-agent architecture

> Architecture diagram of the GitHub repository vigneshwaran100/patient-appointment-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vigneshwaran100/patient-appointment-agent
- Repository: https://github.com/vigneshwaran100/patient-appointment-agent

## Overview

2Care AI is a stateful healthcare receptionist: patients provide multi-turn requests, the agent screens for safety, verifies identity, and routes scheduling or registration actions through deterministic tools backed by SQLite. Separate evaluation and improvement workflows benchmark conversations and database effects, diagnose failures, stage policies, and check candidate changes for regressions. Core runtime calls are visible in the excerpts or SOURCE INDEX; evaluation/improvement links follow documented workflow and indexed imports where noted.

Main entry points: [`app/graph.py`](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/graph.py) (Conversation Graph), [`app/tools/registry.py`](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/tools/registry.py) (Tool Registry), [`improvement/loop.py`](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/improvement/loop.py) (Improvement Loop), [`app/storage/database.py`](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/storage/database.py) (Clinic Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Reception Runtime"]
  node_agent["Conversation Agent<br/>[agent.py]"]
  node_graph["Conversation Graph<br/>[graph.py]"]
  node_state["Domain State<br/>[state.py]"]
  node_guardrails["Safety Screener<br/>[guardrails.py]"]
  node_prompts["Prompts &amp; Policies<br/>[prompts.py]"]
  node_llm["LLM Providers<br/>[llm.py]"]
end

subgraph group_clinic["Clinic Operations"]
  node_registry["Tool Registry<br/>[registry.py]"]
  node_patient_tool["Patient Intake<br/>[patient.py]"]
  node_availability["Availability Search<br/>[availability.py]"]
  node_booking["Booking<br/>[booking.py]"]
  node_cancellation["Cancel &amp; Reschedule<br/>[cancellation.py]"]
  node_database[("Clinic Database<br/>[database.py]")]
end

subgraph group_quality["Evaluation"]
  node_evaluator["Scenario Evaluator<br/>[evaluator.py]"]
  node_rubric["Scoring Rubric<br/>[rubric.py]"]
  node_runner["Benchmark Runner<br/>[runner.py]"]
  node_regression["Regression Comparator<br/>[regression.py]"]
end

subgraph group_learning["Policy Improvement"]
  node_analyzer["Failure Analyzer"]
  node_generator["Policy Generator"]
  node_policy_store["Versioned Policy Store<br/>[policy_store.py]"]
  node_improvement_loop["Improvement Loop<br/>[loop.py]"]
end

node_patient_actor(("Patient"))

node_patient_actor -->|"sends turns"| node_agent
node_agent -->|"processes turns"| node_graph
node_graph -->|"screens requests"| node_guardrails
node_graph -->|"updates state"| node_state
node_graph -->|"uses prompts"| node_prompts
node_graph -->|"invokes models"| node_llm
node_graph -->|"dispatches tools"| node_registry
node_llm -->|"binds tools"| node_registry
node_registry -->|"registers"| node_patient_tool
node_registry -->|"registers"| node_availability
node_registry -->|"registers"| node_booking
node_registry -->|"registers"| node_cancellation
node_patient_tool -->|"looks up patients"| node_database
node_availability -->|"queries slots"| node_database
node_booking -->|"books appointments"| node_database
node_cancellation -->|"changes appointments"| node_database
node_runner -->|"runs scenarios"| node_agent
node_runner -->|"evaluates runs"| node_evaluator
node_evaluator -->|"checks effects"| node_database
node_evaluator -->|"scores dimensions"| node_rubric
node_improvement_loop -->|"runs benchmarks"| node_runner
node_improvement_loop -->|"requests diagnoses"| node_analyzer
node_analyzer -->|"reads results"| node_rubric
node_improvement_loop -->|"creates policies"| node_generator
node_improvement_loop -->|"stages policies"| node_policy_store
node_improvement_loop -->|"compares runs"| node_regression
node_prompts -.->|"loads active policies"| node_policy_store
node_generator -->|"uses diagnoses"| node_analyzer

click node_agent "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/agent.py"
click node_graph "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/graph.py"
click node_state "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/state.py"
click node_guardrails "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/guardrails.py"
click node_prompts "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/prompts.py"
click node_llm "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/llm.py"
click node_registry "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/tools/registry.py"
click node_patient_tool "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/tools/patient.py"
click node_availability "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/tools/availability.py"
click node_booking "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/tools/booking.py"
click node_cancellation "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/tools/cancellation.py"
click node_database "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/storage/database.py"
click node_evaluator "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/eval/evaluator.py"
click node_rubric "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/eval/rubric.py"
click node_runner "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/eval/runner.py"
click node_regression "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/eval/regression.py"
click node_analyzer "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/improvement/failure_analyzer.py"
click node_generator "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/improvement/improvement_generator.py"
click node_policy_store "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/improvement/policy_store.py"
click node_improvement_loop "https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/improvement/loop.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_agent,node_graph,node_state,node_guardrails,node_prompts,node_llm toneBlue
class node_registry,node_patient_tool,node_availability,node_booking,node_cancellation,node_database toneAmber
class node_evaluator,node_rubric,node_runner,node_regression toneMint
class node_analyzer,node_generator,node_policy_store,node_improvement_loop toneRose
class node_patient_actor toneIndigo
```

## Components

### Reception Runtime

- [Conversation Agent](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/agent.py): `app/agent.py`
- [Conversation Graph](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/graph.py): `app/graph.py`
- [Domain State](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/state.py): `app/state.py`
- [Safety Screener](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/guardrails.py): `app/guardrails.py`
- [Prompts & Policies](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/prompts.py): `app/prompts.py`
- [LLM Providers](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/llm.py): `app/llm.py`

### Clinic Operations

- [Tool Registry](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/tools/registry.py): `app/tools/registry.py`
- [Patient Intake](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/tools/patient.py): `app/tools/patient.py`
- [Availability Search](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/tools/availability.py): `app/tools/availability.py`
- [Booking](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/tools/booking.py): `app/tools/booking.py`
- [Cancel & Reschedule](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/tools/cancellation.py): `app/tools/cancellation.py`
- [Clinic Database](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/app/storage/database.py): `app/storage/database.py`

### Evaluation

- [Scenario Evaluator](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/eval/evaluator.py): `eval/evaluator.py`
- [Scoring Rubric](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/eval/rubric.py): `eval/rubric.py`
- [Benchmark Runner](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/eval/runner.py): `eval/runner.py`
- [Regression Comparator](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/eval/regression.py): `eval/regression.py`

### Policy Improvement

- [Failure Analyzer](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/improvement/failure_analyzer.py): `improvement/failure_analyzer.py`
- [Policy Generator](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/improvement/improvement_generator.py): `improvement/improvement_generator.py`
- [Versioned Policy Store](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/improvement/policy_store.py): `improvement/policy_store.py`
- [Improvement Loop](https://github.com/vigneshwaran100/patient-appointment-agent/blob/main/improvement/loop.py): `improvement/loop.py`

### Other components

- **Patient**

## Connections

- Patient → Conversation Agent: sends turns (evidence: `README.md`)
- Conversation Agent → Conversation Graph: processes turns (evidence: `app/agent.py`)
- Conversation Graph → Safety Screener: screens requests (evidence: `README.md`)
- Conversation Graph → Domain State: updates state (evidence: `app/graph.py`)
- Conversation Graph → Prompts & Policies: uses prompts (evidence: `app/graph.py`)
- Conversation Graph → LLM Providers: invokes models (evidence: `app/graph.py`)
- Conversation Graph → Tool Registry: dispatches tools (evidence: `app/graph.py`)
- LLM Providers → Tool Registry: binds tools (evidence: `app/llm.py`)
- Tool Registry → Patient Intake: registers (evidence: `app/tools/registry.py`)
- Tool Registry → Availability Search: registers (evidence: `app/tools/registry.py`)
- Tool Registry → Booking: registers (evidence: `app/tools/registry.py`)
- Tool Registry → Cancel & Reschedule: registers (evidence: `app/tools/registry.py`)
- Patient Intake → Clinic Database: looks up patients (evidence: `app/tools/patient.py`)
- Availability Search → Clinic Database: queries slots (evidence: `app/tools/availability.py`)
- Booking → Clinic Database: books appointments (evidence: `app/tools/booking.py`)
- Cancel & Reschedule → Clinic Database: changes appointments (evidence: `app/tools/cancellation.py`)
- Benchmark Runner → Conversation Agent: runs scenarios (evidence: `eval/runner.py`)
- Benchmark Runner → Scenario Evaluator: evaluates runs (evidence: `eval/runner.py`)
- Scenario Evaluator → Clinic Database: checks effects (evidence: `eval/evaluator.py`)
- Scenario Evaluator → Scoring Rubric: scores dimensions (evidence: `eval/evaluator.py`)
- Improvement Loop → Benchmark Runner: runs benchmarks (evidence: `improvement/loop.py`)
- Improvement Loop → Failure Analyzer: requests diagnoses (evidence: `improvement/loop.py`)
- Failure Analyzer → Scoring Rubric: reads results (evidence: `improvement/failure_analyzer.py`)
- Improvement Loop → Policy Generator: creates policies (evidence: `improvement/loop.py`)
- Improvement Loop → Versioned Policy Store: stages policies (evidence: `improvement/loop.py`)
- Improvement Loop → Regression Comparator: compares runs (evidence: `improvement/loop.py`)
- Prompts & Policies → Versioned Policy Store: loads active policies (evidence: `README.md`)
- Policy Generator → Failure Analyzer: uses diagnoses (evidence: `improvement/improvement_generator.py`)
