# abhishek-3191/patient-scheduling-assistant architecture

> Architecture diagram of the GitHub repository abhishek-3191/patient-scheduling-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhishek-3191/patient-scheduling-assistant
- Repository: https://github.com/abhishek-3191/patient-scheduling-assistant

## Overview

The product is a conversational patient appointment scheduler. A patient sends multi-turn requests through the chat UI; the chat API loads patient and session context, invokes the Gemini-backed agent, persists the updated conversation, and returns structured doctor, slot, and appointment results. The agent dispatches discovery, availability, booking, cancellation, and rescheduling tools. MongoDB repositories provide patient, doctor, appointment, and conversation data. The repository also includes scenario evaluation and a baseline-versus-improved guardrail loop. Tool internals beyond the sampled booking implementation are represented only where the source index documents their dependencies.

Main entry points: [`agent/agent.ts`](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/agent.ts) (Agent orchestrator), [`components/Chat.tsx`](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/components/Chat.tsx) (Chat interface), [`app/api/chat/route.ts`](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/app/api/chat/route.ts) (Chat API), [`evaluation/evaluator.ts`](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/evaluation/evaluator.ts) (Scenario evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Patient experience"]
  node_chat["Chat interface<br/>[Chat.tsx]"]
  node_chatapi["Chat API<br/>[route.ts]"]
  node_messageview["Message view<br/>[Message.tsx]"]
  node_doctorcard["Doctor cards<br/>[DoctorCard.tsx]"]
  node_slotselector["Slot selector<br/>[SlotSelector.tsx]"]
  node_appointmentcard["Appointment card"]
end

subgraph group_assistant["Scheduling assistant"]
  node_agent["Agent orchestrator<br/>[agent.ts]"]
  node_prompt["System prompt<br/>[prompt.ts]"]
  node_state["Appointment state<br/>[state.ts]"]
  node_guardrails["Booking guardrails<br/>[guardrails.ts]"]
  node_finddoctors["Doctor discovery<br/>[findDoctors.ts]"]
  node_availability["Slot availability"]
  node_booking["Book appointment<br/>[bookAppointment.ts]"]
  node_cancellation["Cancel appointment"]
  node_rescheduling["Reschedule appointment"]
end

subgraph group_persistence["MongoDB persistence"]
  node_mongodb[("MongoDB connection<br/>[mongodb.ts]")]
  node_patientrepo["Patient repository"]
  node_doctorrepo["Doctor repository"]
  node_appointmentrepo["Appointment repository"]
  node_conversationrepo["Conversation repository"]
  node_appointmentmodel["Appointment model<br/>[Appointment.ts]"]
  node_doctormodel["Doctor model<br/>[Doctor.ts]"]
  node_patientmodel["Patient model<br/>[Patient.ts]"]
  node_conversationmodel["Conversation model<br/>[Conversation.ts]"]
end

subgraph group_evaluation["Agent evaluation"]
  node_evalapi["Evaluation API<br/>[route.ts]"]
  node_evaluator["Scenario evaluator<br/>[evaluator.ts]"]
  node_scenarios["Evaluation scenarios<br/>[scenarios.ts]"]
  node_metrics["Evaluation metrics<br/>[metrics.ts]"]
  node_evalrunner["Evaluation runner<br/>[run.ts]"]
  node_improvement["Improvement loop<br/>[selfImprovement.ts]"]
end

node_patient(("Patient"))
node_gemini{{"Gemini API"}}

node_patient -->|"sends requests"| node_chat
node_chat -->|"posts messages"| node_chatapi
node_chatapi -->|"runs agent"| node_agent
node_chatapi -->|"looks up patient"| node_patientrepo
node_chatapi -->|"loads and saves session"| node_conversationrepo
node_chatapi -->|"connects"| node_mongodb
node_chatapi -->|"returns structured results"| node_chat
node_chat -->|"renders"| node_messageview
node_chat -->|"renders"| node_doctorcard
node_chat -->|"renders"| node_slotselector
node_chat -->|"renders"| node_appointmentcard
node_appointmentcard -->|"offers appointment PDF"| node_patient
node_agent -->|"generates responses"| node_gemini
node_agent -->|"builds instructions"| node_prompt
node_agent -->|"dispatches discovery"| node_finddoctors
node_agent -->|"dispatches availability"| node_availability
node_agent -->|"dispatches booking"| node_booking
node_agent -->|"dispatches cancellation"| node_cancellation
node_agent -->|"dispatches rescheduling"| node_rescheduling
node_agent -->|"updates state"| node_state
node_booking -->|"validates booking"| node_guardrails
node_booking -->|"gets doctor"| node_doctorrepo
node_booking -->|"gets patient"| node_patientrepo
node_booking -->|"checks and creates booking"| node_appointmentrepo
node_finddoctors -->|"searches doctors"| node_doctorrepo
node_availability -->|"gets doctor schedule"| node_doctorrepo
node_availability -->|"checks booked slots"| node_appointmentrepo
node_cancellation -->|"cancels booking"| node_appointmentrepo
node_rescheduling -->|"updates booking"| node_appointmentrepo
node_rescheduling -->|"checks doctor"| node_doctorrepo
node_patientrepo -->|"queries"| node_patientmodel
node_doctorrepo -->|"queries"| node_doctormodel
node_appointmentrepo -->|"reads and writes"| node_appointmentmodel
node_conversationrepo -->|"reads and writes"| node_conversationmodel
node_evalapi -->|"connects"| node_mongodb
node_evalapi -->|"loads evaluation patient"| node_patientrepo
node_evalapi -->|"runs scenarios"| node_evaluator
node_evalapi -->|"calculates results"| node_metrics
node_evalrunner -->|"connects"| node_mongodb
node_evalrunner -->|"runs scenarios"| node_evaluator
node_evalrunner -->|"summarizes results"| node_metrics
node_evaluator -->|"evaluates behavior"| node_agent
node_evaluator -->|"loads scenarios"| node_scenarios
node_evaluator -->|"produces scenario results"| node_metrics
node_improvement -->|"compares runs"| node_evaluator
node_improvement -->|"compares pass rates"| node_metrics

click node_chat "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/components/Chat.tsx"
click node_chatapi "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/app/api/chat/route.ts"
click node_messageview "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/components/Message.tsx"
click node_doctorcard "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/components/DoctorCard.tsx"
click node_slotselector "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/components/SlotSelector.tsx"
click node_appointmentcard "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/components/AppointmentCard.tsx"
click node_agent "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/agent.ts"
click node_prompt "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/prompt.ts"
click node_state "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/state.ts"
click node_guardrails "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/guardrails.ts"
click node_finddoctors "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/tools/findDoctors.ts"
click node_availability "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/tools/checkAvailability.ts"
click node_booking "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/tools/bookAppointment.ts"
click node_cancellation "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/tools/cancelAppointment.ts"
click node_rescheduling "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/tools/rescheduleAppointment.ts"
click node_mongodb "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/mongodb.ts"
click node_patientrepo "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/repositories/patientRepository.ts"
click node_doctorrepo "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/repositories/doctorRepository.ts"
click node_appointmentrepo "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/repositories/appointmentRepository.ts"
click node_conversationrepo "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/repositories/conversationRepository.ts"
click node_appointmentmodel "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/models/Appointment.ts"
click node_doctormodel "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/models/Doctor.ts"
click node_patientmodel "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/models/Patient.ts"
click node_conversationmodel "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/models/Conversation.ts"
click node_evalapi "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/app/api/evaluation/route.ts"
click node_evaluator "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/evaluation/evaluator.ts"
click node_scenarios "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/evaluation/scenarios.ts"
click node_metrics "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/evaluation/metrics.ts"
click node_evalrunner "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/evaluation/run.ts"
click node_improvement "https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/evaluation/selfImprovement.ts"

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,node_chatapi,node_messageview,node_doctorcard,node_slotselector,node_appointmentcard toneBlue
class node_agent,node_prompt,node_state,node_guardrails,node_finddoctors,node_availability,node_booking,node_cancellation,node_rescheduling toneAmber
class node_mongodb,node_patientrepo,node_doctorrepo,node_appointmentrepo,node_conversationrepo,node_appointmentmodel,node_doctormodel,node_patientmodel,node_conversationmodel,node_gemini toneMint
class node_evalapi,node_evaluator,node_scenarios,node_metrics,node_evalrunner,node_improvement toneRose
class node_patient toneIndigo
```

## Components

### Patient experience

- [Chat interface](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/components/Chat.tsx): `components/Chat.tsx`
- [Chat API](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/app/api/chat/route.ts): `app/api/chat/route.ts`
- [Message view](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/components/Message.tsx): `components/Message.tsx`
- [Doctor cards](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/components/DoctorCard.tsx): `components/DoctorCard.tsx`
- [Slot selector](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/components/SlotSelector.tsx): `components/SlotSelector.tsx`
- [Appointment card](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/components/AppointmentCard.tsx): `components/AppointmentCard.tsx`

### Scheduling assistant

- [Agent orchestrator](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/agent.ts): `agent/agent.ts`
- [System prompt](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/prompt.ts): `agent/prompt.ts`
- [Appointment state](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/state.ts): `agent/state.ts`
- [Booking guardrails](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/guardrails.ts): `agent/guardrails.ts`
- [Doctor discovery](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/tools/findDoctors.ts): `agent/tools/findDoctors.ts`
- [Slot availability](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/tools/checkAvailability.ts): `agent/tools/checkAvailability.ts`
- [Book appointment](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/tools/bookAppointment.ts): `agent/tools/bookAppointment.ts`
- [Cancel appointment](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/tools/cancelAppointment.ts): `agent/tools/cancelAppointment.ts`
- [Reschedule appointment](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/agent/tools/rescheduleAppointment.ts): `agent/tools/rescheduleAppointment.ts`

### MongoDB persistence

- [MongoDB connection](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/mongodb.ts): `db/mongodb.ts`
- [Patient repository](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/repositories/patientRepository.ts): `db/repositories/patientRepository.ts`
- [Doctor repository](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/repositories/doctorRepository.ts): `db/repositories/doctorRepository.ts`
- [Appointment repository](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/repositories/appointmentRepository.ts): `db/repositories/appointmentRepository.ts`
- [Conversation repository](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/repositories/conversationRepository.ts): `db/repositories/conversationRepository.ts`
- [Appointment model](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/models/Appointment.ts): `db/models/Appointment.ts`
- [Doctor model](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/models/Doctor.ts): `db/models/Doctor.ts`
- [Patient model](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/models/Patient.ts): `db/models/Patient.ts`
- [Conversation model](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/db/models/Conversation.ts): `db/models/Conversation.ts`

### Agent evaluation

- [Evaluation API](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/app/api/evaluation/route.ts): `app/api/evaluation/route.ts`
- [Scenario evaluator](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/evaluation/evaluator.ts): `evaluation/evaluator.ts`
- [Evaluation scenarios](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/evaluation/scenarios.ts): `evaluation/scenarios.ts`
- [Evaluation metrics](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/evaluation/metrics.ts): `evaluation/metrics.ts`
- [Evaluation runner](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/evaluation/run.ts): `evaluation/run.ts`
- [Improvement loop](https://github.com/abhishek-3191/patient-scheduling-assistant/blob/main/evaluation/selfImprovement.ts): `evaluation/selfImprovement.ts`

### Other components

- **Patient**
- **Gemini API**

## Connections

- Patient → Chat interface: sends requests (evidence: `components/Chat.tsx`)
- Chat interface → Chat API: posts messages (evidence: `components/Chat.tsx`)
- Chat API → Agent orchestrator: runs agent (evidence: `app/api/chat/route.ts`)
- Chat API → Patient repository: looks up patient (evidence: `app/api/chat/route.ts`)
- Chat API → Conversation repository: loads and saves session (evidence: `app/api/chat/route.ts`)
- Chat API → MongoDB connection: connects (evidence: `app/api/chat/route.ts`)
- Chat API → Chat interface: returns structured results (evidence: `components/Chat.tsx`)
- Chat interface → Message view: renders (evidence: `components/Chat.tsx`)
- Chat interface → Doctor cards: renders (evidence: `components/Chat.tsx`)
- Chat interface → Slot selector: renders (evidence: `components/Chat.tsx`)
- Chat interface → Appointment card: renders (evidence: `components/Chat.tsx`)
- Appointment card → Patient: offers appointment PDF (evidence: `components/AppointmentCard.tsx`)
- Agent orchestrator → Gemini API: generates responses (evidence: `agent/agent.ts`)
- Agent orchestrator → System prompt: builds instructions (evidence: `agent/agent.ts`)
- Agent orchestrator → Doctor discovery: dispatches discovery (evidence: `agent/agent.ts`)
- Agent orchestrator → Slot availability: dispatches availability (evidence: `agent/agent.ts`)
- Agent orchestrator → Book appointment: dispatches booking (evidence: `agent/agent.ts`)
- Agent orchestrator → Cancel appointment: dispatches cancellation (evidence: `agent/agent.ts`)
- Agent orchestrator → Reschedule appointment: dispatches rescheduling (evidence: `agent/agent.ts`)
- Agent orchestrator → Appointment state: updates state (evidence: `agent/agent.ts`)
- Book appointment → Booking guardrails: validates booking (evidence: `agent/tools/bookAppointment.ts`)
- Book appointment → Doctor repository: gets doctor (evidence: `agent/tools/bookAppointment.ts`)
- Book appointment → Patient repository: gets patient (evidence: `agent/tools/bookAppointment.ts`)
- Book appointment → Appointment repository: checks and creates booking (evidence: `agent/tools/bookAppointment.ts`)
- Doctor discovery → Doctor repository: searches doctors (evidence: `agent/tools/findDoctors.ts`)
- Slot availability → Doctor repository: gets doctor schedule (evidence: `agent/tools/checkAvailability.ts`)
- Slot availability → Appointment repository: checks booked slots (evidence: `agent/tools/checkAvailability.ts`)
- Cancel appointment → Appointment repository: cancels booking (evidence: `agent/tools/cancelAppointment.ts`)
- Reschedule appointment → Appointment repository: updates booking (evidence: `agent/tools/rescheduleAppointment.ts`)
- Reschedule appointment → Doctor repository: checks doctor (evidence: `agent/tools/rescheduleAppointment.ts`)
- Patient repository → Patient model: queries (evidence: `db/repositories/patientRepository.ts`)
- Doctor repository → Doctor model: queries (evidence: `db/repositories/doctorRepository.ts`)
- Appointment repository → Appointment model: reads and writes (evidence: `db/repositories/appointmentRepository.ts`)
- Conversation repository → Conversation model: reads and writes (evidence: `db/repositories/conversationRepository.ts`)
- Evaluation API → MongoDB connection: connects (evidence: `app/api/evaluation/route.ts`)
- Evaluation API → Patient repository: loads evaluation patient (evidence: `app/api/evaluation/route.ts`)
- Evaluation API → Scenario evaluator: runs scenarios (evidence: `app/api/evaluation/route.ts`)
- Evaluation API → Evaluation metrics: calculates results (evidence: `app/api/evaluation/route.ts`)
- Evaluation runner → MongoDB connection: connects (evidence: `evaluation/run.ts`)
- Evaluation runner → Scenario evaluator: runs scenarios (evidence: `evaluation/run.ts`)
- Evaluation runner → Evaluation metrics: summarizes results (evidence: `evaluation/run.ts`)
- Scenario evaluator → Agent orchestrator: evaluates behavior (evidence: `evaluation/evaluator.ts`)
- Scenario evaluator → Evaluation scenarios: loads scenarios (evidence: `evaluation/evaluator.ts`)
- Scenario evaluator → Evaluation metrics: produces scenario results (evidence: `evaluation/evaluator.ts`)
- Improvement loop → Scenario evaluator: compares runs (evidence: `evaluation/selfImprovement.ts`)
- Improvement loop → Evaluation metrics: compares pass rates (evidence: `evaluation/selfImprovement.ts`)
