# tanmay-awal/clinic-ai architecture

> Architecture diagram of the GitHub repository tanmay-awal/clinic-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tanmay-awal/clinic-ai
- Repository: https://github.com/tanmay-awal/clinic-ai

## Overview

Clinic AI combines a patient-facing phone agent with a clinic operations dashboard. Patients call through Twilio; the bot conducts a structured conversation, while the backend provides appointment, call-analysis, action, and reporting capabilities that clinic staff access through the frontend. The README documents the bot’s speech/LLM pipeline and post-call analysis; sampled controllers confirm the API ownership shown, but unsampled service internals limit certainty about some integrations.

Main entry points: [`clinic-backend/src/data-source.ts`](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/data-source.ts) (PostgreSQL), [`clinic-bot/bot.py`](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-bot/bot.py) (Speech services), [`clinic-frontend/src/app/(protected)/layout.tsx`](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/(protected)/layout.tsx) (Clinic dashboard), [`clinic-backend/src/call/call.controller.ts`](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/call/call.controller.ts) (Call API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice agent"]
  node_twilio{{"Twilio"}}
  node_botserver["Call server<br/>[server.py]"]
  node_botflow["Conversation flow<br/>[bot.py]"]
  node_speech["Speech services<br/>[bot.py]"]
  node_botruntime["Bot runtime<br/>[runtime.py]"]
  node_groq{{"Groq / OpenRouter"}}
  node_deepgram{{"Deepgram STT"}}
  node_cartesia{{"Cartesia TTS"}}
end

subgraph group_backend["Clinic API"]
  node_userapi["Identity API<br/>[user.controller.ts]"]
  node_appointmentapi["Appointment API"]
  node_callapi["Call API<br/>[call.controller.ts]"]
  node_callanalysis["Call analysis<br/>[ai.service.ts]"]
  node_database[("PostgreSQL<br/>[data-source.ts]")]
end

subgraph group_operations["Clinic operations"]
  node_actionapi["Action API"]
  node_dashboardapi["Dashboard API"]
  node_reportsapi["Reports API"]
  node_adminapi["Admin API"]
end

subgraph group_frontend["Staff dashboard"]
  node_webapp["Clinic dashboard<br/>[layout.tsx]"]
  node_callview["Call review<br/>[page.tsx]"]
  node_insightsview["Insights<br/>[page.tsx]"]
  node_actionsview["Action management<br/>[page.tsx]"]
  node_reportsview["Report builder<br/>[page.tsx]"]
  node_appointmentsview["Appointment management<br/>[page.tsx]"]
end

node_patient(("Patient"))
node_staff(("Clinic staff"))

node_patient -->|"calls"| node_twilio
node_twilio -->|"streams audio"| node_botserver
node_botserver -->|"starts call"| node_botflow
node_botflow -->|"processes dialogue"| node_speech
node_speech -->|"transcribes"| node_deepgram
node_speech -->|"generates replies"| node_groq
node_speech -->|"synthesizes speech"| node_cartesia
node_speech -->|"returns audio"| node_twilio
node_botflow -->|"records telemetry"| node_botruntime
node_botserver -->|"submits call"| node_callapi
node_callapi -->|"analyzes call"| node_callanalysis
node_callapi -->|"stores call data"| node_database
node_callanalysis -->|"stores analysis"| node_database
node_staff -->|"uses"| node_webapp
node_webapp -->|"authenticates"| node_userapi
node_webapp -->|"requests metrics"| node_dashboardapi
node_callview -->|"loads call"| node_callapi
node_insightsview -->|"loads insights"| node_dashboardapi
node_actionsview -->|"manages tasks"| node_actionapi
node_reportsview -->|"generates reports"| node_reportsapi
node_appointmentsview -->|"manages bookings"| node_appointmentapi
node_webapp -->|"manages users"| node_adminapi
node_appointmentapi -->|"reads and writes"| node_database
node_actionapi -->|"reads and writes"| node_database
node_dashboardapi -->|"queries analytics"| node_database
node_reportsapi -->|"queries report data"| node_database
node_adminapi -->|"reads and writes"| node_database

click node_botserver "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-bot/server.py"
click node_botflow "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-bot/bot.py"
click node_speech "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-bot/bot.py"
click node_botruntime "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-bot/runtime.py"
click node_userapi "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/user/user.controller.ts"
click node_appointmentapi "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/appointments/appointments.controller.ts"
click node_callapi "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/call/call.controller.ts"
click node_callanalysis "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/ai/ai.service.ts"
click node_actionapi "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/actions/actions.controller.ts"
click node_dashboardapi "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/dashboard/dashboard.controller.ts"
click node_reportsapi "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/reports/reports.controller.ts"
click node_adminapi "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/admin/admin.controller.ts"
click node_database "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/data-source.ts"
click node_webapp "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/(protected)/layout.tsx"
click node_callview "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/calls/%5BcallId%5D/page.tsx"
click node_insightsview "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/insights/page.tsx"
click node_actionsview "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/actions/page.tsx"
click node_reportsview "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/reports/page.tsx"
click node_appointmentsview "https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/outbound/page.tsx"

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_twilio,node_botserver,node_botflow,node_speech,node_botruntime,node_groq,node_deepgram,node_cartesia toneBlue
class node_userapi,node_appointmentapi,node_callapi,node_callanalysis,node_database toneAmber
class node_actionapi,node_dashboardapi,node_reportsapi,node_adminapi toneMint
class node_webapp,node_callview,node_insightsview,node_actionsview,node_reportsview,node_appointmentsview toneRose
class node_patient,node_staff toneIndigo
```

## Components

### Voice agent

- **Twilio**
- [Call server](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-bot/server.py): `clinic-bot/server.py`
- [Conversation flow](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-bot/bot.py): `clinic-bot/bot.py`
- [Speech services](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-bot/bot.py): `clinic-bot/bot.py`
- [Bot runtime](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-bot/runtime.py): `clinic-bot/runtime.py`
- **Groq / OpenRouter**
- **Deepgram STT**
- **Cartesia TTS**

### Clinic API

- [Identity API](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/user/user.controller.ts): `clinic-backend/src/user/user.controller.ts`
- [Appointment API](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/appointments/appointments.controller.ts): `clinic-backend/src/appointments/appointments.controller.ts`
- [Call API](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/call/call.controller.ts): `clinic-backend/src/call/call.controller.ts`
- [Call analysis](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/ai/ai.service.ts): `clinic-backend/src/ai/ai.service.ts`
- [PostgreSQL](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/data-source.ts): `clinic-backend/src/data-source.ts`

### Clinic operations

- [Action API](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/actions/actions.controller.ts): `clinic-backend/src/actions/actions.controller.ts`
- [Dashboard API](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/dashboard/dashboard.controller.ts): `clinic-backend/src/dashboard/dashboard.controller.ts`
- [Reports API](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/reports/reports.controller.ts): `clinic-backend/src/reports/reports.controller.ts`
- [Admin API](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-backend/src/admin/admin.controller.ts): `clinic-backend/src/admin/admin.controller.ts`

### Staff dashboard

- [Clinic dashboard](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/(protected)/layout.tsx): `clinic-frontend/src/app/(protected)/layout.tsx`
- [Call review](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/calls/%5BcallId%5D/page.tsx): `clinic-frontend/src/app/calls/[callId]/page.tsx`
- [Insights](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/insights/page.tsx): `clinic-frontend/src/app/insights/page.tsx`
- [Action management](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/actions/page.tsx): `clinic-frontend/src/app/actions/page.tsx`
- [Report builder](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/reports/page.tsx): `clinic-frontend/src/app/reports/page.tsx`
- [Appointment management](https://github.com/tanmay-awal/clinic-ai/blob/main/clinic-frontend/src/app/outbound/page.tsx): `clinic-frontend/src/app/outbound/page.tsx`

### Other components

- **Patient**
- **Clinic staff**

## Connections

- Patient → Twilio: calls
- Twilio → Call server: streams audio
- Call server → Conversation flow: starts call
- Conversation flow → Speech services: processes dialogue
- Speech services → Deepgram STT: transcribes
- Speech services → Groq / OpenRouter: generates replies
- Speech services → Cartesia TTS: synthesizes speech
- Speech services → Twilio: returns audio
- Conversation flow → Bot runtime: records telemetry
- Call server → Call API: submits call
- Call API → Call analysis: analyzes call
- Call API → PostgreSQL: stores call data
- Call analysis → PostgreSQL: stores analysis
- Clinic staff → Clinic dashboard: uses
- Clinic dashboard → Identity API: authenticates
- Clinic dashboard → Dashboard API: requests metrics
- Call review → Call API: loads call
- Insights → Dashboard API: loads insights
- Action management → Action API: manages tasks
- Report builder → Reports API: generates reports
- Appointment management → Appointment API: manages bookings
- Clinic dashboard → Admin API: manages users
- Appointment API → PostgreSQL: reads and writes
- Action API → PostgreSQL: reads and writes
- Dashboard API → PostgreSQL: queries analytics
- Reports API → PostgreSQL: queries report data
- Admin API → PostgreSQL: reads and writes