# sai-koushik-vimmadisetty/ai-confessor architecture

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

- Interactive diagram: https://gitdiagram.com/sai-koushik-vimmadisetty/ai-confessor
- Repository: https://github.com/sai-koushik-vimmadisetty/ai-confessor

## Overview

AI Confessor is a real-time voice-and-text conversational app. A user speaks or types in the browser; the frontend streams microphone audio or text to FastAPI over WebSocket. The backend transcribes audio when needed, manages per-connection conversation history, streams a response from the selected language-model provider, and optionally synthesizes speech. The browser displays streamed text and plays returned audio, with browser speech synthesis as a fallback. The README documents these capabilities; unsampled configuration and proxy behavior are represented only where their paths and roles are documented.

Main entry points: [`backend/app/main.py`](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/main.py) (FastAPI and turn handler), [`frontend/src/components/ChatWindow.tsx`](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/src/components/ChatWindow.tsx) (Chat interface), [`frontend/src/lib/ws.ts`](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/src/lib/ws.ts) (WebSocket client), [`frontend/src/lib/audio.ts`](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/src/lib/audio.ts) (Audio capture and playback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser experience"]
  node_ui_entry["React entry<br/>[main.tsx]"]
  node_chat_ui["Chat interface<br/>[ChatWindow.tsx]"]
  node_ws_client["WebSocket client<br/>[ws.ts]"]
  node_audio_client["Audio capture and playback<br/>[audio.ts]"]
  node_pcm_worklet["PCM worklet<br/>[pcm-processor.js]"]
  node_proxy["HTTP and WS proxy<br/>[nginx.conf]"]
end

subgraph group_backend["Conversation backend"]
  node_api["FastAPI and turn handler<br/>[main.py]"]
  node_config["Runtime settings<br/>[config.py]"]
  node_stt["Vosk transcription<br/>[stt.py]"]
end

subgraph group_state["Session state"]
  node_session_manager["Session manager<br/>[sessions.py]"]
  node_session["Conversation session<br/>[sessions.py]"]
end

subgraph group_providers["AI services"]
  node_llm["LLM provider adapter<br/>[llm.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
end

node_user(("User"))
node_browser["Browser APIs"]
node_edge_tts_service["Edge TTS"]
node_anthropic_service["Anthropic API"]
node_openai_service["OpenAI API"]
node_browser_speech["Browser speech synthesis"]

node_user -->|"types or speaks"| node_chat_ui
node_ui_entry -->|"renders"| node_chat_ui
node_chat_ui -->|"sends turns"| node_ws_client
node_chat_ui -->|"starts capture and playback"| node_audio_client
node_audio_client -->|"captures and plays"| node_browser
node_audio_client -->|"loads processor"| node_pcm_worklet
node_chat_ui -->|"fetches config"| node_ws_client
node_ws_client -->|"sends HTTP and WS"| node_proxy
node_proxy -->|"proxies requests"| node_api
node_api -->|"sends protocol events"| node_ws_client
node_ws_client -->|"delivers events"| node_chat_ui
node_chat_ui -.->|"speaks fallback text"| node_browser_speech
node_api -->|"reads settings"| node_config
node_api -->|"creates and removes sessions"| node_session_manager
node_session_manager -->|"creates session"| node_session
node_api -->|"reads and updates history"| node_session
node_session -->|"returns history"| node_api
node_api -->|"feeds audio and flushes transcript"| node_stt
node_api -->|"streams conversation reply"| node_llm
node_llm -.->|"streams completion"| node_anthropic_service
node_llm -.->|"streams completion"| node_openai_service
node_api -.->|"synthesizes reply"| node_tts
node_tts -->|"requests audio"| node_edge_tts_service
node_api -->|"sends transcript, tokens, and audio"| node_ws_client

click node_ui_entry "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/src/main.tsx"
click node_chat_ui "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/src/components/ChatWindow.tsx"
click node_ws_client "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/src/lib/ws.ts"
click node_audio_client "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/src/lib/audio.ts"
click node_pcm_worklet "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/public/pcm-processor.js"
click node_proxy "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/nginx.conf"
click node_api "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/main.py"
click node_config "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/config.py"
click node_stt "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/stt.py"
click node_llm "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/llm.py"
click node_tts "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/tts.py"
click node_session_manager "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/sessions.py"
click node_session "https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/sessions.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_ui_entry,node_chat_ui,node_ws_client,node_audio_client,node_pcm_worklet,node_proxy,node_user,node_browser,node_browser_speech toneBlue
class node_api,node_config,node_stt toneAmber
class node_session_manager,node_session,node_anthropic_service,node_openai_service toneMint
class node_llm,node_tts toneRose
class node_edge_tts_service toneIndigo
```

## Components

### Browser experience

- [React entry](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Chat interface](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/src/components/ChatWindow.tsx): `frontend/src/components/ChatWindow.tsx`
- [WebSocket client](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/src/lib/ws.ts): `frontend/src/lib/ws.ts`
- [Audio capture and playback](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/src/lib/audio.ts): `frontend/src/lib/audio.ts`
- [PCM worklet](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/public/pcm-processor.js): `frontend/public/pcm-processor.js`
- [HTTP and WS proxy](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/frontend/nginx.conf): `frontend/nginx.conf`

### Conversation backend

- [FastAPI and turn handler](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/main.py): `backend/app/main.py`
- [Runtime settings](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/config.py): `backend/app/config.py`
- [Vosk transcription](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/stt.py): `backend/app/stt.py`

### Session state

- [Session manager](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/sessions.py): `backend/app/sessions.py`
- [Conversation session](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/sessions.py): `backend/app/sessions.py`

### AI services

- [LLM provider adapter](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/llm.py): `backend/app/llm.py`
- [Speech synthesis](https://github.com/sai-koushik-vimmadisetty/ai-confessor/blob/main/backend/app/tts.py): `backend/app/tts.py`

### Other components

- **User**
- **Browser APIs**
- **Edge TTS**
- **Anthropic API**
- **OpenAI API**
- **Browser speech synthesis**

## Connections

- User → Chat interface: types or speaks
- React entry → Chat interface: renders
- Chat interface → WebSocket client: sends turns
- Chat interface → Audio capture and playback: starts capture and playback
- Audio capture and playback → Browser APIs: captures and plays
- Audio capture and playback → PCM worklet: loads processor
- Chat interface → WebSocket client: fetches config
- WebSocket client → HTTP and WS proxy: sends HTTP and WS
- HTTP and WS proxy → FastAPI and turn handler: proxies requests
- FastAPI and turn handler → WebSocket client: sends protocol events
- WebSocket client → Chat interface: delivers events
- Chat interface → Browser speech synthesis: speaks fallback text
- FastAPI and turn handler → Runtime settings: reads settings
- FastAPI and turn handler → Session manager: creates and removes sessions
- Session manager → Conversation session: creates session
- FastAPI and turn handler → Conversation session: reads and updates history
- Conversation session → FastAPI and turn handler: returns history
- FastAPI and turn handler → Vosk transcription: feeds audio and flushes transcript
- FastAPI and turn handler → LLM provider adapter: streams conversation reply
- LLM provider adapter → Anthropic API: streams completion
- LLM provider adapter → OpenAI API: streams completion
- FastAPI and turn handler → Speech synthesis: synthesizes reply
- Speech synthesis → Edge TTS: requests audio
- FastAPI and turn handler → WebSocket client: sends transcript, tokens, and audio