# hari31416/indic-language-utils architecture

> Architecture diagram of the GitHub repository hari31416/indic-language-utils, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hari31416/indic-language-utils
- Repository: https://github.com/hari31416/indic-language-utils

## Overview

indic-language-utils is a provider-neutral Python toolkit for Indian-language text and speech capabilities, with an optional FastAPI interactive workbench. A typical workflow accepts text or audio, normalizes language information, selects a configured provider route, and returns translated, detected, transliterated, transcribed, or synthesized results. The README also documents script identification, document/code protection, localization catalogs, caching, and resilient fallback. Sampled clients confirm routing and caching for several capabilities; where source was not sampled, the graph shows documented subsystems without inferring their internal call chains.

Main entry points: [`src/indic_language_utils/server/routes.py`](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/server/routes.py) (REST endpoints), [`src/indic_language_utils/routing.py`](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/routing.py) (Provider routing), [`src/indic_language_utils/detection/client.py`](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/detection/client.py) (Language detection), [`src/indic_language_utils/transliteration/client.py`](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/transliteration/client.py) (Transliteration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workbench["Interactive workbench"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_webviews["Capability views"]
  node_webapi["Web API client<br/>[api.ts]"]
  node_webstream["Audio streaming<br/>[streaming.ts]"]
  node_webkeys["Key storage<br/>[storage.ts]"]
  node_serverapp["HTTP application<br/>[app.py]"]
  node_routes["REST endpoints<br/>[routes.py]"]
  node_wsroutes["WebSocket endpoints<br/>[streaming.py]"]
end

subgraph group_capabilities["Language capabilities"]
  node_translation["Translation"]
  node_detection["Language detection<br/>[client.py]"]
  node_transliteration["Transliteration<br/>[client.py]"]
  node_script["Script identification<br/>[languages.py]"]
  node_stt["Speech transcription<br/>[client.py]"]
  node_tts["Speech synthesis<br/>[client.py]"]
  node_processing["Text processing<br/>[processors.py]"]
end

subgraph group_execution["Provider execution"]
  node_routing["Provider routing<br/>[routing.py]"]
  node_providerregistry["Provider registry<br/>[factories.py]"]
  node_adapters["Provider adapters"]
end

subgraph group_shared["Shared foundations"]
  node_config["Configuration<br/>[config.py]"]
  node_languages["Language registry<br/>[languages.py]"]
  node_cache[("Caching<br/>[cache.py]")]
end

subgraph group_integrations["External engines"]
  node_providers{{"Cloud and local engines"}}
  node_browser[("Browser storage")]
end

node_user(("Workbench user"))

node_user -->|"uses"| node_webapp
node_webapp -->|"selects view"| node_webviews
node_webviews -->|"requests"| node_webapi
node_webviews -->|"streams audio"| node_webstream
node_webapp -->|"manages keys"| node_webkeys
node_webkeys -->|"reads and writes"| node_browser
node_webapi -->|"HTTP requests"| node_routes
node_webstream -->|"WebSocket audio"| node_wsroutes
node_serverapp -->|"mounts routes"| node_routes
node_serverapp -->|"mounts routes"| node_wsroutes
node_routes -->|"runs detection"| node_detection
node_routes -->|"runs transcription"| node_stt
node_routes -->|"runs synthesis"| node_tts
node_detection -->|"gets candidates"| node_routing
node_transliteration -->|"gets candidates"| node_routing
node_stt -->|"gets candidates"| node_routing
node_tts -->|"gets candidates"| node_routing
node_routing -->|"resolves route"| node_providerregistry
node_providerregistry -->|"registers providers"| node_adapters
node_adapters -->|"calls engines"| node_providers
node_detection -->|"reads and writes"| node_cache
node_transliteration -->|"reads and writes"| node_cache
node_tts -->|"reads and writes"| node_cache
node_detection -->|"normalizes language"| node_languages
node_transliteration -->|"normalizes language"| node_languages
node_stt -->|"normalizes language"| node_languages
node_translation -.->|"uses engines"| node_providers
node_processing -.->|"protects text"| node_translation

click node_webapp "https://github.com/hari31416/indic-language-utils/blob/main/web/src/App.tsx"
click node_webviews "https://github.com/hari31416/indic-language-utils/tree/main/web/src/components"
click node_webapi "https://github.com/hari31416/indic-language-utils/blob/main/web/src/api.ts"
click node_webstream "https://github.com/hari31416/indic-language-utils/blob/main/web/src/streaming.ts"
click node_webkeys "https://github.com/hari31416/indic-language-utils/blob/main/web/src/storage.ts"
click node_serverapp "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/server/app.py"
click node_routes "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/server/routes.py"
click node_wsroutes "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/server/streaming.py"
click node_translation "https://github.com/hari31416/indic-language-utils/tree/main/src/indic_language_utils/providers"
click node_detection "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/detection/client.py"
click node_transliteration "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/transliteration/client.py"
click node_script "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/languages.py"
click node_stt "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/stt/client.py"
click node_tts "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/tts/client.py"
click node_processing "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/processors.py"
click node_routing "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/routing.py"
click node_providerregistry "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/providers/factories.py"
click node_adapters "https://github.com/hari31416/indic-language-utils/tree/main/src/indic_language_utils/providers"
click node_config "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/config.py"
click node_languages "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/languages.py"
click node_cache "https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/cache.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_webapp,node_webviews,node_webapi,node_webstream,node_webkeys,node_serverapp,node_routes,node_wsroutes,node_user toneBlue
class node_translation,node_detection,node_transliteration,node_script,node_stt,node_tts,node_processing toneAmber
class node_routing,node_providerregistry,node_adapters toneMint
class node_config,node_languages,node_cache toneRose
class node_providers,node_browser toneIndigo
```

## Components

### Interactive workbench

- [Web application](https://github.com/hari31416/indic-language-utils/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Capability views](https://github.com/hari31416/indic-language-utils/tree/main/web/src/components): `web/src/components`
- [Web API client](https://github.com/hari31416/indic-language-utils/blob/main/web/src/api.ts): `web/src/api.ts`
- [Audio streaming](https://github.com/hari31416/indic-language-utils/blob/main/web/src/streaming.ts): `web/src/streaming.ts`
- [Key storage](https://github.com/hari31416/indic-language-utils/blob/main/web/src/storage.ts): `web/src/storage.ts`
- [HTTP application](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/server/app.py): `src/indic_language_utils/server/app.py`
- [REST endpoints](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/server/routes.py): `src/indic_language_utils/server/routes.py`
- [WebSocket endpoints](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/server/streaming.py): `src/indic_language_utils/server/streaming.py`

### Language capabilities

- [Translation](https://github.com/hari31416/indic-language-utils/tree/main/src/indic_language_utils/providers): `src/indic_language_utils/providers`
- [Language detection](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/detection/client.py): `src/indic_language_utils/detection/client.py`
- [Transliteration](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/transliteration/client.py): `src/indic_language_utils/transliteration/client.py`
- [Script identification](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/languages.py): `src/indic_language_utils/languages.py`
- [Speech transcription](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/stt/client.py): `src/indic_language_utils/stt/client.py`
- [Speech synthesis](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/tts/client.py): `src/indic_language_utils/tts/client.py`
- [Text processing](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/processors.py): `src/indic_language_utils/processors.py`

### Provider execution

- [Provider routing](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/routing.py): `src/indic_language_utils/routing.py`
- [Provider registry](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/providers/factories.py): `src/indic_language_utils/providers/factories.py`
- [Provider adapters](https://github.com/hari31416/indic-language-utils/tree/main/src/indic_language_utils/providers): `src/indic_language_utils/providers`

### Shared foundations

- [Configuration](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/config.py): `src/indic_language_utils/config.py`
- [Language registry](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/languages.py): `src/indic_language_utils/languages.py`
- [Caching](https://github.com/hari31416/indic-language-utils/blob/main/src/indic_language_utils/cache.py): `src/indic_language_utils/cache.py`

### External engines

- **Cloud and local engines**
- **Browser storage**

### Other components

- **Workbench user**

## Connections

- Workbench user → Web application: uses
- Web application → Capability views: selects view
- Capability views → Web API client: requests
- Capability views → Audio streaming: streams audio
- Web application → Key storage: manages keys
- Key storage → Browser storage: reads and writes
- Web API client → REST endpoints: HTTP requests
- Audio streaming → WebSocket endpoints: WebSocket audio
- HTTP application → REST endpoints: mounts routes
- HTTP application → WebSocket endpoints: mounts routes
- REST endpoints → Language detection: runs detection
- REST endpoints → Speech transcription: runs transcription
- REST endpoints → Speech synthesis: runs synthesis
- Language detection → Provider routing: gets candidates
- Transliteration → Provider routing: gets candidates
- Speech transcription → Provider routing: gets candidates
- Speech synthesis → Provider routing: gets candidates
- Provider routing → Provider registry: resolves route
- Provider registry → Provider adapters: registers providers
- Provider adapters → Cloud and local engines: calls engines
- Language detection → Caching: reads and writes
- Transliteration → Caching: reads and writes
- Speech synthesis → Caching: reads and writes
- Language detection → Language registry: normalizes language
- Transliteration → Language registry: normalizes language
- Speech transcription → Language registry: normalizes language
- Translation → Cloud and local engines: uses engines
- Text processing → Translation: protects text