# badrinath63/self-improving-appointment-agent architecture

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

- Interactive diagram: https://gitdiagram.com/badrinath63/self-improving-appointment-agent
- Repository: https://github.com/badrinath63/self-improving-appointment-agent

## Overview

This repository provides a patient-facing appointment scheduling agent and a separate evaluation/improvement loop. The main workflow is patient message → FastAPI chat endpoint → agent conversation and tool dispatch → mock clinic data for doctor search, availability, booking, or cancellation → response with tool trace. Evaluation runs predefined scenarios through the agent, scores responses and traces, applies structured policy rules, then reruns scenarios for regression checks. The graph follows documented capabilities where source was not sampled; those unsampled implementation details are not asserted as code-level links.

Main entry points: [`app/agent.py`](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/agent.py) (Agent orchestration), [`evaluation/run.py`](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/evaluation/run.py) (Evaluation runner), [`app/main.py`](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/main.py) (Chat API), [`app/tools.py`](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/tools.py) (Appointment tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Patient interaction"]
  node_chat_api["Chat API<br/>[main.py]"]
  node_chat_schemas["Chat schemas<br/>[schemas.py]"]
end

subgraph group_scheduling["Scheduling runtime"]
  node_agent["Agent orchestration<br/>[agent.py]"]
  node_openrouter{{"OpenRouter model"}}
  node_session_state[("Session state<br/>[state.py]")]
  node_appointment_tools["Appointment tools<br/>[tools.py]"]
  node_clinic_data[("Mock clinic data<br/>[database.py]")]
end

subgraph group_evaluation["Evaluation loop"]
  node_eval_scenarios["Evaluation scenarios<br/>[scenarios.py]"]
  node_eval_runner["Evaluation runner<br/>[run.py]"]
  node_scenario_evaluator["Scenario evaluator<br/>[evaluator.py]"]
  node_improvement_logic["Improvement logic<br/>[improvement.py]"]
end

subgraph group_policy["Agent policy"]
  node_system_prompt["Prompt builder<br/>[prompts.py]"]
  node_policy_rules["Policy rules<br/>[policy.json]"]
end

node_patient(("Patient"))

node_patient -->|"sends message"| node_chat_api
node_chat_api -->|"validates and formats"| node_chat_schemas
node_chat_api -->|"invokes"| node_agent
node_agent -->|"requests completion"| node_openrouter
node_agent -->|"reads and updates"| node_session_state
node_agent -->|"builds instructions"| node_system_prompt
node_system_prompt -->|"loads rules"| node_policy_rules
node_agent -->|"dispatches tool calls"| node_appointment_tools
node_appointment_tools -->|"reads and updates"| node_clinic_data
node_eval_runner -->|"runs scenarios"| node_eval_scenarios
node_eval_runner -->|"runs conversation"| node_agent
node_eval_runner -->|"resets state"| node_clinic_data
node_eval_runner -->|"scores results"| node_scenario_evaluator
node_eval_runner -->|"applies improvements"| node_improvement_logic
node_improvement_logic -->|"updates policy"| node_policy_rules

click node_chat_api "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/main.py"
click node_chat_schemas "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/schemas.py"
click node_agent "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/agent.py"
click node_session_state "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/state.py"
click node_system_prompt "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/prompts.py"
click node_policy_rules "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/improvements/policy.json"
click node_appointment_tools "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/tools.py"
click node_clinic_data "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/database.py"
click node_eval_scenarios "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/evaluation/scenarios.py"
click node_eval_runner "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/evaluation/run.py"
click node_scenario_evaluator "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/evaluation/evaluator.py"
click node_improvement_logic "https://github.com/badrinath63/self-improving-appointment-agent/blob/main/evaluation/improvement.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_api,node_chat_schemas toneBlue
class node_agent,node_openrouter,node_session_state,node_appointment_tools,node_clinic_data toneAmber
class node_eval_scenarios,node_eval_runner,node_scenario_evaluator,node_improvement_logic toneMint
class node_system_prompt,node_policy_rules toneRose
class node_patient toneIndigo
```

## Components

### Patient interaction

- [Chat API](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/main.py): `app/main.py`
- [Chat schemas](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/schemas.py): `app/schemas.py`

### Scheduling runtime

- [Agent orchestration](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/agent.py): `app/agent.py`
- **OpenRouter model**
- [Session state](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/state.py): `app/state.py`
- [Appointment tools](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/tools.py): `app/tools.py`
- [Mock clinic data](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/database.py): `app/database.py`

### Evaluation loop

- [Evaluation scenarios](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/evaluation/scenarios.py): `evaluation/scenarios.py`
- [Evaluation runner](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/evaluation/run.py): `evaluation/run.py`
- [Scenario evaluator](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/evaluation/evaluator.py): `evaluation/evaluator.py`
- [Improvement logic](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/evaluation/improvement.py): `evaluation/improvement.py`

### Agent policy

- [Prompt builder](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/app/prompts.py): `app/prompts.py`
- [Policy rules](https://github.com/badrinath63/self-improving-appointment-agent/blob/main/improvements/policy.json): `improvements/policy.json`

### Other components

- **Patient**

## Connections

- Patient → Chat API: sends message (evidence: `README.md`)
- Chat API → Chat schemas: validates and formats (evidence: `app/main.py`)
- Chat API → Agent orchestration: invokes (evidence: `app/main.py`)
- Agent orchestration → OpenRouter model: requests completion (evidence: `app/agent.py`)
- Agent orchestration → Session state: reads and updates (evidence: `app/agent.py`)
- Agent orchestration → Prompt builder: builds instructions (evidence: `app/agent.py`)
- Prompt builder → Policy rules: loads rules (evidence: `app/prompts.py`)
- Agent orchestration → Appointment tools: dispatches tool calls (evidence: `app/agent.py`)
- Appointment tools → Mock clinic data: reads and updates (evidence: `app/tools.py`)
- Evaluation runner → Evaluation scenarios: runs scenarios (evidence: `evaluation/run.py`)
- Evaluation runner → Agent orchestration: runs conversation (evidence: `evaluation/run.py`)
- Evaluation runner → Mock clinic data: resets state (evidence: `evaluation/run.py`)
- Evaluation runner → Scenario evaluator: scores results (evidence: `evaluation/run.py`)
- Evaluation runner → Improvement logic: applies improvements (evidence: `evaluation/run.py`)
- Improvement logic → Policy rules: updates policy (evidence: `evaluation/improvement.py`)
