# viswaags/translatorai architecture

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

- Interactive diagram: https://gitdiagram.com/viswaags/translatorai
- Repository: https://github.com/viswaags/translatorai

## Overview

AI Translator is a local-first browser application backed by a FastAPI service. Users submit text, images, or audio; the corresponding route detects or extracts input, then may translate it and optionally synthesize speech. The README documents these workflows and the browser-to-API boundary. Source excerpts show OCR orchestration and shared lazy service registration; the translation implementation and most frontend internals were not sampled, so those details are represented only where documented or indexed.

Main entry points: [`backend/ai_translator_api/core/registry.py`](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/core/registry.py) (Service registry), [`backend/ai_translator_api/main.py`](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/main.py) (FastAPI app), [`backend/ai_translator_api/api/routes/ocr.py`](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/routes/ocr.py) (Image workflow), [`backend/ai_translator_api/api/routes/speech.py`](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/routes/speech.py) (Speech workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser interface"]
  node_browser["Browser client<br/>[api.js]"]
end

subgraph group_api["API workflows"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_text_route["Text workflow<br/>[text.py]"]
  node_ocr_route["Image workflow<br/>[ocr.py]"]
  node_speech_route["Speech workflow<br/>[speech.py]"]
  node_health_route["Health status<br/>[health.py]"]
  node_schemas["API contracts<br/>[schemas.py]"]
end

subgraph group_inference["Inference services"]
  node_translation["IndicTrans2 translation"]
  node_ocr["PaddleOCR extraction<br/>[ocr_service.py]"]
  node_stt["Whisper transcription<br/>[stt_service.py]"]
  node_tts["Piper synthesis<br/>[tts_service.py]"]
  node_detector["Language detection"]
end

subgraph group_platform["Shared platform"]
  node_languages["Language catalog<br/>[languages.py]"]
  node_uploads["Upload handling<br/>[uploads.py]"]
  node_registry["Service registry<br/>[registry.py]"]
  node_readiness["Artifact readiness<br/>[readiness.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_errors["Error handling<br/>[error_handlers.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_browser
node_browser -->|"sends HTTP requests"| node_api_app
node_api_app -->|"routes to"| node_text_route
node_api_app -->|"routes to"| node_ocr_route
node_api_app -->|"routes to"| node_speech_route
node_api_app -->|"routes to"| node_health_route
node_api_app -->|"initializes"| node_registry
node_api_app -->|"checks artifacts"| node_readiness
node_api_app -->|"registers handlers"| node_errors
node_text_route -->|"gets services"| node_registry
node_text_route -->|"detects language"| node_detector
node_text_route -->|"translates text"| node_translation
node_text_route -.->|"optionally synthesizes"| node_tts
node_ocr_route -->|"manages image upload"| node_uploads
node_ocr_route -->|"gets services"| node_registry
node_ocr_route -->|"extracts text"| node_ocr
node_ocr_route -->|"translates extraction"| node_translation
node_ocr_route -->|"optionally synthesizes"| node_tts
node_ocr_route -->|"detects language"| node_detector
node_speech_route -->|"manages audio upload"| node_uploads
node_speech_route -->|"gets services"| node_registry
node_speech_route -->|"transcribes audio"| node_stt
node_speech_route -->|"translates transcript"| node_translation
node_speech_route -.->|"optionally synthesizes"| node_tts
node_health_route -->|"reports readiness"| node_readiness
node_health_route -->|"lists languages"| node_languages
node_registry -->|"creates lazily"| node_translation
node_registry -->|"creates lazily"| node_ocr
node_registry -->|"creates lazily"| node_stt
node_registry -->|"creates lazily"| node_tts
node_registry -->|"creates lazily"| node_detector
node_readiness -->|"reads settings"| node_config
node_readiness -->|"checks supported artifacts"| node_languages
node_ocr -->|"uses settings"| node_config
node_ocr -->|"uses language metadata"| node_languages
node_ocr -->|"detects language"| node_detector
node_stt -->|"uses settings"| node_config
node_stt -->|"maps recognized languages"| node_languages
node_tts -->|"uses settings"| node_config
node_tts -->|"uses language metadata"| node_languages
node_text_route -->|"validates requests"| node_schemas
node_ocr_route -->|"validates requests"| node_schemas
node_speech_route -->|"validates requests"| node_schemas
node_health_route -->|"formats status"| node_schemas

click node_browser "https://github.com/viswaags/translatorai/blob/main/frontend/js/api.js"
click node_api_app "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/main.py"
click node_text_route "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/routes/text.py"
click node_ocr_route "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/routes/ocr.py"
click node_speech_route "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/routes/speech.py"
click node_health_route "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/routes/health.py"
click node_schemas "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/models/schemas.py"
click node_translation "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/services/translation/translation_service.py"
click node_ocr "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/services/ocr/ocr_service.py"
click node_stt "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/services/stt/stt_service.py"
click node_tts "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/services/tts/tts_service.py"
click node_detector "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/utils/language_detector.py"
click node_languages "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/utils/languages.py"
click node_uploads "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/utils/uploads.py"
click node_registry "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/core/registry.py"
click node_readiness "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/core/readiness.py"
click node_config "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/core/config.py"
click node_errors "https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/error_handlers.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_browser,node_user toneBlue
class node_api_app,node_text_route,node_ocr_route,node_speech_route,node_health_route,node_schemas toneAmber
class node_translation,node_ocr,node_stt,node_tts,node_detector toneMint
class node_languages,node_uploads,node_registry,node_readiness,node_config,node_errors toneRose
```

## Components

### Browser interface

- [Browser client](https://github.com/viswaags/translatorai/blob/main/frontend/js/api.js): `frontend/js/api.js`

### API workflows

- [FastAPI app](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/main.py): `backend/ai_translator_api/main.py`
- [Text workflow](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/routes/text.py): `backend/ai_translator_api/api/routes/text.py`
- [Image workflow](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/routes/ocr.py): `backend/ai_translator_api/api/routes/ocr.py`
- [Speech workflow](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/routes/speech.py): `backend/ai_translator_api/api/routes/speech.py`
- [Health status](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/routes/health.py): `backend/ai_translator_api/api/routes/health.py`
- [API contracts](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/models/schemas.py): `backend/ai_translator_api/models/schemas.py`

### Inference services

- [IndicTrans2 translation](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/services/translation/translation_service.py): `backend/ai_translator_api/services/translation/translation_service.py`
- [PaddleOCR extraction](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/services/ocr/ocr_service.py): `backend/ai_translator_api/services/ocr/ocr_service.py`
- [Whisper transcription](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/services/stt/stt_service.py): `backend/ai_translator_api/services/stt/stt_service.py`
- [Piper synthesis](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/services/tts/tts_service.py): `backend/ai_translator_api/services/tts/tts_service.py`
- [Language detection](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/utils/language_detector.py): `backend/ai_translator_api/utils/language_detector.py`

### Shared platform

- [Language catalog](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/utils/languages.py): `backend/ai_translator_api/utils/languages.py`
- [Upload handling](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/utils/uploads.py): `backend/ai_translator_api/utils/uploads.py`
- [Service registry](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/core/registry.py): `backend/ai_translator_api/core/registry.py`
- [Artifact readiness](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/core/readiness.py): `backend/ai_translator_api/core/readiness.py`
- [Runtime configuration](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/core/config.py): `backend/ai_translator_api/core/config.py`
- [Error handling](https://github.com/viswaags/translatorai/blob/main/backend/ai_translator_api/api/error_handlers.py): `backend/ai_translator_api/api/error_handlers.py`

### Other components

- **User**

## Connections

- User → Browser client: uses (evidence: `README.md`)
- Browser client → FastAPI app: sends HTTP requests (evidence: `README.md`)
- FastAPI app → Text workflow: routes to (evidence: `backend/ai_translator_api/main.py`)
- FastAPI app → Image workflow: routes to (evidence: `backend/ai_translator_api/main.py`)
- FastAPI app → Speech workflow: routes to (evidence: `backend/ai_translator_api/main.py`)
- FastAPI app → Health status: routes to (evidence: `backend/ai_translator_api/main.py`)
- FastAPI app → Service registry: initializes (evidence: `backend/ai_translator_api/main.py`)
- FastAPI app → Artifact readiness: checks artifacts (evidence: `backend/ai_translator_api/main.py`)
- FastAPI app → Error handling: registers handlers (evidence: `backend/ai_translator_api/main.py`)
- Text workflow → Service registry: gets services (evidence: `backend/ai_translator_api/api/routes/text.py`)
- Text workflow → Language detection: detects language (evidence: `backend/ai_translator_api/api/routes/text.py`)
- Text workflow → IndicTrans2 translation: translates text (evidence: `README.md`)
- Text workflow → Piper synthesis: optionally synthesizes (evidence: `README.md`)
- Image workflow → Upload handling: manages image upload (evidence: `backend/ai_translator_api/api/routes/ocr.py`)
- Image workflow → Service registry: gets services (evidence: `backend/ai_translator_api/api/routes/ocr.py`)
- Image workflow → PaddleOCR extraction: extracts text (evidence: `backend/ai_translator_api/api/routes/ocr.py`)
- Image workflow → IndicTrans2 translation: translates extraction (evidence: `backend/ai_translator_api/api/routes/ocr.py`)
- Image workflow → Piper synthesis: optionally synthesizes (evidence: `backend/ai_translator_api/api/routes/ocr.py`)
- Image workflow → Language detection: detects language (evidence: `backend/ai_translator_api/api/routes/ocr.py`)
- Speech workflow → Upload handling: manages audio upload (evidence: `backend/ai_translator_api/api/routes/speech.py`)
- Speech workflow → Service registry: gets services (evidence: `backend/ai_translator_api/api/routes/speech.py`)
- Speech workflow → Whisper transcription: transcribes audio (evidence: `README.md`)
- Speech workflow → IndicTrans2 translation: translates transcript (evidence: `README.md`)
- Speech workflow → Piper synthesis: optionally synthesizes (evidence: `README.md`)
- Health status → Artifact readiness: reports readiness (evidence: `backend/ai_translator_api/api/routes/health.py`)
- Health status → Language catalog: lists languages (evidence: `backend/ai_translator_api/api/routes/health.py`)
- Service registry → IndicTrans2 translation: creates lazily (evidence: `backend/ai_translator_api/core/registry.py`)
- Service registry → PaddleOCR extraction: creates lazily (evidence: `backend/ai_translator_api/core/registry.py`)
- Service registry → Whisper transcription: creates lazily (evidence: `backend/ai_translator_api/core/registry.py`)
- Service registry → Piper synthesis: creates lazily (evidence: `backend/ai_translator_api/core/registry.py`)
- Service registry → Language detection: creates lazily (evidence: `backend/ai_translator_api/core/registry.py`)
- Artifact readiness → Runtime configuration: reads settings (evidence: `backend/ai_translator_api/core/readiness.py`)
- Artifact readiness → Language catalog: checks supported artifacts (evidence: `backend/ai_translator_api/core/readiness.py`)
- PaddleOCR extraction → Runtime configuration: uses settings (evidence: `backend/ai_translator_api/services/ocr/ocr_service.py`)
- PaddleOCR extraction → Language catalog: uses language metadata (evidence: `backend/ai_translator_api/services/ocr/ocr_service.py`)
- PaddleOCR extraction → Language detection: detects language (evidence: `backend/ai_translator_api/services/ocr/ocr_service.py`)
- Whisper transcription → Runtime configuration: uses settings (evidence: `backend/ai_translator_api/services/stt/stt_service.py`)
- Whisper transcription → Language catalog: maps recognized languages (evidence: `backend/ai_translator_api/services/stt/stt_service.py`)
- Piper synthesis → Runtime configuration: uses settings (evidence: `backend/ai_translator_api/services/tts/tts_service.py`)
- Piper synthesis → Language catalog: uses language metadata (evidence: `backend/ai_translator_api/services/tts/tts_service.py`)
- Text workflow → API contracts: validates requests (evidence: `backend/ai_translator_api/api/routes/text.py`)
- Image workflow → API contracts: validates requests (evidence: `backend/ai_translator_api/api/routes/ocr.py`)
- Speech workflow → API contracts: validates requests (evidence: `backend/ai_translator_api/api/routes/speech.py`)
- Health status → API contracts: formats status (evidence: `backend/ai_translator_api/api/routes/health.py`)
