# santin0-dev/kalqueue architecture

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

- Interactive diagram: https://gitdiagram.com/santin0-dev/kalqueue
- Repository: https://github.com/santin0-dev/kalqueue

## Overview

KalQueue is a staged clinic-visit and records system. Its principal workflow runs from patient intake and booking through queue tracking, doctor call-in and consultation, then to a saved record and patient history. Patients, doctors, and admins have distinct operational views; admins also manage announcements, reports, and backups. The queue engine is the central internal layer, coordinating ticket state, position estimates, notifications, and realtime updates. Relationships not visible in sampled code are included only where the README documents them; unsampled page behavior is not independently verified.

Main entry points: [`src/lib/prisma.ts`](https://github.com/santin0-dev/kalqueue/blob/main/src/lib/prisma.ts) (Clinic database), [`src/app/admin/dashboard/page.tsx`](https://github.com/santin0-dev/kalqueue/blob/main/src/app/admin/dashboard/page.tsx) (Operations dashboard), [`src/lib/queue-engine.ts`](https://github.com/santin0-dev/kalqueue/blob/main/src/lib/queue-engine.ts) (Queue engine), [`local-ai-service/server.py`](https://github.com/santin0-dev/kalqueue/blob/main/local-ai-service/server.py) (Local AI charting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_patient["Patient journey"]
  node_patient_views["Patient dashboard<br/>[page.tsx]"]
  node_booking["Booking and intake<br/>[page.tsx]"]
  node_intake_api["Intake submission<br/>[route.ts]"]
  node_queue_view["Queue tracking<br/>[page.tsx]"]
  node_history["Checkup history<br/>[page.tsx]"]
  node_notifications_view["Patient notifications<br/>[page.tsx]"]
end

subgraph group_clinic["Clinic operations"]
  node_doctor_queue["Doctor queue<br/>[page.tsx]"]
  node_consultation["Consultation records<br/>[page.tsx]"]
  node_availability["Doctor availability<br/>[route.ts]"]
  node_queue_api["Queue API<br/>[route.ts]"]
  node_queue_engine["Queue engine<br/>[queue-engine.ts]"]
end

subgraph group_admin["Administration"]
  node_admin_dashboard["Operations dashboard<br/>[page.tsx]"]
  node_admin_records["Records management<br/>[route.ts]"]
  node_admin_reports["Reports and downloads<br/>[route.ts]"]
  node_admin_backups["Backup downloads<br/>[route.ts]"]
end

subgraph group_platform["Shared services"]
  node_auth["Role-based auth<br/>[auth.ts]"]
  node_database[("Clinic database<br/>[prisma.ts]")]
  node_notifications["Notification service<br/>[notifications.ts]"]
  node_realtime["Realtime updates<br/>[pusher.ts]"]
end

subgraph group_ai["AI charting"]
  node_ai_service["Local AI charting<br/>[server.py]"]
end

node_patient_actor(("Patient"))
node_doctor_actor(("Doctor"))
node_admin_actor(("Admin"))
node_pusher_service["Pusher"]
node_twilio_service["Twilio SMS"]
node_whisper["Whisper transcription"]
node_ollama["Ollama chart formatting"]

node_patient_actor -->|"books visit"| node_booking
node_booking -.->|"submits intake"| node_intake_api
node_intake_api -.->|"writes intake"| node_database
node_patient_actor -->|"tracks position"| node_queue_view
node_queue_view -.->|"requests queue"| node_queue_api
node_queue_api -->|"gets or creates"| node_queue_engine
node_queue_engine -->|"reads and writes"| node_database
node_queue_engine -->|"broadcasts updates"| node_realtime
node_realtime -->|"publishes events"| node_pusher_service
node_queue_engine -->|"sends updates"| node_notifications
node_notifications -.->|"sends SMS"| node_twilio_service
node_patient_actor -->|"views visit"| node_patient_views
node_patient_views -.->|"views history"| node_history
node_patient_views -.->|"views alerts"| node_notifications_view
node_doctor_actor -->|"monitors queue"| node_doctor_queue
node_doctor_queue -.->|"loads queue"| node_queue_api
node_doctor_actor -->|"completes consultation"| node_consultation
node_consultation -.->|"saves record"| node_database
node_doctor_actor -.->|"sets availability"| node_availability
node_admin_actor -->|"monitors clinic"| node_admin_dashboard
node_admin_dashboard -.->|"manages records"| node_admin_records
node_admin_dashboard -->|"downloads reports"| node_admin_reports
node_admin_dashboard -->|"downloads backups"| node_admin_backups
node_admin_records -->|"reads and writes"| node_database
node_admin_reports -->|"reads records"| node_database
node_admin_backups -->|"reads data"| node_database
node_admin_dashboard -.->|"uses role access"| node_auth
node_consultation -->|"requests charting"| node_ai_service
node_ai_service -->|"transcribes audio"| node_whisper
node_ai_service -->|"formats transcript"| node_ollama
node_ai_service -->|"returns draft"| node_consultation

click node_patient_views "https://github.com/santin0-dev/kalqueue/blob/main/src/app/patient/dashboard/page.tsx"
click node_booking "https://github.com/santin0-dev/kalqueue/blob/main/src/app/patient/book/page.tsx"
click node_intake_api "https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/intake/route.ts"
click node_queue_view "https://github.com/santin0-dev/kalqueue/blob/main/src/app/patient/queue/page.tsx"
click node_history "https://github.com/santin0-dev/kalqueue/blob/main/src/app/patient/history/page.tsx"
click node_notifications_view "https://github.com/santin0-dev/kalqueue/blob/main/src/app/patient/notifications/page.tsx"
click node_doctor_queue "https://github.com/santin0-dev/kalqueue/blob/main/src/app/doctor/queue/page.tsx"
click node_consultation "https://github.com/santin0-dev/kalqueue/blob/main/src/app/doctor/dashboard/page.tsx"
click node_availability "https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/doctors/availability/route.ts"
click node_queue_api "https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/queue/route.ts"
click node_queue_engine "https://github.com/santin0-dev/kalqueue/blob/main/src/lib/queue-engine.ts"
click node_admin_dashboard "https://github.com/santin0-dev/kalqueue/blob/main/src/app/admin/dashboard/page.tsx"
click node_admin_records "https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/admin/records/route.ts"
click node_admin_reports "https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/admin/reports/download/route.ts"
click node_admin_backups "https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/admin/backups/route.ts"
click node_auth "https://github.com/santin0-dev/kalqueue/blob/main/src/lib/auth.ts"
click node_database "https://github.com/santin0-dev/kalqueue/blob/main/src/lib/prisma.ts"
click node_notifications "https://github.com/santin0-dev/kalqueue/blob/main/src/lib/notifications.ts"
click node_realtime "https://github.com/santin0-dev/kalqueue/blob/main/src/lib/pusher.ts"
click node_ai_service "https://github.com/santin0-dev/kalqueue/blob/main/local-ai-service/server.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_patient_views,node_booking,node_intake_api,node_queue_view,node_history,node_notifications_view toneBlue
class node_doctor_queue,node_consultation,node_availability,node_queue_api,node_queue_engine toneAmber
class node_admin_dashboard,node_admin_records,node_admin_reports,node_admin_backups toneMint
class node_auth,node_database,node_notifications,node_realtime toneRose
class node_ai_service,node_patient_actor,node_doctor_actor,node_admin_actor,node_pusher_service,node_twilio_service,node_whisper,node_ollama toneIndigo
```

## Components

### Patient journey

- [Patient dashboard](https://github.com/santin0-dev/kalqueue/blob/main/src/app/patient/dashboard/page.tsx): `src/app/patient/dashboard/page.tsx`
- [Booking and intake](https://github.com/santin0-dev/kalqueue/blob/main/src/app/patient/book/page.tsx): `src/app/patient/book/page.tsx`
- [Intake submission](https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/intake/route.ts): `src/app/api/intake/route.ts`
- [Queue tracking](https://github.com/santin0-dev/kalqueue/blob/main/src/app/patient/queue/page.tsx): `src/app/patient/queue/page.tsx`
- [Checkup history](https://github.com/santin0-dev/kalqueue/blob/main/src/app/patient/history/page.tsx): `src/app/patient/history/page.tsx`
- [Patient notifications](https://github.com/santin0-dev/kalqueue/blob/main/src/app/patient/notifications/page.tsx): `src/app/patient/notifications/page.tsx`

### Clinic operations

- [Doctor queue](https://github.com/santin0-dev/kalqueue/blob/main/src/app/doctor/queue/page.tsx): `src/app/doctor/queue/page.tsx`
- [Consultation records](https://github.com/santin0-dev/kalqueue/blob/main/src/app/doctor/dashboard/page.tsx): `src/app/doctor/dashboard/page.tsx`
- [Doctor availability](https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/doctors/availability/route.ts): `src/app/api/doctors/availability/route.ts`
- [Queue API](https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/queue/route.ts): `src/app/api/queue/route.ts`
- [Queue engine](https://github.com/santin0-dev/kalqueue/blob/main/src/lib/queue-engine.ts): `src/lib/queue-engine.ts`

### Administration

- [Operations dashboard](https://github.com/santin0-dev/kalqueue/blob/main/src/app/admin/dashboard/page.tsx): `src/app/admin/dashboard/page.tsx`
- [Records management](https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/admin/records/route.ts): `src/app/api/admin/records/route.ts`
- [Reports and downloads](https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/admin/reports/download/route.ts): `src/app/api/admin/reports/download/route.ts`
- [Backup downloads](https://github.com/santin0-dev/kalqueue/blob/main/src/app/api/admin/backups/route.ts): `src/app/api/admin/backups/route.ts`

### Shared services

- [Role-based auth](https://github.com/santin0-dev/kalqueue/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Clinic database](https://github.com/santin0-dev/kalqueue/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`
- [Notification service](https://github.com/santin0-dev/kalqueue/blob/main/src/lib/notifications.ts): `src/lib/notifications.ts`
- [Realtime updates](https://github.com/santin0-dev/kalqueue/blob/main/src/lib/pusher.ts): `src/lib/pusher.ts`

### AI charting

- [Local AI charting](https://github.com/santin0-dev/kalqueue/blob/main/local-ai-service/server.py): `local-ai-service/server.py`

### Other components

- **Patient**
- **Doctor**
- **Admin**
- **Pusher**
- **Twilio SMS**
- **Whisper transcription**
- **Ollama chart formatting**

## Connections

- Patient → Booking and intake: books visit
- Booking and intake → Intake submission: submits intake
- Intake submission → Clinic database: writes intake (evidence: `src/app/api/intake/route.ts`)
- Patient → Queue tracking: tracks position
- Queue tracking → Queue API: requests queue
- Queue API → Queue engine: gets or creates (evidence: `src/app/api/queue/route.ts`)
- Queue engine → Clinic database: reads and writes (evidence: `src/lib/queue-engine.ts`)
- Queue engine → Realtime updates: broadcasts updates (evidence: `src/lib/queue-engine.ts`)
- Realtime updates → Pusher: publishes events
- Queue engine → Notification service: sends updates (evidence: `src/lib/queue-engine.ts`)
- Notification service → Twilio SMS: sends SMS
- Patient → Patient dashboard: views visit
- Patient dashboard → Checkup history: views history
- Patient dashboard → Patient notifications: views alerts
- Doctor → Doctor queue: monitors queue
- Doctor queue → Queue API: loads queue
- Doctor → Consultation records: completes consultation
- Consultation records → Clinic database: saves record
- Doctor → Doctor availability: sets availability
- Admin → Operations dashboard: monitors clinic
- Operations dashboard → Records management: manages records
- Operations dashboard → Reports and downloads: downloads reports
- Operations dashboard → Backup downloads: downloads backups
- Records management → Clinic database: reads and writes (evidence: `src/app/api/admin/records/route.ts`)
- Reports and downloads → Clinic database: reads records (evidence: `src/app/api/admin/reports/download/route.ts`)
- Backup downloads → Clinic database: reads data (evidence: `src/app/api/admin/backups/route.ts`)
- Operations dashboard → Role-based auth: uses role access
- Consultation records → Local AI charting: requests charting
- Local AI charting → Whisper transcription: transcribes audio
- Local AI charting → Ollama chart formatting: formats transcript
- Local AI charting → Consultation records: returns draft
