# codesbysaravana/nephele_production architecture

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

- Interactive diagram: https://gitdiagram.com/codesbysaravana/nephele_production
- Repository: https://github.com/codesbysaravana/nephele_production

## Overview

Nephele is a real-time voice companion for college placement preparation. A student starts a conversation in the frontend, which captures microphone audio and streams it to the backend; the backend transcribes speech, generates a streamed answer, synthesizes speech, and returns transcript/audio events for display and playback. The graph includes the documented provider stages and health endpoint. Provider orchestration details are partly documented in the README; unsampled frontend entry-point wiring is included only where documented.

Main entry points: [`backend/routes/voice_routes.py`](https://github.com/codesbysaravana/nephele_production/blob/main/backend/routes/voice_routes.py) (Voice WebSocket), [`frontend/src/audio/VoiceSession.ts`](https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/audio/VoiceSession.ts) (Voice session), [`frontend/src/components/VoiceOverlay.tsx`](https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/components/VoiceOverlay.tsx) (Voice overlay), [`backend/main.py`](https://github.com/codesbysaravana/nephele_production/blob/main/backend/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Voice frontend"]
  node_app["React app<br/>[App.tsx]"]
  node_overlay["Voice overlay<br/>[VoiceOverlay.tsx]"]
  node_session["Voice session<br/>[VoiceSession.ts]"]
  node_url_config["Voice URL config<br/>[config.ts]"]
  node_pcm_worklet["PCM capture worklet<br/>[pcm-processor.js]"]
  node_playback["Audio playback<br/>[Playback.ts]"]
end

subgraph group_backend["Voice backend"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_voice_route["Voice WebSocket<br/>[voice_routes.py]"]
  node_health["Health endpoint<br/>[main.py]"]
end

subgraph group_providers["AI providers"]
  node_stt["AssemblyAI STT"]
  node_llm["OpenAI LLM"]
  node_tts["Deepgram TTS"]
end

node_student(("Student"))

node_student -->|"starts conversation"| node_overlay
node_app -->|"renders"| node_overlay
node_overlay -->|"starts session"| node_session
node_session -->|"resolves URL"| node_url_config
node_session -->|"loads capture"| node_pcm_worklet
node_session -->|"plays audio"| node_playback
node_session -->|"streams audio and receives events"| node_voice_route
node_api_app -->|"registers router"| node_voice_route
node_voice_route -->|"forwards audio"| node_stt
node_stt -->|"returns transcript"| node_voice_route
node_voice_route -->|"sends transcript and history"| node_llm
node_llm -->|"streams tokens"| node_voice_route
node_voice_route -->|"sends sentences"| node_tts
node_tts -->|"returns audio"| node_voice_route
node_voice_route -->|"streams audio and transcript events"| node_session
node_api_app -->|"serves"| node_health

click node_app "https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/App.tsx"
click node_overlay "https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/components/VoiceOverlay.tsx"
click node_session "https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/audio/VoiceSession.ts"
click node_url_config "https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/config.ts"
click node_pcm_worklet "https://github.com/codesbysaravana/nephele_production/blob/main/frontend/public/pcm-processor.js"
click node_playback "https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/audio/Playback.ts"
click node_api_app "https://github.com/codesbysaravana/nephele_production/blob/main/backend/main.py"
click node_voice_route "https://github.com/codesbysaravana/nephele_production/blob/main/backend/routes/voice_routes.py"
click node_health "https://github.com/codesbysaravana/nephele_production/blob/main/backend/main.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_app,node_overlay,node_session,node_url_config,node_pcm_worklet,node_playback toneBlue
class node_api_app,node_voice_route,node_health toneAmber
class node_stt,node_llm,node_tts toneMint
class node_student toneIndigo
```

## Components

### Voice frontend

- [React app](https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Voice overlay](https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/components/VoiceOverlay.tsx): `frontend/src/components/VoiceOverlay.tsx`
- [Voice session](https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/audio/VoiceSession.ts): `frontend/src/audio/VoiceSession.ts`
- [Voice URL config](https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/config.ts): `frontend/src/config.ts`
- [PCM capture worklet](https://github.com/codesbysaravana/nephele_production/blob/main/frontend/public/pcm-processor.js): `frontend/public/pcm-processor.js`
- [Audio playback](https://github.com/codesbysaravana/nephele_production/blob/main/frontend/src/audio/Playback.ts): `frontend/src/audio/Playback.ts`

### Voice backend

- [FastAPI app](https://github.com/codesbysaravana/nephele_production/blob/main/backend/main.py): `backend/main.py`
- [Voice WebSocket](https://github.com/codesbysaravana/nephele_production/blob/main/backend/routes/voice_routes.py): `backend/routes/voice_routes.py`
- [Health endpoint](https://github.com/codesbysaravana/nephele_production/blob/main/backend/main.py): `backend/main.py`

### AI providers

- **AssemblyAI STT**
- **OpenAI LLM**
- **Deepgram TTS**

### Other components

- **Student**

## Connections

- Student → Voice overlay: starts conversation (evidence: `frontend/src/components/VoiceOverlay.tsx`)
- React app → Voice overlay: renders (evidence: `README.md`)
- Voice overlay → Voice session: starts session (evidence: `frontend/src/components/VoiceOverlay.tsx`)
- Voice session → Voice URL config: resolves URL (evidence: `frontend/src/audio/VoiceSession.ts`)
- Voice session → PCM capture worklet: loads capture (evidence: `frontend/src/audio/VoiceSession.ts`)
- Voice session → Audio playback: plays audio (evidence: `frontend/src/audio/VoiceSession.ts`)
- Voice session → Voice WebSocket: streams audio and receives events (evidence: `README.md`)
- FastAPI app → Voice WebSocket: registers router (evidence: `backend/main.py`)
- Voice WebSocket → AssemblyAI STT: forwards audio (evidence: `README.md`)
- AssemblyAI STT → Voice WebSocket: returns transcript (evidence: `README.md`)
- Voice WebSocket → OpenAI LLM: sends transcript and history (evidence: `README.md`)
- OpenAI LLM → Voice WebSocket: streams tokens (evidence: `README.md`)
- Voice WebSocket → Deepgram TTS: sends sentences (evidence: `backend/routes/voice_routes.py`)
- Deepgram TTS → Voice WebSocket: returns audio (evidence: `README.md`)
- Voice WebSocket → Voice session: streams audio and transcript events (evidence: `README.md`)
- FastAPI app → Health endpoint: serves (evidence: `backend/main.py`)
