# alexalkhatib/realtime-voice-translator architecture

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

- Interactive diagram: https://gitdiagram.com/alexalkhatib/realtime-voice-translator
- Repository: https://github.com/alexalkhatib/realtime-voice-translator

## Overview

Real-Time AI Voice Translator captures browser speech or replays a demo conversation, sends recognized segments to FastAPI for validation and translation, then displays and optionally speaks the result. The server supports Google, MyMemory, and offline demo translation, optional Gemini refinement, Google TTS, latency metrics, and cached results; the browser also offers REST fallback, transcript exports, and browser speech synthesis. Edges follow the excerpts, SOURCE INDEX references, and README; some detailed route and fallback internals were not sampled.

Main entry points: [`app/pipeline.py`](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/pipeline.py) (Translation pipeline), [`app/providers/registry.py`](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/registry.py) (Provider assembly), [`web/js/app.js`](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/js/app.js) (Session controller), [`app/main.py`](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/main.py) (FastAPI routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser experience"]
  node_ui["Session interface<br/>[index.html]"]
  node_controller["Session controller<br/>[app.js]"]
  node_recognition["Speech recognition<br/>[speech.js]"]
  node_demo_script["Demo conversation<br/>[demo.js]"]
  node_api_client["Transport client<br/>[api.js]"]
  node_audio["Audio playback<br/>[audio.js]"]
end

subgraph group_server["API and orchestration"]
  node_fastapi["FastAPI routes<br/>[main.py]"]
  node_pipeline["Translation pipeline<br/>[pipeline.py]"]
  node_registry["Provider assembly<br/>[registry.py]"]
end

subgraph group_providers["Translation and speech engines"]
  node_provider_contracts["Provider contracts<br/>[base.py]"]
  node_google_translation["Google translation<br/>[google.py]"]
  node_google_tts["Google speech synthesis<br/>[google.py]"]
  node_mymemory["MyMemory translation<br/>[mymemory.py]"]
  node_offline["Offline translations<br/>[demo.py]"]
  node_gemini["Gemini refinement<br/>[gemini.py]"]
end

subgraph group_shared["Shared domain services"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_languages["Language catalog<br/>[languages.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
  node_text["Text utilities<br/>[text.py]"]
  node_metrics["Latency metrics<br/>[metrics.py]"]
end

node_user(("Translator"))
node_browser_speech["Browser speech APIs"]
node_google_cloud["Google Cloud"]
node_mymemory_service["MyMemory service"]
node_gemini_service["Gemini service"]

node_user -->|"uses"| node_ui
node_ui -->|"hosts"| node_controller
node_controller -->|"starts recognition"| node_recognition
node_controller -->|"replays"| node_demo_script
node_recognition -->|"recognizes speech"| node_browser_speech
node_controller -->|"requests translation"| node_api_client
node_api_client -->|"sends WebSocket or REST"| node_fastapi
node_fastapi -->|"dispatches requests"| node_pipeline
node_fastapi -->|"validates requests"| node_schemas
node_fastapi -->|"serves language config"| node_languages
node_fastapi -->|"builds pipeline"| node_registry
node_registry -->|"configures engines"| node_settings
node_registry -->|"registers"| node_google_translation
node_registry -->|"registers"| node_google_tts
node_registry -->|"registers"| node_mymemory
node_registry -->|"registers"| node_offline
node_registry -->|"configures optional refiner"| node_gemini
node_pipeline -->|"uses contracts"| node_provider_contracts
node_pipeline -->|"resolves languages"| node_languages
node_pipeline -->|"cleans text"| node_text
node_pipeline -->|"records latency"| node_metrics
node_pipeline -.->|"tries translation"| node_google_translation
node_pipeline -->|"falls back to"| node_mymemory
node_pipeline -->|"falls back to"| node_offline
node_pipeline -->|"optionally refines"| node_gemini
node_pipeline -->|"optionally synthesizes"| node_google_tts
node_google_translation -.->|"calls"| node_google_cloud
node_google_tts -.->|"calls"| node_google_cloud
node_mymemory -->|"calls"| node_mymemory_service
node_gemini -.->|"calls"| node_gemini_service
node_controller -->|"plays result"| node_audio
node_audio -->|"speaks fallback"| node_browser_speech

click node_ui "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/index.html"
click node_controller "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/js/app.js"
click node_recognition "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/js/speech.js"
click node_demo_script "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/js/demo.js"
click node_api_client "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/js/api.js"
click node_audio "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/js/audio.js"
click node_fastapi "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/main.py"
click node_pipeline "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/pipeline.py"
click node_registry "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/registry.py"
click node_settings "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/config.py"
click node_languages "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/languages.py"
click node_schemas "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/schemas.py"
click node_text "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/text.py"
click node_metrics "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/metrics.py"
click node_provider_contracts "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/base.py"
click node_google_translation "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/google.py"
click node_google_tts "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/google.py"
click node_mymemory "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/mymemory.py"
click node_offline "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/demo.py"
click node_gemini "https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/gemini.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,node_controller,node_recognition,node_demo_script,node_api_client,node_audio,node_browser_speech toneBlue
class node_fastapi,node_pipeline,node_registry toneAmber
class node_provider_contracts,node_google_translation,node_google_tts,node_mymemory,node_offline,node_gemini toneMint
class node_settings,node_languages,node_schemas,node_text,node_metrics toneRose
class node_user,node_google_cloud,node_mymemory_service,node_gemini_service toneIndigo
```

## Components

### Browser experience

- [Session interface](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/index.html): `web/index.html`
- [Session controller](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/js/app.js): `web/js/app.js`
- [Speech recognition](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/js/speech.js): `web/js/speech.js`
- [Demo conversation](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/js/demo.js): `web/js/demo.js`
- [Transport client](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/js/api.js): `web/js/api.js`
- [Audio playback](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/web/js/audio.js): `web/js/audio.js`

### API and orchestration

- [FastAPI routes](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/main.py): `app/main.py`
- [Translation pipeline](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/pipeline.py): `app/pipeline.py`
- [Provider assembly](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/registry.py): `app/providers/registry.py`

### Translation and speech engines

- [Provider contracts](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/base.py): `app/providers/base.py`
- [Google translation](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/google.py): `app/providers/google.py`
- [Google speech synthesis](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/google.py): `app/providers/google.py`
- [MyMemory translation](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/mymemory.py): `app/providers/mymemory.py`
- [Offline translations](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/demo.py): `app/providers/demo.py`
- [Gemini refinement](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/providers/gemini.py): `app/providers/gemini.py`

### Shared domain services

- [Runtime settings](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/config.py): `app/config.py`
- [Language catalog](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/languages.py): `app/languages.py`
- [Request and response schemas](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/schemas.py): `app/schemas.py`
- [Text utilities](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/text.py): `app/text.py`
- [Latency metrics](https://github.com/alexalkhatib/realtime-voice-translator/blob/main/app/metrics.py): `app/metrics.py`

### Other components

- **Translator**
- **Browser speech APIs**
- **Google Cloud**
- **MyMemory service**
- **Gemini service**

## Connections

- Translator → Session interface: uses (evidence: `README.md`)
- Session interface → Session controller: hosts (evidence: `README.md`)
- Session controller → Speech recognition: starts recognition (evidence: `web/js/app.js`)
- Session controller → Demo conversation: replays (evidence: `web/js/app.js`)
- Speech recognition → Browser speech APIs: recognizes speech (evidence: `README.md`)
- Session controller → Transport client: requests translation (evidence: `web/js/app.js`)
- Transport client → FastAPI routes: sends WebSocket or REST (evidence: `README.md`)
- FastAPI routes → Translation pipeline: dispatches requests (evidence: `README.md`)
- FastAPI routes → Request and response schemas: validates requests (evidence: `app/main.py`)
- FastAPI routes → Language catalog: serves language config (evidence: `app/main.py`)
- FastAPI routes → Provider assembly: builds pipeline (evidence: `app/main.py`)
- Provider assembly → Runtime settings: configures engines (evidence: `app/providers/registry.py`)
- Provider assembly → Google translation: registers (evidence: `app/providers/registry.py`)
- Provider assembly → Google speech synthesis: registers (evidence: `app/providers/registry.py`)
- Provider assembly → MyMemory translation: registers (evidence: `app/providers/registry.py`)
- Provider assembly → Offline translations: registers (evidence: `app/providers/registry.py`)
- Provider assembly → Gemini refinement: configures optional refiner (evidence: `app/providers/registry.py`)
- Translation pipeline → Provider contracts: uses contracts (evidence: `app/pipeline.py`)
- Translation pipeline → Language catalog: resolves languages (evidence: `app/pipeline.py`)
- Translation pipeline → Text utilities: cleans text (evidence: `app/pipeline.py`)
- Translation pipeline → Latency metrics: records latency (evidence: `app/pipeline.py`)
- Translation pipeline → Google translation: tries translation
- Translation pipeline → MyMemory translation: falls back to (evidence: `README.md`)
- Translation pipeline → Offline translations: falls back to (evidence: `README.md`)
- Translation pipeline → Gemini refinement: optionally refines (evidence: `README.md`)
- Translation pipeline → Google speech synthesis: optionally synthesizes (evidence: `README.md`)
- Google translation → Google Cloud: calls
- Google speech synthesis → Google Cloud: calls
- MyMemory translation → MyMemory service: calls (evidence: `README.md`)
- Gemini refinement → Gemini service: calls
- Session controller → Audio playback: plays result (evidence: `web/js/app.js`)
- Audio playback → Browser speech APIs: speaks fallback (evidence: `README.md`)