# bisman-singh/twiceheard architecture

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

- Interactive diagram: https://gitdiagram.com/bisman-singh/twiceheard
- Repository: https://github.com/bisman-singh/twiceheard

## Overview

Twiceheard is a clinic phone and browser voice-intake product. Its main workflow captures and reads back patient details, offers and books appointments, then reconstructs and checks the chart after the call before presenting it to clinic staff. The graph also includes the clinic desk, privacy controls, and the voice-platform integration. Relationships for unsampled modules are included only where the README or SOURCE INDEX supports them; source details beyond the supplied excerpts were not inspected.

Main entry points: [`lib/tools/handlers.ts`](https://github.com/bisman-singh/twiceheard/blob/main/lib/tools/handlers.ts) (Intake tool handlers), [`lib/postcall/process.ts`](https://github.com/bisman-singh/twiceheard/blob/main/lib/postcall/process.ts) (Post-call processing), [`lib/postcall/record.ts`](https://github.com/bisman-singh/twiceheard/blob/main/lib/postcall/record.ts) (Call records), [`lib/server/deps.ts`](https://github.com/bisman-singh/twiceheard/blob/main/lib/server/deps.ts) (Server dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_calling["Calling"]
  node_call_ui["Browser call UI<br/>[call-panel.tsx]"]
  node_browser_session["Browser call session<br/>[session-client.ts]"]
  node_voice_session_api["Session API<br/>[route.ts]"]
  node_voice_platform{{"AssemblyAI voice platform"}}
  node_tool_relay["Tool relay<br/>[route.ts]"]
  node_phone_tools["Phone tool endpoint<br/>[route.ts]"]
end

subgraph group_intake["Intake and booking"]
  node_tool_handlers["Intake tool handlers<br/>[handlers.ts]"]
  node_intake_chart["Intake chart<br/>[chart.ts]"]
  node_field_rules["Field normalization<br/>[fields.ts]"]
  node_appointment_slots["Appointment slots<br/>[slots.ts]"]
  node_medication_lookup["Medication lookup<br/>[rxnorm.ts]"]
end

subgraph group_postcall["Post-call verification"]
  node_result_api["Call result API<br/>[route.ts]"]
  node_postcall_process["Post-call processing<br/>[process.ts]"]
  node_timeline_replay["Timeline replay<br/>[replay.ts]"]
  node_second_hearing["Recording verification<br/>[hearing.ts]"]
  node_grade["Chart grading<br/>[grade.ts]"]
end

subgraph group_desk["Clinic desk"]
  node_desk_pages["Clinic desk pages<br/>[page.tsx]"]
  node_call_detail["Call detail page<br/>[page.tsx]"]
  node_forget_api["Forget call API<br/>[route.ts]"]
end

subgraph group_platform["Platform and services"]
  node_intake_store[("Intake store<br/>[store.ts]")]
  node_transcription{{"AssemblyAI transcription<br/>[transcribe.ts]"}}
  node_call_records[("Call records<br/>[record.ts]")]
  node_clinic_config["Clinic configuration<br/>[config.ts]"]
  node_dependency_factory["Server dependencies<br/>[deps.ts]"]
  node_redis_store[("Redis stores<br/>[redis.ts]")]
  node_sms{{"SMS messenger<br/>[sms.ts]"}}
end

node_caller(("Caller"))
node_clinic_staff(("Clinic staff"))

node_caller -->|"starts call"| node_call_ui
node_call_ui -->|"starts session"| node_browser_session
node_browser_session -->|"streams audio"| node_voice_platform
node_voice_session_api -->|"mints token"| node_voice_platform
node_voice_platform -->|"requests tools"| node_tool_relay
node_voice_platform -->|"calls tools"| node_phone_tools
node_tool_relay -->|"dispatches tools"| node_tool_handlers
node_phone_tools -->|"dispatches tools"| node_tool_handlers
node_tool_handlers -->|"saves fields"| node_intake_chart
node_intake_chart -->|"normalizes values"| node_field_rules
node_tool_handlers -->|"loads and saves"| node_intake_store
node_tool_handlers -->|"offers slots"| node_appointment_slots
node_tool_handlers -->|"checks medication"| node_medication_lookup
node_tool_handlers -->|"uses clinic details"| node_clinic_config
node_caller -->|"requests chart"| node_result_api
node_result_api -->|"processes session"| node_postcall_process
node_postcall_process -->|"replays timeline"| node_timeline_replay
node_postcall_process -->|"checks recording"| node_second_hearing
node_second_hearing -->|"transcribes audio"| node_transcription
node_postcall_process -->|"grades chart"| node_grade
node_postcall_process -->|"stores result"| node_call_records
node_clinic_staff -->|"opens desk"| node_desk_pages
node_desk_pages -->|"lists calls"| node_call_records
node_desk_pages -->|"opens chart"| node_call_detail
node_clinic_staff -->|"requests erasure"| node_forget_api
node_forget_api -->|"removes record"| node_call_records
node_dependency_factory -->|"configures store"| node_intake_store
node_dependency_factory -->|"configures store"| node_call_records
node_dependency_factory -->|"selects Redis"| node_redis_store
node_tool_handlers -.->|"sends confirmation"| node_sms

click node_call_ui "https://github.com/bisman-singh/twiceheard/blob/main/components/call/call-panel.tsx"
click node_browser_session "https://github.com/bisman-singh/twiceheard/blob/main/lib/call/session-client.ts"
click node_voice_session_api "https://github.com/bisman-singh/twiceheard/blob/main/app/api/voice/session/route.ts"
click node_tool_relay "https://github.com/bisman-singh/twiceheard/blob/main/app/api/voice/tool/route.ts"
click node_phone_tools "https://github.com/bisman-singh/twiceheard/blob/main/app/api/tools/%5BclinicId%5D/%5Btool%5D/route.ts"
click node_tool_handlers "https://github.com/bisman-singh/twiceheard/blob/main/lib/tools/handlers.ts"
click node_intake_chart "https://github.com/bisman-singh/twiceheard/blob/main/lib/intake/chart.ts"
click node_field_rules "https://github.com/bisman-singh/twiceheard/blob/main/lib/intake/fields.ts"
click node_appointment_slots "https://github.com/bisman-singh/twiceheard/blob/main/lib/scheduling/slots.ts"
click node_medication_lookup "https://github.com/bisman-singh/twiceheard/blob/main/lib/medication/rxnorm.ts"
click node_intake_store "https://github.com/bisman-singh/twiceheard/blob/main/lib/intake/store.ts"
click node_result_api "https://github.com/bisman-singh/twiceheard/blob/main/app/api/call/result/route.ts"
click node_postcall_process "https://github.com/bisman-singh/twiceheard/blob/main/lib/postcall/process.ts"
click node_timeline_replay "https://github.com/bisman-singh/twiceheard/blob/main/lib/postcall/replay.ts"
click node_second_hearing "https://github.com/bisman-singh/twiceheard/blob/main/lib/verify/hearing.ts"
click node_transcription "https://github.com/bisman-singh/twiceheard/blob/main/lib/verify/transcribe.ts"
click node_grade "https://github.com/bisman-singh/twiceheard/blob/main/lib/intake/grade.ts"
click node_call_records "https://github.com/bisman-singh/twiceheard/blob/main/lib/postcall/record.ts"
click node_desk_pages "https://github.com/bisman-singh/twiceheard/blob/main/app/desk/page.tsx"
click node_call_detail "https://github.com/bisman-singh/twiceheard/blob/main/app/desk/calls/%5BsessionId%5D/page.tsx"
click node_forget_api "https://github.com/bisman-singh/twiceheard/blob/main/app/api/call/forget/route.ts"
click node_clinic_config "https://github.com/bisman-singh/twiceheard/blob/main/lib/clinic/config.ts"
click node_dependency_factory "https://github.com/bisman-singh/twiceheard/blob/main/lib/server/deps.ts"
click node_redis_store "https://github.com/bisman-singh/twiceheard/blob/main/lib/store/redis.ts"
click node_sms "https://github.com/bisman-singh/twiceheard/blob/main/lib/notify/sms.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_call_ui,node_browser_session,node_voice_session_api,node_voice_platform,node_tool_relay,node_phone_tools toneBlue
class node_tool_handlers,node_intake_chart,node_field_rules,node_appointment_slots,node_medication_lookup toneAmber
class node_result_api,node_postcall_process,node_timeline_replay,node_second_hearing,node_grade toneMint
class node_desk_pages,node_call_detail,node_forget_api toneRose
class node_intake_store,node_transcription,node_call_records,node_clinic_config,node_dependency_factory,node_redis_store,node_sms,node_caller,node_clinic_staff toneIndigo
```

## Components

### Calling

- [Browser call UI](https://github.com/bisman-singh/twiceheard/blob/main/components/call/call-panel.tsx): `components/call/call-panel.tsx`
- [Browser call session](https://github.com/bisman-singh/twiceheard/blob/main/lib/call/session-client.ts): `lib/call/session-client.ts`
- [Session API](https://github.com/bisman-singh/twiceheard/blob/main/app/api/voice/session/route.ts): `app/api/voice/session/route.ts`
- **AssemblyAI voice platform**
- [Tool relay](https://github.com/bisman-singh/twiceheard/blob/main/app/api/voice/tool/route.ts): `app/api/voice/tool/route.ts`
- [Phone tool endpoint](https://github.com/bisman-singh/twiceheard/blob/main/app/api/tools/%5BclinicId%5D/%5Btool%5D/route.ts): `app/api/tools/[clinicId]/[tool]/route.ts`

### Intake and booking

- [Intake tool handlers](https://github.com/bisman-singh/twiceheard/blob/main/lib/tools/handlers.ts): `lib/tools/handlers.ts`
- [Intake chart](https://github.com/bisman-singh/twiceheard/blob/main/lib/intake/chart.ts): `lib/intake/chart.ts`
- [Field normalization](https://github.com/bisman-singh/twiceheard/blob/main/lib/intake/fields.ts): `lib/intake/fields.ts`
- [Appointment slots](https://github.com/bisman-singh/twiceheard/blob/main/lib/scheduling/slots.ts): `lib/scheduling/slots.ts`
- [Medication lookup](https://github.com/bisman-singh/twiceheard/blob/main/lib/medication/rxnorm.ts): `lib/medication/rxnorm.ts`

### Post-call verification

- [Call result API](https://github.com/bisman-singh/twiceheard/blob/main/app/api/call/result/route.ts): `app/api/call/result/route.ts`
- [Post-call processing](https://github.com/bisman-singh/twiceheard/blob/main/lib/postcall/process.ts): `lib/postcall/process.ts`
- [Timeline replay](https://github.com/bisman-singh/twiceheard/blob/main/lib/postcall/replay.ts): `lib/postcall/replay.ts`
- [Recording verification](https://github.com/bisman-singh/twiceheard/blob/main/lib/verify/hearing.ts): `lib/verify/hearing.ts`
- [Chart grading](https://github.com/bisman-singh/twiceheard/blob/main/lib/intake/grade.ts): `lib/intake/grade.ts`

### Clinic desk

- [Clinic desk pages](https://github.com/bisman-singh/twiceheard/blob/main/app/desk/page.tsx): `app/desk/page.tsx`
- [Call detail page](https://github.com/bisman-singh/twiceheard/blob/main/app/desk/calls/%5BsessionId%5D/page.tsx): `app/desk/calls/[sessionId]/page.tsx`
- [Forget call API](https://github.com/bisman-singh/twiceheard/blob/main/app/api/call/forget/route.ts): `app/api/call/forget/route.ts`

### Platform and services

- [Intake store](https://github.com/bisman-singh/twiceheard/blob/main/lib/intake/store.ts): `lib/intake/store.ts`
- [AssemblyAI transcription](https://github.com/bisman-singh/twiceheard/blob/main/lib/verify/transcribe.ts): `lib/verify/transcribe.ts`
- [Call records](https://github.com/bisman-singh/twiceheard/blob/main/lib/postcall/record.ts): `lib/postcall/record.ts`
- [Clinic configuration](https://github.com/bisman-singh/twiceheard/blob/main/lib/clinic/config.ts): `lib/clinic/config.ts`
- [Server dependencies](https://github.com/bisman-singh/twiceheard/blob/main/lib/server/deps.ts): `lib/server/deps.ts`
- [Redis stores](https://github.com/bisman-singh/twiceheard/blob/main/lib/store/redis.ts): `lib/store/redis.ts`
- [SMS messenger](https://github.com/bisman-singh/twiceheard/blob/main/lib/notify/sms.ts): `lib/notify/sms.ts`

### Other components

- **Caller**
- **Clinic staff**

## Connections

- Caller → Browser call UI: starts call
- Browser call UI → Browser call session: starts session (evidence: `components/call/call-panel.tsx`)
- Browser call session → AssemblyAI voice platform: streams audio (evidence: `lib/call/session-client.ts`)
- Session API → AssemblyAI voice platform: mints token (evidence: `app/api/voice/session/route.ts`)
- AssemblyAI voice platform → Tool relay: requests tools
- AssemblyAI voice platform → Phone tool endpoint: calls tools
- Tool relay → Intake tool handlers: dispatches tools (evidence: `app/api/voice/tool/route.ts`)
- Phone tool endpoint → Intake tool handlers: dispatches tools (evidence: `app/api/tools/[clinicId]/[tool]/route.ts`)
- Intake tool handlers → Intake chart: saves fields (evidence: `lib/tools/handlers.ts`)
- Intake chart → Field normalization: normalizes values (evidence: `lib/intake/chart.ts`)
- Intake tool handlers → Intake store: loads and saves (evidence: `lib/tools/handlers.ts`)
- Intake tool handlers → Appointment slots: offers slots (evidence: `lib/tools/handlers.ts`)
- Intake tool handlers → Medication lookup: checks medication (evidence: `lib/tools/handlers.ts`)
- Intake tool handlers → Clinic configuration: uses clinic details (evidence: `lib/tools/handlers.ts`)
- Caller → Call result API: requests chart
- Call result API → Post-call processing: processes session (evidence: `app/api/call/result/route.ts`)
- Post-call processing → Timeline replay: replays timeline
- Post-call processing → Recording verification: checks recording
- Recording verification → AssemblyAI transcription: transcribes audio
- Post-call processing → Chart grading: grades chart
- Post-call processing → Call records: stores result (evidence: `app/api/call/result/route.ts`)
- Clinic staff → Clinic desk pages: opens desk
- Clinic desk pages → Call records: lists calls (evidence: `app/desk/page.tsx`)
- Clinic desk pages → Call detail page: opens chart (evidence: `app/desk/calls/[sessionId]/page.tsx`)
- Clinic staff → Forget call API: requests erasure
- Forget call API → Call records: removes record (evidence: `app/api/call/forget/route.ts`)
- Server dependencies → Intake store: configures store (evidence: `lib/server/deps.ts`)
- Server dependencies → Call records: configures store (evidence: `lib/server/deps.ts`)
- Server dependencies → Redis stores: selects Redis (evidence: `lib/server/deps.ts`)
- Intake tool handlers → SMS messenger: sends confirmation (evidence: `lib/tools/handlers.ts`)
