# nathanblatter/ai-therapist architecture

> Architecture diagram of the GitHub repository nathanblatter/ai-therapist, 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/nathanblatter/ai-therapist
- Repository: https://github.com/nathanblatter/ai-therapist

## Overview

AI Therapist is a voice-based therapy research application with a participant experience and a therapist/researcher dashboard. Participants begin a session, converse by live voice or chat, and receive safety checks; staff monitor sessions and manage follow-up. The graph also shows the caseworker workflow, transcript redaction and recording, and evaluation capabilities. Relationships are limited to the README and the shown source references/calls; several subsystem connections are omitted or marked unverified because their implementation was not sampled.

Main entry points: [`src/server/routes/public/chat.routes.ts`](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/routes/public/chat.routes.ts) (Chat API), [`src/server/routes/admin/sessions.routes.ts`](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/routes/admin/sessions.routes.ts) (Session operations), [`src/server/config/db.ts`](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/config/db.ts) (PostgreSQL), [`src/server/services/crisisPipeline.service.ts`](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/crisisPipeline.service.ts) (Crisis pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_participant["Participant experience"]
  node_main_ui["Therapy interface<br/>[App.tsx]"]
  node_voice_client["Grok voice client<br/>[grokVoiceClient.ts]"]
end

subgraph group_runtime["Session runtime"]
  node_chat_api["Chat API<br/>[chat.routes.ts]"]
  node_session_api["Session API<br/>[sessions.routes.ts]"]
  node_sideband["Live sideband"]
  node_chat_therapy["Chat therapy"]
  node_session_limits["Session limits<br/>[sessionHelpers.ts]"]
end

subgraph group_safety["Safety and care"]
  node_crisis_pipeline["Crisis pipeline"]
  node_crisis_detection["Risk detection"]
  node_crisis_response["Graduated response"]
  node_redaction["PHI redaction"]
end

subgraph group_staff["Staff operations"]
  node_admin_ui["Staff dashboard<br/>[AdminApp.tsx]"]
  node_admin_sessions["Session operations<br/>[sessions.routes.ts]"]
  node_escalations["Escalation handling"]
  node_work_queue["Care work queue"]
  node_role_model["Role and data tiers<br/>[roles.ts]"]
end

subgraph group_research["Research and evaluation"]
  node_redteam["Red-team harness<br/>[voiceClient.ts]"]
  node_evals["Session evaluation"]
end

node_participant(("Participant"))
node_database[("PostgreSQL<br/>[db.ts]")]
node_object_storage[("Object storage<br/>[objectStorage.ts]")]
node_openai{{"OpenAI Realtime"}}

node_participant -->|"uses"| node_main_ui
node_main_ui -.->|"sends chat"| node_chat_api
node_main_ui -->|"uses voice"| node_voice_client
node_voice_client -.->|"streams audio"| node_openai
node_chat_api -->|"checks limits"| node_session_limits
node_chat_api -->|"creates session"| node_database
node_chat_api -->|"invokes"| node_chat_therapy
node_chat_api -->|"runs safety"| node_crisis_pipeline
node_crisis_pipeline -->|"reads state"| node_database
node_crisis_pipeline -->|"analyzes risk"| node_crisis_detection
node_crisis_pipeline -->|"executes response"| node_crisis_response
node_session_api -->|"attaches"| node_sideband
node_session_api -->|"redacts session"| node_redaction
node_sideband -->|"persists turns"| node_database
node_admin_ui -.->|"manages sessions"| node_admin_sessions
node_admin_sessions -->|"reads session data"| node_database
node_admin_sessions -->|"controls live sessions"| node_sideband
node_admin_sessions -->|"requests redaction"| node_redaction
node_admin_sessions -->|"loads recordings"| node_object_storage
node_escalations -->|"enqueues work"| node_work_queue
node_work_queue -.->|"stores work items"| node_database
node_role_model -.->|"defines access tiers"| node_admin_ui
node_redteam -->|"drives voice tests"| node_openai
node_redteam -->|"uses eval dimensions"| node_evals

click node_main_ui "https://github.com/nathanblatter/ai-therapist/blob/main/src/client/main/components/App.tsx"
click node_voice_client "https://github.com/nathanblatter/ai-therapist/blob/main/src/client/main/lib/grokVoiceClient.ts"
click node_chat_api "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/routes/public/chat.routes.ts"
click node_session_api "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/routes/public/sessions.routes.ts"
click node_sideband "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/sidebandManager.service.ts"
click node_chat_therapy "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/chatTherapy.service.ts"
click node_session_limits "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/utils/sessionHelpers.ts"
click node_crisis_pipeline "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/crisisPipeline.service.ts"
click node_crisis_detection "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/crisisDetection.service.ts"
click node_crisis_response "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/crisisIntervention.service.ts"
click node_redaction "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/sessionRedaction.service.ts"
click node_admin_ui "https://github.com/nathanblatter/ai-therapist/blob/main/src/client/admin/components/AdminApp.tsx"
click node_admin_sessions "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/routes/admin/sessions.routes.ts"
click node_escalations "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/routes/admin/escalations.routes.ts"
click node_work_queue "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/workQueue.service.ts"
click node_role_model "https://github.com/nathanblatter/ai-therapist/blob/main/src/shared/roles.ts"
click node_database "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/config/db.ts"
click node_object_storage "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/config/objectStorage.ts"
click node_redteam "https://github.com/nathanblatter/ai-therapist/blob/main/src/redteam/voiceClient.ts"
click node_evals "https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/sessionEval.service.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_main_ui,node_voice_client toneBlue
class node_chat_api,node_session_api,node_sideband,node_chat_therapy,node_session_limits,node_database,node_object_storage toneAmber
class node_crisis_pipeline,node_crisis_detection,node_crisis_response,node_redaction toneMint
class node_admin_ui,node_admin_sessions,node_escalations,node_work_queue,node_role_model toneRose
class node_redteam,node_evals,node_participant,node_openai toneIndigo
```

## Components

### Participant experience

- [Therapy interface](https://github.com/nathanblatter/ai-therapist/blob/main/src/client/main/components/App.tsx): `src/client/main/components/App.tsx`
- [Grok voice client](https://github.com/nathanblatter/ai-therapist/blob/main/src/client/main/lib/grokVoiceClient.ts): `src/client/main/lib/grokVoiceClient.ts`

### Session runtime

- [Chat API](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/routes/public/chat.routes.ts): `src/server/routes/public/chat.routes.ts`
- [Session API](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/routes/public/sessions.routes.ts): `src/server/routes/public/sessions.routes.ts`
- [Live sideband](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/sidebandManager.service.ts): `src/server/services/sidebandManager.service.ts`
- [Chat therapy](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/chatTherapy.service.ts): `src/server/services/chatTherapy.service.ts`
- [Session limits](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/utils/sessionHelpers.ts): `src/server/utils/sessionHelpers.ts`

### Safety and care

- [Crisis pipeline](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/crisisPipeline.service.ts): `src/server/services/crisisPipeline.service.ts`
- [Risk detection](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/crisisDetection.service.ts): `src/server/services/crisisDetection.service.ts`
- [Graduated response](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/crisisIntervention.service.ts): `src/server/services/crisisIntervention.service.ts`
- [PHI redaction](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/sessionRedaction.service.ts): `src/server/services/sessionRedaction.service.ts`

### Staff operations

- [Staff dashboard](https://github.com/nathanblatter/ai-therapist/blob/main/src/client/admin/components/AdminApp.tsx): `src/client/admin/components/AdminApp.tsx`
- [Session operations](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/routes/admin/sessions.routes.ts): `src/server/routes/admin/sessions.routes.ts`
- [Escalation handling](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/routes/admin/escalations.routes.ts): `src/server/routes/admin/escalations.routes.ts`
- [Care work queue](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/workQueue.service.ts): `src/server/services/workQueue.service.ts`
- [Role and data tiers](https://github.com/nathanblatter/ai-therapist/blob/main/src/shared/roles.ts): `src/shared/roles.ts`

### Research and evaluation

- [Red-team harness](https://github.com/nathanblatter/ai-therapist/blob/main/src/redteam/voiceClient.ts): `src/redteam/voiceClient.ts`
- [Session evaluation](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/services/sessionEval.service.ts): `src/server/services/sessionEval.service.ts`

### Other components

- **Participant**
- [PostgreSQL](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/config/db.ts): `src/server/config/db.ts`
- [Object storage](https://github.com/nathanblatter/ai-therapist/blob/main/src/server/config/objectStorage.ts): `src/server/config/objectStorage.ts`
- **OpenAI Realtime**

## Connections

- Participant → Therapy interface: uses (evidence: `README.md`)
- Therapy interface → Chat API: sends chat
- Therapy interface → Grok voice client: uses voice (evidence: `src/client/main/components/App.tsx`)
- Grok voice client → OpenAI Realtime: streams audio
- Chat API → Session limits: checks limits (evidence: `src/server/routes/public/chat.routes.ts`)
- Chat API → PostgreSQL: creates session (evidence: `src/server/routes/public/chat.routes.ts`)
- Chat API → Chat therapy: invokes (evidence: `src/server/routes/public/chat.routes.ts`)
- Chat API → Crisis pipeline: runs safety (evidence: `src/server/routes/public/chat.routes.ts`)
- Crisis pipeline → PostgreSQL: reads state (evidence: `src/server/services/crisisPipeline.service.ts`)
- Crisis pipeline → Risk detection: analyzes risk (evidence: `src/server/services/crisisPipeline.service.ts`)
- Crisis pipeline → Graduated response: executes response (evidence: `src/server/services/crisisPipeline.service.ts`)
- Session API → Live sideband: attaches (evidence: `src/server/routes/public/sessions.routes.ts`)
- Session API → PHI redaction: redacts session (evidence: `src/server/routes/public/sessions.routes.ts`)
- Live sideband → PostgreSQL: persists turns (evidence: `src/server/services/sidebandManager.service.ts`)
- Staff dashboard → Session operations: manages sessions
- Session operations → PostgreSQL: reads session data (evidence: `src/server/routes/admin/sessions.routes.ts`)
- Session operations → Live sideband: controls live sessions (evidence: `src/server/routes/admin/sessions.routes.ts`)
- Session operations → PHI redaction: requests redaction (evidence: `src/server/routes/admin/sessions.routes.ts`)
- Session operations → Object storage: loads recordings (evidence: `src/server/routes/admin/sessions.routes.ts`)
- Escalation handling → Care work queue: enqueues work (evidence: `src/server/routes/admin/escalations.routes.ts`)
- Care work queue → PostgreSQL: stores work items (evidence: `src/server/services/workQueue.service.ts`)
- Role and data tiers → Staff dashboard: defines access tiers
- Red-team harness → OpenAI Realtime: drives voice tests (evidence: `src/redteam/voiceClient.ts`)
- Red-team harness → Session evaluation: uses eval dimensions