# sundaramkasera/medikiosk architecture

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

- Interactive diagram: https://gitdiagram.com/sundaramkasera/medikiosk
- Repository: https://github.com/sundaramkasera/medikiosk

## Overview

MediKiosk is a touchless clinical-intake and triage platform: a patient kiosk wakes on proximity, conducts a voice interview, and can hand off documents for OCR; clinicians review encounters, summaries, and documents in a real-time dashboard. The backend coordinates Socket.IO events, interview reasoning, document processing, and MongoDB persistence. The graph reflects excerpted calls and indexed imports; some features and wiring are documented in the README but their implementation was not sampled, so those links are marked as documented or unverified.

Main entry points: [`backend/core/websocket_hub.py`](https://github.com/sundaramkasera/medikiosk/blob/main/backend/core/websocket_hub.py) (Realtime Event Hub), [`backend/ai_engine/ocr_pipeline.py`](https://github.com/sundaramkasera/medikiosk/blob/main/backend/ai_engine/ocr_pipeline.py) (Document OCR & Structuring), [`kiosk_frontend/src/App.jsx`](https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/App.jsx) (Kiosk App), [`doctor_dashboard/src/App.jsx`](https://github.com/sundaramkasera/medikiosk/blob/main/doctor_dashboard/src/App.jsx) (Dashboard App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_patient["Patient Kiosk"]
  node_kiosk["Kiosk App<br/>[App.jsx]"]
  node_mirror["Camera Mirror<br/>[Mirror.jsx]"]
  node_vision["Face &amp; Pose Vision<br/>[VisionEngine.js]"]
  node_wake["Wake Detection<br/>[useFaceWakeup.js]"]
  node_gesture["Gesture Cursor"]
  node_audio["Audio I/O<br/>[useAudioIO.js]"]
end

subgraph group_backend["Backend Workflow"]
  node_api["FastAPI &amp; Socket.IO<br/>[main.py]"]
  node_events["Realtime Event Hub<br/>[websocket_hub.py]"]
  node_interview["SOCRATES Interview<br/>[interview_agent.py]"]
  node_speech["Speech Transcription<br/>[speech_client.py]"]
  node_mobile["Mobile Upload<br/>[mobile_routes.py]"]
  node_ocr["Document OCR &amp; Structuring<br/>[ocr_pipeline.py]"]
  node_encounters["Encounter API"]
end

subgraph group_clinical["Clinical Data"]
  node_models["Clinical Models<br/>[models.py]"]
  node_mongo[("MongoDB<br/>[db.py]")]
end

subgraph group_doctor["Doctor Dashboard"]
  node_dashboard["Dashboard App<br/>[App.jsx]"]
  node_queue["Triage Queue<br/>[TriageQueue.jsx]"]
  node_summary["Clinical Summary"]
  node_timeline["Document Timeline"]
end

node_patient(("Patient"))
node_doctor(("Clinician"))
node_groq["Groq Services"]
node_visionapi["Google Vision"]
node_easyocr["EasyOCR"]

node_patient -->|"starts intake"| node_kiosk
node_kiosk -->|"renders"| node_mirror
node_mirror -->|"processes camera"| node_vision
node_kiosk -->|"detects arrival"| node_wake
node_kiosk -->|"uses cursor"| node_gesture
node_kiosk -->|"uses audio"| node_audio
node_kiosk -->|"emits events"| node_events
node_api -->|"hosts"| node_events
node_api -->|"mounts router"| node_mobile
node_api -->|"mounts router"| node_encounters
node_events -->|"transcribes audio"| node_speech
node_events -->|"runs dialogue"| node_interview
node_events -->|"persists encounter"| node_mongo
node_events -->|"creates encounter"| node_models
node_mobile -->|"queues processing"| node_ocr
node_ocr -->|"saves extracted data"| node_mongo
node_ocr -->|"emits result"| node_events
node_ocr -->|"builds document model"| node_models
node_encounters -->|"reads and finalizes"| node_mongo
node_dashboard -->|"renders"| node_queue
node_dashboard -->|"renders"| node_summary
node_dashboard -->|"renders"| node_timeline
node_dashboard -->|"fetches and finalizes"| node_encounters
node_dashboard -->|"joins and listens"| node_events
node_doctor -->|"reviews cases"| node_dashboard
node_speech -->|"transcribes with Whisper"| node_groq
node_ocr -->|"tries OCR first"| node_visionapi
node_ocr -->|"falls back to"| node_easyocr
node_ocr -->|"structures extracted text"| node_groq

click node_kiosk "https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/App.jsx"
click node_mirror "https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/components/Mirror.jsx"
click node_vision "https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/core/VisionEngine.js"
click node_wake "https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/hooks/useFaceWakeup.js"
click node_gesture "https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/hooks/useGestureCursor.js"
click node_audio "https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/hooks/useAudioIO.js"
click node_api "https://github.com/sundaramkasera/medikiosk/blob/main/backend/main.py"
click node_events "https://github.com/sundaramkasera/medikiosk/blob/main/backend/core/websocket_hub.py"
click node_interview "https://github.com/sundaramkasera/medikiosk/blob/main/backend/ai/interview_agent.py"
click node_speech "https://github.com/sundaramkasera/medikiosk/blob/main/backend/ai_engine/speech_client.py"
click node_mobile "https://github.com/sundaramkasera/medikiosk/blob/main/backend/routes/mobile_routes.py"
click node_ocr "https://github.com/sundaramkasera/medikiosk/blob/main/backend/ai_engine/ocr_pipeline.py"
click node_encounters "https://github.com/sundaramkasera/medikiosk/blob/main/backend/routes/encounter_routes.py"
click node_models "https://github.com/sundaramkasera/medikiosk/blob/main/backend/database/models.py"
click node_mongo "https://github.com/sundaramkasera/medikiosk/blob/main/backend/database/db.py"
click node_dashboard "https://github.com/sundaramkasera/medikiosk/blob/main/doctor_dashboard/src/App.jsx"
click node_queue "https://github.com/sundaramkasera/medikiosk/blob/main/doctor_dashboard/src/components/TriageQueue.jsx"
click node_summary "https://github.com/sundaramkasera/medikiosk/blob/main/doctor_dashboard/src/components/ClinicalSummary.jsx"
click node_timeline "https://github.com/sundaramkasera/medikiosk/blob/main/doctor_dashboard/src/components/DocumentTimeline.jsx"

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_kiosk,node_mirror,node_vision,node_wake,node_gesture,node_audio toneBlue
class node_api,node_events,node_interview,node_speech,node_mobile,node_ocr,node_encounters toneAmber
class node_models,node_mongo toneMint
class node_dashboard,node_queue,node_summary,node_timeline toneRose
class node_patient,node_doctor,node_groq,node_visionapi,node_easyocr toneIndigo
```

## Components

### Patient Kiosk

- [Kiosk App](https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/App.jsx): `kiosk_frontend/src/App.jsx`
- [Camera Mirror](https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/components/Mirror.jsx): `kiosk_frontend/src/components/Mirror.jsx`
- [Face & Pose Vision](https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/core/VisionEngine.js): `kiosk_frontend/src/core/VisionEngine.js`
- [Wake Detection](https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/hooks/useFaceWakeup.js): `kiosk_frontend/src/hooks/useFaceWakeup.js`
- [Gesture Cursor](https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/hooks/useGestureCursor.js): `kiosk_frontend/src/hooks/useGestureCursor.js`
- [Audio I/O](https://github.com/sundaramkasera/medikiosk/blob/main/kiosk_frontend/src/hooks/useAudioIO.js): `kiosk_frontend/src/hooks/useAudioIO.js`

### Backend Workflow

- [FastAPI & Socket.IO](https://github.com/sundaramkasera/medikiosk/blob/main/backend/main.py): `backend/main.py`
- [Realtime Event Hub](https://github.com/sundaramkasera/medikiosk/blob/main/backend/core/websocket_hub.py): `backend/core/websocket_hub.py`
- [SOCRATES Interview](https://github.com/sundaramkasera/medikiosk/blob/main/backend/ai/interview_agent.py): `backend/ai/interview_agent.py`
- [Speech Transcription](https://github.com/sundaramkasera/medikiosk/blob/main/backend/ai_engine/speech_client.py): `backend/ai_engine/speech_client.py`
- [Mobile Upload](https://github.com/sundaramkasera/medikiosk/blob/main/backend/routes/mobile_routes.py): `backend/routes/mobile_routes.py`
- [Document OCR & Structuring](https://github.com/sundaramkasera/medikiosk/blob/main/backend/ai_engine/ocr_pipeline.py): `backend/ai_engine/ocr_pipeline.py`
- [Encounter API](https://github.com/sundaramkasera/medikiosk/blob/main/backend/routes/encounter_routes.py): `backend/routes/encounter_routes.py`

### Clinical Data

- [Clinical Models](https://github.com/sundaramkasera/medikiosk/blob/main/backend/database/models.py): `backend/database/models.py`
- [MongoDB](https://github.com/sundaramkasera/medikiosk/blob/main/backend/database/db.py): `backend/database/db.py`

### Doctor Dashboard

- [Dashboard App](https://github.com/sundaramkasera/medikiosk/blob/main/doctor_dashboard/src/App.jsx): `doctor_dashboard/src/App.jsx`
- [Triage Queue](https://github.com/sundaramkasera/medikiosk/blob/main/doctor_dashboard/src/components/TriageQueue.jsx): `doctor_dashboard/src/components/TriageQueue.jsx`
- [Clinical Summary](https://github.com/sundaramkasera/medikiosk/blob/main/doctor_dashboard/src/components/ClinicalSummary.jsx): `doctor_dashboard/src/components/ClinicalSummary.jsx`
- [Document Timeline](https://github.com/sundaramkasera/medikiosk/blob/main/doctor_dashboard/src/components/DocumentTimeline.jsx): `doctor_dashboard/src/components/DocumentTimeline.jsx`

### Other components

- **Patient**
- **Clinician**
- **Groq Services**
- **Google Vision**
- **EasyOCR**

## Connections

- Patient → Kiosk App: starts intake
- Kiosk App → Camera Mirror: renders (evidence: `kiosk_frontend/src/App.jsx`)
- Camera Mirror → Face & Pose Vision: processes camera (evidence: `kiosk_frontend/src/components/Mirror.jsx`)
- Kiosk App → Wake Detection: detects arrival (evidence: `kiosk_frontend/src/App.jsx`)
- Kiosk App → Gesture Cursor: uses cursor (evidence: `kiosk_frontend/src/App.jsx`)
- Kiosk App → Audio I/O: uses audio (evidence: `kiosk_frontend/src/App.jsx`)
- Kiosk App → Realtime Event Hub: emits events (evidence: `kiosk_frontend/src/App.jsx`)
- FastAPI & Socket.IO → Realtime Event Hub: hosts (evidence: `backend/main.py`)
- FastAPI & Socket.IO → Mobile Upload: mounts router (evidence: `backend/main.py`)
- FastAPI & Socket.IO → Encounter API: mounts router (evidence: `backend/main.py`)
- Realtime Event Hub → Speech Transcription: transcribes audio (evidence: `backend/core/websocket_hub.py`)
- Realtime Event Hub → SOCRATES Interview: runs dialogue (evidence: `backend/core/websocket_hub.py`)
- Realtime Event Hub → MongoDB: persists encounter (evidence: `backend/core/websocket_hub.py`)
- Realtime Event Hub → Clinical Models: creates encounter (evidence: `backend/core/websocket_hub.py`)
- Mobile Upload → Document OCR & Structuring: queues processing (evidence: `backend/routes/mobile_routes.py`)
- Document OCR & Structuring → MongoDB: saves extracted data (evidence: `backend/ai_engine/ocr_pipeline.py`)
- Document OCR & Structuring → Realtime Event Hub: emits result (evidence: `backend/ai_engine/ocr_pipeline.py`)
- Document OCR & Structuring → Clinical Models: builds document model (evidence: `backend/ai_engine/ocr_pipeline.py`)
- Encounter API → MongoDB: reads and finalizes (evidence: `backend/routes/encounter_routes.py`)
- Dashboard App → Triage Queue: renders (evidence: `doctor_dashboard/src/App.jsx`)
- Dashboard App → Clinical Summary: renders (evidence: `doctor_dashboard/src/App.jsx`)
- Dashboard App → Document Timeline: renders (evidence: `doctor_dashboard/src/App.jsx`)
- Dashboard App → Encounter API: fetches and finalizes (evidence: `doctor_dashboard/src/App.jsx`)
- Dashboard App → Realtime Event Hub: joins and listens (evidence: `doctor_dashboard/src/App.jsx`)
- Clinician → Dashboard App: reviews cases
- Speech Transcription → Groq Services: transcribes with Whisper (evidence: `backend/ai_engine/speech_client.py`)
- Document OCR & Structuring → Google Vision: tries OCR first (evidence: `backend/ai_engine/ocr_pipeline.py`)
- Document OCR & Structuring → EasyOCR: falls back to (evidence: `backend/ai_engine/ocr_pipeline.py`)
- Document OCR & Structuring → Groq Services: structures extracted text (evidence: `backend/ai_engine/ocr_pipeline.py`)
