# kizuna-ai-lab/sokuji architecture

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

- Interactive diagram: https://gitdiagram.com/kizuna-ai-lab/sokuji
- Repository: https://github.com/kizuna-ai-lab/sokuji

## Overview

Sokuji is a desktop and browser-extension app for real-time, two-way speech translation, with cloud and fully offline modes. The main workflow captures microphone and meeting/system audio, processes speech through provider-backed or local ASR → translation → TTS, then presents subtitles and routes translated audio for others to hear. Major documented capabilities include provider selection, local model management, session display and extension/desktop use. The README documents the product flow; sampled source confirms local engine and model-management details, but not every runtime connection.

Main entry points: [`src/components/MainPanel/MainPanel.tsx`](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/components/MainPanel/MainPanel.tsx) (Translation session), [`src/services/clients/LocalInferenceClient.ts`](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/services/clients/LocalInferenceClient.ts) (Local inference client), [`src/stores/modelStore.ts`](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/stores/modelStore.ts) (Model store), [`src/services/clients/ClientFactory.ts`](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/services/clients/ClientFactory.ts) (Client factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Session experience"]
  node_session["Translation session<br/>[MainPanel.tsx]"]
  node_subtitles["Live subtitles<br/>[SubtitleApp.tsx]"]
  node_conversation[("Conversation display")]
  node_settings["Provider settings<br/>[Settings.tsx]"]
end

subgraph group_audio["Audio capture and output"]
  node_capture["Audio capture"]
  node_desktop_capture["System audio<br/>[audio-host.js]"]
  node_extension_capture["Meeting audio<br/>[content.js]"]
  node_playback["Translated audio"]
  node_virtual_mic["Virtual microphone"]
end

subgraph group_providers["Speech processing"]
  node_operations["Client operations"]
  node_client_factory["Client factory<br/>[ClientFactory.ts]"]
  node_cloud_clients["Cloud provider clients<br/>[index.ts]"]
end

subgraph group_local["Local inference"]
  node_local_client["Local inference client"]
  node_asr["Speech recognition<br/>[AsrEngine.ts]"]
  node_translation["Text translation"]
  node_tts["Speech synthesis<br/>[TtsEngine.ts]"]
  node_model_management["Local model management<br/>[ModelManager.ts]"]
  node_model_store[("Model store<br/>[modelStore.ts]")]
  node_native_runtime["Native inference sidecar<br/>[server.py]"]
end

subgraph group_runtime["Desktop and extension"]
  node_desktop["Desktop shell<br/>[main.js]"]
  node_extension["Browser extension<br/>[background.js]"]
  node_subtitle_surface["Subtitle surfaces"]
end

node_speaker(("Meeting participants"))
node_cloud_services{{"Cloud speech services"}}

node_speaker -->|"speaks into"| node_capture
node_speaker -->|"meeting audio"| node_desktop_capture
node_speaker -->|"meeting audio"| node_extension_capture
node_capture -->|"audio input"| node_session
node_desktop_capture -->|"audio input"| node_session
node_extension_capture -->|"audio input"| node_session
node_settings -->|"configures"| node_session
node_session -->|"starts session"| node_operations
node_operations -->|"creates client"| node_client_factory
node_client_factory -->|"selects provider"| node_cloud_clients
node_cloud_clients -->|"sends audio"| node_cloud_services
node_cloud_services -->|"returns speech"| node_cloud_clients
node_client_factory -->|"selects local"| node_local_client
node_local_client -->|"transcribes"| node_asr
node_local_client -->|"translates text"| node_translation
node_local_client -->|"synthesizes speech"| node_tts
node_asr -->|"transcript"| node_local_client
node_translation -->|"translated text"| node_local_client
node_tts -->|"audio output"| node_local_client
node_model_management -->|"manages models"| node_model_store
node_model_store -->|"provides models"| node_asr
node_model_store -->|"provides models"| node_translation
node_model_store -->|"provides models"| node_tts
node_local_client -.->|"uses native engine"| node_native_runtime
node_session -->|"updates display"| node_conversation
node_session -->|"updates subtitles"| node_subtitles
node_session -->|"plays translated audio"| node_playback
node_playback -->|"routes audio"| node_virtual_mic
node_desktop -->|"hosts capture"| node_desktop_capture
node_extension -->|"hosts capture"| node_extension_capture
node_subtitles -->|"renders on"| node_subtitle_surface

click node_session "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/components/MainPanel/MainPanel.tsx"
click node_subtitles "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/components/Subtitle/SubtitleApp.tsx"
click node_conversation "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/stores/conversationDisplayStore.ts"
click node_settings "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/components/Settings/Settings.tsx"
click node_capture "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/modern-audio/ModernBrowserAudioService.ts"
click node_desktop_capture "https://github.com/kizuna-ai-lab/sokuji/blob/main/electron/audio-host.js"
click node_extension_capture "https://github.com/kizuna-ai-lab/sokuji/blob/main/extension/content/content.js"
click node_playback "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/modern-audio/ModernAudioPlayer.js"
click node_virtual_mic "https://github.com/kizuna-ai-lab/sokuji/blob/main/extension/content/virtual-microphone.js"
click node_operations "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/services/ClientOperations.ts"
click node_client_factory "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/services/clients/ClientFactory.ts"
click node_cloud_clients "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/services/clients/index.ts"
click node_local_client "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/services/clients/LocalInferenceClient.ts"
click node_asr "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/local-inference/engine/AsrEngine.ts"
click node_translation "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/local-inference/engine/TranslationEngine.ts"
click node_tts "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/local-inference/engine/TtsEngine.ts"
click node_model_management "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/local-inference/ModelManager.ts"
click node_model_store "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/stores/modelStore.ts"
click node_native_runtime "https://github.com/kizuna-ai-lab/sokuji/blob/main/sidecar/sokuji_sidecar/server.py"
click node_desktop "https://github.com/kizuna-ai-lab/sokuji/blob/main/electron/main.js"
click node_extension "https://github.com/kizuna-ai-lab/sokuji/blob/main/extension/background/background.js"
click node_subtitle_surface "https://github.com/kizuna-ai-lab/sokuji/blob/main/src/components/Subtitle/surfaces/getSubtitleSurface.ts"

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_session,node_subtitles,node_conversation,node_settings toneBlue
class node_capture,node_desktop_capture,node_extension_capture,node_playback,node_virtual_mic toneAmber
class node_operations,node_client_factory,node_cloud_clients toneMint
class node_local_client,node_asr,node_translation,node_tts,node_model_management,node_model_store,node_native_runtime toneRose
class node_desktop,node_extension,node_subtitle_surface,node_speaker,node_cloud_services toneIndigo
```

## Components

### Session experience

- [Translation session](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/components/MainPanel/MainPanel.tsx): `src/components/MainPanel/MainPanel.tsx`
- [Live subtitles](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/components/Subtitle/SubtitleApp.tsx): `src/components/Subtitle/SubtitleApp.tsx`
- [Conversation display](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/stores/conversationDisplayStore.ts): `src/stores/conversationDisplayStore.ts`
- [Provider settings](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/components/Settings/Settings.tsx): `src/components/Settings/Settings.tsx`

### Audio capture and output

- [Audio capture](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/modern-audio/ModernBrowserAudioService.ts): `src/lib/modern-audio/ModernBrowserAudioService.ts`
- [System audio](https://github.com/kizuna-ai-lab/sokuji/blob/main/electron/audio-host.js): `electron/audio-host.js`
- [Meeting audio](https://github.com/kizuna-ai-lab/sokuji/blob/main/extension/content/content.js): `extension/content/content.js`
- [Translated audio](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/modern-audio/ModernAudioPlayer.js): `src/lib/modern-audio/ModernAudioPlayer.js`
- [Virtual microphone](https://github.com/kizuna-ai-lab/sokuji/blob/main/extension/content/virtual-microphone.js): `extension/content/virtual-microphone.js`

### Speech processing

- [Client operations](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/services/ClientOperations.ts): `src/services/ClientOperations.ts`
- [Client factory](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/services/clients/ClientFactory.ts): `src/services/clients/ClientFactory.ts`
- [Cloud provider clients](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/services/clients/index.ts): `src/services/clients/index.ts`

### Local inference

- [Local inference client](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/services/clients/LocalInferenceClient.ts): `src/services/clients/LocalInferenceClient.ts`
- [Speech recognition](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/local-inference/engine/AsrEngine.ts): `src/lib/local-inference/engine/AsrEngine.ts`
- [Text translation](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/local-inference/engine/TranslationEngine.ts): `src/lib/local-inference/engine/TranslationEngine.ts`
- [Speech synthesis](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/local-inference/engine/TtsEngine.ts): `src/lib/local-inference/engine/TtsEngine.ts`
- [Local model management](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/lib/local-inference/ModelManager.ts): `src/lib/local-inference/ModelManager.ts`
- [Model store](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/stores/modelStore.ts): `src/stores/modelStore.ts`
- [Native inference sidecar](https://github.com/kizuna-ai-lab/sokuji/blob/main/sidecar/sokuji_sidecar/server.py): `sidecar/sokuji_sidecar/server.py`

### Desktop and extension

- [Desktop shell](https://github.com/kizuna-ai-lab/sokuji/blob/main/electron/main.js): `electron/main.js`
- [Browser extension](https://github.com/kizuna-ai-lab/sokuji/blob/main/extension/background/background.js): `extension/background/background.js`
- [Subtitle surfaces](https://github.com/kizuna-ai-lab/sokuji/blob/main/src/components/Subtitle/surfaces/getSubtitleSurface.ts): `src/components/Subtitle/surfaces/getSubtitleSurface.ts`

### Other components

- **Meeting participants**
- **Cloud speech services**

## Connections

- Meeting participants → Audio capture: speaks into
- Meeting participants → System audio: meeting audio
- Meeting participants → Meeting audio: meeting audio
- Audio capture → Translation session: audio input
- System audio → Translation session: audio input
- Meeting audio → Translation session: audio input
- Provider settings → Translation session: configures
- Translation session → Client operations: starts session
- Client operations → Client factory: creates client
- Client factory → Cloud provider clients: selects provider
- Cloud provider clients → Cloud speech services: sends audio
- Cloud speech services → Cloud provider clients: returns speech
- Client factory → Local inference client: selects local
- Local inference client → Speech recognition: transcribes
- Local inference client → Text translation: translates text
- Local inference client → Speech synthesis: synthesizes speech
- Speech recognition → Local inference client: transcript
- Text translation → Local inference client: translated text
- Speech synthesis → Local inference client: audio output
- Local model management → Model store: manages models
- Model store → Speech recognition: provides models
- Model store → Text translation: provides models
- Model store → Speech synthesis: provides models
- Local inference client → Native inference sidecar: uses native engine
- Translation session → Conversation display: updates display
- Translation session → Live subtitles: updates subtitles
- Translation session → Translated audio: plays translated audio
- Translated audio → Virtual microphone: routes audio
- Desktop shell → System audio: hosts capture
- Browser extension → Meeting audio: hosts capture
- Live subtitles → Subtitle surfaces: renders on