# cat-in-a-box/decky-translator architecture

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

- Interactive diagram: https://gitdiagram.com/cat-in-a-box/decky-translator
- Repository: https://github.com/cat-in-a-box/decky-translator

## Overview

Decky Translator is a Steam Deck screen-translation plugin. The user starts a translation from the plugin UI or a configured quick-toggle control; the backend captures the screen, runs the selected OCR and translation providers, and returns translated regions for an on-screen overlay. Settings and model downloads configure this workflow, while provider choices include offline and web-based alternatives. The README documents the provider capabilities; because much of main.py and provider wiring was not sampled, uncertain internal calls are omitted.

Main entry points: [`main.py`](https://github.com/cat-in-a-box/decky-translator/blob/main/main.py) (Decky backend), [`src/index.tsx`](https://github.com/cat-in-a-box/decky-translator/blob/main/src/index.tsx) (Plugin entry), [`py_modules/providers/__init__.py`](https://github.com/cat-in-a-box/decky-translator/blob/main/py_modules/providers/__init__.py) (Provider manager), [`src/Translator.tsx`](https://github.com/cat-in-a-box/decky-translator/blob/main/src/Translator.tsx) (Translation workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Plugin interface"]
  node_plugin["Plugin entry<br/>[index.tsx]"]
  node_settings_ui["Settings context"]
  node_main_tab["Main tab<br/>[TabMain.tsx]"]
  node_translation_tab["Translation settings<br/>[TabTranslation.tsx]"]
  node_controls_tab["Control settings<br/>[TabControls.tsx]"]
  node_translator["Translation workflow<br/>[Translator.tsx]"]
  node_overlay["Result overlay<br/>[Overlay.tsx]"]
  node_fonts["Overlay fonts<br/>[index.ts]"]
end

subgraph group_backend["Capture and orchestration"]
  node_backend["Decky backend<br/>[main.py]"]
end

subgraph group_providers["Recognition and translation"]
  node_provider_manager["Provider manager<br/>[__init__.py]"]
  node_ocr["OCR providers"]
  node_gemini["Gemini Vision<br/>[gemini_vision.py]"]
  node_translation["Translation providers"]
  node_ct2["Offline NLLB worker"]
end

subgraph group_support["Configuration and models"]
  node_settings[("Persisted settings<br/>[main.py]")]
  node_cache[("Translation cache")]
  node_model_downloads["Model downloads"]
end

node_user(("Steam Deck user"))
node_screen(("Steam Deck screen"))
node_external_apis(("Web provider APIs"))

node_user -->|"opens plugin"| node_plugin
node_plugin -->|"shows main tab"| node_main_tab
node_plugin -->|"shows settings"| node_translation_tab
node_plugin -->|"shows controls"| node_controls_tab
node_plugin -->|"provides settings"| node_settings_ui
node_settings_ui -->|"loads and saves"| node_backend
node_main_tab -->|"starts translation"| node_translator
node_controls_tab -->|"configures controls"| node_backend
node_translation_tab -->|"configures providers"| node_backend
node_translator -->|"requests translation"| node_backend
node_backend -->|"captures image"| node_screen
node_backend -->|"selects providers"| node_provider_manager
node_provider_manager -->|"dispatches OCR"| node_ocr
node_provider_manager -->|"dispatches translation"| node_translation
node_ocr -.->|"sends image"| node_external_apis
node_translation -.->|"sends text"| node_external_apis
node_provider_manager -->|"selects integrated OCR"| node_gemini
node_gemini -.->|"sends image request"| node_external_apis
node_translation -->|"runs offline translation"| node_ct2
node_backend -->|"reads and writes"| node_cache
node_backend -->|"reads and writes"| node_settings
node_provider_manager -->|"manages model availability"| node_model_downloads
node_backend -->|"returns regions"| node_translator
node_translator -->|"provides translated regions"| node_overlay
node_overlay -->|"loads font options"| node_fonts

click node_plugin "https://github.com/cat-in-a-box/decky-translator/blob/main/src/index.tsx"
click node_settings_ui "https://github.com/cat-in-a-box/decky-translator/blob/main/src/SettingsContext.tsx"
click node_main_tab "https://github.com/cat-in-a-box/decky-translator/blob/main/src/tabs/TabMain.tsx"
click node_translation_tab "https://github.com/cat-in-a-box/decky-translator/blob/main/src/tabs/TabTranslation.tsx"
click node_controls_tab "https://github.com/cat-in-a-box/decky-translator/blob/main/src/tabs/TabControls.tsx"
click node_translator "https://github.com/cat-in-a-box/decky-translator/blob/main/src/Translator.tsx"
click node_overlay "https://github.com/cat-in-a-box/decky-translator/blob/main/src/Overlay.tsx"
click node_fonts "https://github.com/cat-in-a-box/decky-translator/blob/main/src/fonts/index.ts"
click node_backend "https://github.com/cat-in-a-box/decky-translator/blob/main/main.py"
click node_provider_manager "https://github.com/cat-in-a-box/decky-translator/blob/main/py_modules/providers/__init__.py"
click node_ocr "https://github.com/cat-in-a-box/decky-translator/tree/main/py_modules/providers"
click node_gemini "https://github.com/cat-in-a-box/decky-translator/blob/main/py_modules/providers/gemini_vision.py"
click node_translation "https://github.com/cat-in-a-box/decky-translator/tree/main/py_modules/providers"
click node_ct2 "https://github.com/cat-in-a-box/decky-translator/blob/main/py_modules/providers/ct2_translate_worker.py"
click node_settings "https://github.com/cat-in-a-box/decky-translator/blob/main/main.py"
click node_cache "https://github.com/cat-in-a-box/decky-translator/blob/main/py_modules/providers/translation_cache.py"
click node_model_downloads "https://github.com/cat-in-a-box/decky-translator/tree/main/py_modules/providers"

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_plugin,node_settings_ui,node_main_tab,node_translation_tab,node_controls_tab,node_translator,node_overlay,node_fonts,node_user,node_screen toneBlue
class node_backend toneAmber
class node_provider_manager,node_ocr,node_gemini,node_translation,node_ct2,node_external_apis toneMint
class node_settings,node_cache,node_model_downloads toneRose
```

## Components

### Plugin interface

- [Plugin entry](https://github.com/cat-in-a-box/decky-translator/blob/main/src/index.tsx): `src/index.tsx`
- [Settings context](https://github.com/cat-in-a-box/decky-translator/blob/main/src/SettingsContext.tsx): `src/SettingsContext.tsx`
- [Main tab](https://github.com/cat-in-a-box/decky-translator/blob/main/src/tabs/TabMain.tsx): `src/tabs/TabMain.tsx`
- [Translation settings](https://github.com/cat-in-a-box/decky-translator/blob/main/src/tabs/TabTranslation.tsx): `src/tabs/TabTranslation.tsx`
- [Control settings](https://github.com/cat-in-a-box/decky-translator/blob/main/src/tabs/TabControls.tsx): `src/tabs/TabControls.tsx`
- [Translation workflow](https://github.com/cat-in-a-box/decky-translator/blob/main/src/Translator.tsx): `src/Translator.tsx`
- [Result overlay](https://github.com/cat-in-a-box/decky-translator/blob/main/src/Overlay.tsx): `src/Overlay.tsx`
- [Overlay fonts](https://github.com/cat-in-a-box/decky-translator/blob/main/src/fonts/index.ts): `src/fonts/index.ts`

### Capture and orchestration

- [Decky backend](https://github.com/cat-in-a-box/decky-translator/blob/main/main.py): `main.py`

### Recognition and translation

- [Provider manager](https://github.com/cat-in-a-box/decky-translator/blob/main/py_modules/providers/__init__.py): `py_modules/providers/__init__.py`
- [OCR providers](https://github.com/cat-in-a-box/decky-translator/tree/main/py_modules/providers): `py_modules/providers`
- [Gemini Vision](https://github.com/cat-in-a-box/decky-translator/blob/main/py_modules/providers/gemini_vision.py): `py_modules/providers/gemini_vision.py`
- [Translation providers](https://github.com/cat-in-a-box/decky-translator/tree/main/py_modules/providers): `py_modules/providers`
- [Offline NLLB worker](https://github.com/cat-in-a-box/decky-translator/blob/main/py_modules/providers/ct2_translate_worker.py): `py_modules/providers/ct2_translate_worker.py`

### Configuration and models

- [Persisted settings](https://github.com/cat-in-a-box/decky-translator/blob/main/main.py): `main.py`
- [Translation cache](https://github.com/cat-in-a-box/decky-translator/blob/main/py_modules/providers/translation_cache.py): `py_modules/providers/translation_cache.py`
- [Model downloads](https://github.com/cat-in-a-box/decky-translator/tree/main/py_modules/providers): `py_modules/providers`

### Other components

- **Steam Deck user**
- **Steam Deck screen**
- **Web provider APIs**

## Connections

- Steam Deck user → Plugin entry: opens plugin
- Plugin entry → Main tab: shows main tab
- Plugin entry → Translation settings: shows settings
- Plugin entry → Control settings: shows controls
- Plugin entry → Settings context: provides settings
- Settings context → Decky backend: loads and saves
- Main tab → Translation workflow: starts translation
- Control settings → Decky backend: configures controls
- Translation settings → Decky backend: configures providers
- Translation workflow → Decky backend: requests translation
- Decky backend → Steam Deck screen: captures image
- Decky backend → Provider manager: selects providers
- Provider manager → OCR providers: dispatches OCR
- Provider manager → Translation providers: dispatches translation
- OCR providers → Web provider APIs: sends image
- Translation providers → Web provider APIs: sends text
- Provider manager → Gemini Vision: selects integrated OCR
- Gemini Vision → Web provider APIs: sends image request
- Translation providers → Offline NLLB worker: runs offline translation
- Decky backend → Translation cache: reads and writes
- Decky backend → Persisted settings: reads and writes
- Provider manager → Model downloads: manages model availability
- Decky backend → Translation workflow: returns regions
- Translation workflow → Result overlay: provides translated regions
- Result overlay → Overlay fonts: loads font options