# hunainasif/openclinic architecture

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

- Interactive diagram: https://gitdiagram.com/hunainasif/openclinic
- Repository: https://github.com/hunainasif/openclinic

## Overview

Open Clinic AI is a healthcare voice receptionist with an admin dashboard. The primary workflow is a browser voice turn through transcription, guarded multi-agent routing, clinic-document retrieval or appointment actions, then spoken response; emergencies trigger notification. The dashboard separately manages appointments, doctors and schedules, knowledge documents, call history, and analytics. The graph preserves these documented capabilities, but many voice, agent, dashboard-service, and analytics implementations were not sampled, so those links are documented or marked unverified rather than inferred from module names.

Main entry points: [`apps/api/src/libs/prisma.ts`](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/prisma.ts) (PostgreSQL), [`apps/api/src/agents/appointment.node.ts`](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/appointment.node.ts) (Booking specialist), [`apps/api/src/agents/supervisor.node.ts`](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/supervisor.node.ts) (Turn supervisor), [`apps/api/src/controllers/knowledgeBase.controller.ts`](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/knowledgeBase.controller.ts) (Knowledge API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice and agents"]
  node_voice_session["Voice session<br/>[voice-turn.ts]"]
  node_stt["Speech recognition<br/>[deepgram.ts]"]
  node_agent_graph["Agent graph<br/>[graph.ts]"]
  node_guardrail["Input guardrail<br/>[guardrail.node.ts]"]
  node_supervisor["Turn supervisor<br/>[supervisor.node.ts]"]
  node_faq_agent["FAQ specialist<br/>[faq.node.ts]"]
  node_appointment_agent["Booking specialist"]
  node_emergency_agent["Emergency specialist<br/>[emergency.node.ts]"]
  node_tts["Speech synthesis<br/>[elevenlabs.ts]"]
  node_mailer["Clinic email<br/>[mailer.ts]"]
end

subgraph group_knowledge["Clinic knowledge"]
  node_clinic_docs["Uploaded documents"]
  node_text_extract["Text extraction<br/>[textExtraction.ts]"]
  node_rag_ingest["Document ingestion<br/>[knowledgeBase.ts]"]
  node_vector_store["Vector retrieval<br/>[vectorStore.ts]"]
  node_pinecone[("Pinecone<br/>[pinecone.ts]")]
end

subgraph group_admin["Clinic administration"]
end

subgraph group_api["API and persistence"]
  node_appointment_controller["Appointment API"]
  node_appointment_data["Appointment data access"]
  node_doctor_controller["Doctor API"]
  node_schedule_controller["Schedule API"]
  node_exception_controller["Schedule exceptions"]
  node_knowledge_controller["Knowledge API"]
  node_calls_controller["Call records API<br/>[call.controller.ts]"]
  node_analytics_controller["Analytics API"]
  node_postgres[("PostgreSQL<br/>[prisma.ts]")]
end

subgraph group_web["Web experience"]
  node_browser_voice["Voice interface<br/>[call-overlay.tsx]"]
  node_dashboard["Admin dashboard<br/>[page.tsx]"]
  node_booking_ui["Appointment management<br/>[page.tsx]"]
  node_doctor_ui["Doctor management<br/>[page.tsx]"]
  node_knowledge_ui["Knowledge management<br/>[page.tsx]"]
  node_call_history["Call history<br/>[page.tsx]"]
  node_analytics_ui["Analytics<br/>[page.tsx]"]
end

node_caller(("Caller"))
node_admin(("Clinic administrator"))
node_deepgram_service["Deepgram"]

node_caller -->|"starts call"| node_browser_voice
node_browser_voice -->|"streams turns"| node_voice_session
node_voice_session -->|"transcribes audio"| node_stt
node_stt -->|"passes transcript"| node_agent_graph
node_agent_graph -->|"starts turn"| node_guardrail
node_guardrail -->|"allows input"| node_supervisor
node_supervisor -->|"routes turn"| node_faq_agent
node_supervisor -->|"routes turn"| node_appointment_agent
node_supervisor -->|"routes turn"| node_emergency_agent
node_faq_agent -->|"retrieves context"| node_vector_store
node_faq_agent -->|"returns answer"| node_tts
node_appointment_agent -.->|"books appointment"| node_appointment_controller
node_appointment_agent -.->|"looks up doctors"| node_doctor_controller
node_appointment_agent -.->|"checks schedules"| node_schedule_controller
node_appointment_agent -->|"emails confirmation"| node_mailer
node_emergency_agent -->|"sends alert"| node_mailer
node_tts -->|"streams speech"| node_voice_session
node_voice_session -->|"returns audio"| node_browser_voice
node_admin -->|"manages clinic"| node_dashboard
node_admin -->|"manages bookings"| node_booking_ui
node_admin -->|"manages doctors"| node_doctor_ui
node_admin -->|"manages documents"| node_knowledge_ui
node_admin -->|"reviews calls"| node_call_history
node_admin -->|"reviews analytics"| node_analytics_ui
node_booking_ui -.->|"uses API"| node_appointment_controller
node_doctor_ui -.->|"uses API"| node_doctor_controller
node_knowledge_ui -.->|"uses API"| node_knowledge_controller
node_call_history -.->|"uses API"| node_calls_controller
node_analytics_ui -.->|"uses API"| node_analytics_controller
node_appointment_controller -->|"reads and writes"| node_appointment_data
node_appointment_data -->|"queries database"| node_postgres
node_knowledge_controller -->|"extracts text"| node_text_extract
node_knowledge_controller -->|"ingests document"| node_rag_ingest
node_knowledge_controller -->|"stores document record"| node_clinic_docs
node_rag_ingest -->|"indexes vectors"| node_pinecone
node_vector_store -.->|"searches vectors"| node_pinecone
node_clinic_docs -.->|"persists metadata"| node_postgres
node_doctor_controller -.->|"persists doctors"| node_postgres
node_schedule_controller -.->|"persists schedules"| node_postgres
node_exception_controller -.->|"persists exceptions"| node_postgres
node_calls_controller -.->|"persists call history"| node_postgres
node_analytics_controller -.->|"reads metrics"| node_postgres

click node_browser_voice "https://github.com/hunainasif/openclinic/blob/main/apps/web/src/components/call/call-overlay.tsx"
click node_voice_session "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/sockets/handlers/voice-turn.ts"
click node_stt "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/deepgram.ts"
click node_agent_graph "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/graph.ts"
click node_guardrail "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/guardrail.node.ts"
click node_supervisor "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/supervisor.node.ts"
click node_faq_agent "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/faq.node.ts"
click node_appointment_agent "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/appointment.node.ts"
click node_emergency_agent "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/emergency.node.ts"
click node_tts "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/elevenlabs.ts"
click node_mailer "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/mailer.ts"
click node_clinic_docs "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/knowledgeBase.controller.ts"
click node_text_extract "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/helpers/textExtraction.ts"
click node_rag_ingest "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/helpers/knowledgeBase.ts"
click node_vector_store "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/vectorStore.ts"
click node_pinecone "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/pinecone.ts"
click node_dashboard "https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/dashboard/page.tsx"
click node_booking_ui "https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/appointments/page.tsx"
click node_doctor_ui "https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/doctors/page.tsx"
click node_knowledge_ui "https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/knowledge-base/page.tsx"
click node_call_history "https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/calls/page.tsx"
click node_analytics_ui "https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/analytics/page.tsx"
click node_appointment_controller "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/appointments.controller.ts"
click node_appointment_data "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/data/appointments.data.ts"
click node_doctor_controller "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/doctors.controller.ts"
click node_schedule_controller "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/schedules.controller.ts"
click node_exception_controller "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/exceptions.controller.ts"
click node_knowledge_controller "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/knowledgeBase.controller.ts"
click node_calls_controller "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/call.controller.ts"
click node_analytics_controller "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/analytics.controller.ts"
click node_postgres "https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/prisma.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_voice_session,node_stt,node_agent_graph,node_guardrail,node_supervisor,node_faq_agent,node_appointment_agent,node_emergency_agent,node_tts,node_mailer toneBlue
class node_clinic_docs,node_text_extract,node_rag_ingest,node_vector_store,node_pinecone toneAmber
class node_appointment_controller,node_appointment_data,node_doctor_controller,node_schedule_controller,node_exception_controller,node_knowledge_controller,node_calls_controller,node_analytics_controller,node_postgres toneRose
class node_browser_voice,node_dashboard,node_booking_ui,node_doctor_ui,node_knowledge_ui,node_call_history,node_analytics_ui,node_caller,node_admin,node_deepgram_service toneIndigo
```

## Components

### Voice and agents

- [Voice session](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/sockets/handlers/voice-turn.ts): `apps/api/src/sockets/handlers/voice-turn.ts`
- [Speech recognition](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/deepgram.ts): `apps/api/src/libs/deepgram.ts`
- [Agent graph](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/graph.ts): `apps/api/src/agents/graph.ts`
- [Input guardrail](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/guardrail.node.ts): `apps/api/src/agents/guardrail.node.ts`
- [Turn supervisor](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/supervisor.node.ts): `apps/api/src/agents/supervisor.node.ts`
- [FAQ specialist](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/faq.node.ts): `apps/api/src/agents/faq.node.ts`
- [Booking specialist](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/appointment.node.ts): `apps/api/src/agents/appointment.node.ts`
- [Emergency specialist](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/agents/emergency.node.ts): `apps/api/src/agents/emergency.node.ts`
- [Speech synthesis](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/elevenlabs.ts): `apps/api/src/libs/elevenlabs.ts`
- [Clinic email](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/mailer.ts): `apps/api/src/libs/mailer.ts`

### Clinic knowledge

- [Uploaded documents](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/knowledgeBase.controller.ts): `apps/api/src/controllers/knowledgeBase.controller.ts`
- [Text extraction](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/helpers/textExtraction.ts): `apps/api/src/helpers/textExtraction.ts`
- [Document ingestion](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/helpers/knowledgeBase.ts): `apps/api/src/helpers/knowledgeBase.ts`
- [Vector retrieval](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/vectorStore.ts): `apps/api/src/libs/vectorStore.ts`
- [Pinecone](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/pinecone.ts): `apps/api/src/libs/pinecone.ts`

### API and persistence

- [Appointment API](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/appointments.controller.ts): `apps/api/src/controllers/appointments.controller.ts`
- [Appointment data access](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/data/appointments.data.ts): `apps/api/src/data/appointments.data.ts`
- [Doctor API](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/doctors.controller.ts): `apps/api/src/controllers/doctors.controller.ts`
- [Schedule API](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/schedules.controller.ts): `apps/api/src/controllers/schedules.controller.ts`
- [Schedule exceptions](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/exceptions.controller.ts): `apps/api/src/controllers/exceptions.controller.ts`
- [Knowledge API](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/knowledgeBase.controller.ts): `apps/api/src/controllers/knowledgeBase.controller.ts`
- [Call records API](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/call.controller.ts): `apps/api/src/controllers/call.controller.ts`
- [Analytics API](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/controllers/analytics.controller.ts): `apps/api/src/controllers/analytics.controller.ts`
- [PostgreSQL](https://github.com/hunainasif/openclinic/blob/main/apps/api/src/libs/prisma.ts): `apps/api/src/libs/prisma.ts`

### Web experience

- [Voice interface](https://github.com/hunainasif/openclinic/blob/main/apps/web/src/components/call/call-overlay.tsx): `apps/web/src/components/call/call-overlay.tsx`
- [Admin dashboard](https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/dashboard/page.tsx): `apps/web/src/app/(app)/dashboard/page.tsx`
- [Appointment management](https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/appointments/page.tsx): `apps/web/src/app/(app)/appointments/page.tsx`
- [Doctor management](https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/doctors/page.tsx): `apps/web/src/app/(app)/doctors/page.tsx`
- [Knowledge management](https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/knowledge-base/page.tsx): `apps/web/src/app/(app)/knowledge-base/page.tsx`
- [Call history](https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/calls/page.tsx): `apps/web/src/app/(app)/calls/page.tsx`
- [Analytics](https://github.com/hunainasif/openclinic/blob/main/apps/web/src/app/(app)/analytics/page.tsx): `apps/web/src/app/(app)/analytics/page.tsx`

### Other components

- **Caller**
- **Clinic administrator**
- **Deepgram**

## Connections

- Caller → Voice interface: starts call (evidence: `README.md`)
- Voice interface → Voice session: streams turns (evidence: `README.md`)
- Voice session → Speech recognition: transcribes audio (evidence: `README.md`)
- Speech recognition → Agent graph: passes transcript (evidence: `README.md`)
- Agent graph → Input guardrail: starts turn (evidence: `README.md`)
- Input guardrail → Turn supervisor: allows input (evidence: `README.md`)
- Turn supervisor → FAQ specialist: routes turn (evidence: `README.md`)
- Turn supervisor → Booking specialist: routes turn (evidence: `README.md`)
- Turn supervisor → Emergency specialist: routes turn (evidence: `README.md`)
- FAQ specialist → Vector retrieval: retrieves context (evidence: `README.md`)
- FAQ specialist → Speech synthesis: returns answer (evidence: `README.md`)
- Booking specialist → Appointment API: books appointment
- Booking specialist → Doctor API: looks up doctors
- Booking specialist → Schedule API: checks schedules
- Booking specialist → Clinic email: emails confirmation (evidence: `README.md`)
- Emergency specialist → Clinic email: sends alert (evidence: `README.md`)
- Speech synthesis → Voice session: streams speech (evidence: `README.md`)
- Voice session → Voice interface: returns audio (evidence: `README.md`)
- Clinic administrator → Admin dashboard: manages clinic (evidence: `README.md`)
- Clinic administrator → Appointment management: manages bookings (evidence: `README.md`)
- Clinic administrator → Doctor management: manages doctors (evidence: `README.md`)
- Clinic administrator → Knowledge management: manages documents (evidence: `README.md`)
- Clinic administrator → Call history: reviews calls (evidence: `README.md`)
- Clinic administrator → Analytics: reviews analytics (evidence: `README.md`)
- Appointment management → Appointment API: uses API
- Doctor management → Doctor API: uses API
- Knowledge management → Knowledge API: uses API
- Call history → Call records API: uses API
- Analytics → Analytics API: uses API
- Appointment API → Appointment data access: reads and writes (evidence: `apps/api/src/controllers/appointments.controller.ts`)
- Appointment data access → PostgreSQL: queries database (evidence: `apps/api/src/data/appointments.data.ts`)
- Knowledge API → Text extraction: extracts text (evidence: `apps/api/src/controllers/knowledgeBase.controller.ts`)
- Knowledge API → Document ingestion: ingests document (evidence: `apps/api/src/controllers/knowledgeBase.controller.ts`)
- Knowledge API → Uploaded documents: stores document record (evidence: `apps/api/src/controllers/knowledgeBase.controller.ts`)
- Document ingestion → Pinecone: indexes vectors (evidence: `apps/api/src/helpers/knowledgeBase.ts`)
- Vector retrieval → Pinecone: searches vectors
- Uploaded documents → PostgreSQL: persists metadata
- Doctor API → PostgreSQL: persists doctors
- Schedule API → PostgreSQL: persists schedules
- Schedule exceptions → PostgreSQL: persists exceptions
- Call records API → PostgreSQL: persists call history
- Analytics API → PostgreSQL: reads metrics
