# sokmeankao/luma architecture

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

- Interactive diagram: https://gitdiagram.com/sokmeankao/luma
- Repository: https://github.com/sokmeankao/luma

## Overview

Luma captures browser-tab playback, obtains an ephemeral live-session credential, streams audio for Gemini Live Translate, and presents original and translated text; voice playback is optional. The web workspace owns the live-session orchestration, while a Go loopback API serves capabilities and mints credentials. Electron reuses that workspace and adds source selection, process-loopback support, and floating subtitles. The README documents a translation-provider package, but that package is absent from the supplied tree; provider internals are therefore represented as an external service. Connections reflect excerpts or explicit README statements.

Main entry points: [`apps/web/src/components/LiveWorkspace.tsx`](https://github.com/sokmeankao/luma/blob/main/apps/web/src/components/LiveWorkspace.tsx) (Live workspace), [`services/api/internal/httpapi/handlers.go`](https://github.com/sokmeankao/luma/blob/main/services/api/internal/httpapi/handlers.go) (API handlers), [`apps/desktop/src/renderer/src/App.tsx`](https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/renderer/src/App.tsx) (Desktop live app), [`apps/desktop/src/shared/ipc.ts`](https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/shared/ipc.ts) (Desktop IPC contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Live web experience"]
  node_home["Home mode<br/>[page.tsx]"]
  node_workspace["Live workspace<br/>[LiveWorkspace.tsx]"]
  node_language["Language selection"]
  node_language_catalog["Language catalog"]
  node_capture_panel["Capture controls<br/>[CapturePanel.tsx]"]
  node_transcript_ui["Shared transcript UI<br/>[index.tsx]"]
  node_preview["Transcript preview<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_audio["Audio capture and playback"]
  node_browser_capture["Browser capture<br/>[browser-capture.ts]"]
  node_audio_encoder["PCM encoding<br/>[encoder.ts]"]
  node_pcm_mime["PCM format tools<br/>[pcm-mime.ts]"]
  node_audio_player["Translated audio player"]
end

subgraph group_api["Local API"]
  node_api_server["API server<br/>[main.go]"]
  node_api_handlers["API handlers<br/>[handlers.go]"]
  node_language_rules["Language catalog<br/>[catalog.go]"]
end

subgraph group_desktop["Desktop companion"]
  node_desktop_app["Desktop live app<br/>[App.tsx]"]
  node_desktop_main["Electron main process<br/>[index.ts]"]
  node_desktop_preload["Desktop preload bridge<br/>[index.ts]"]
  node_desktop_picker["Source picker<br/>[pick-source.ts]"]
  node_desktop_audio["Windows audio host<br/>[win-audio-host.ts]"]
  node_ipc["Desktop IPC contract<br/>[ipc.ts]"]
  node_win_audio["Windows audio module<br/>[index.js]"]
end

node_user(("User"))
node_gemini{{"Gemini Live Translate"}}

node_user -->|"opens app"| node_home
node_home -->|"shows live mode"| node_workspace
node_workspace -->|"renders controls"| node_language
node_language -->|"derives language pairs"| node_language_catalog
node_workspace -.->|"renders controls"| node_capture_panel
node_workspace -->|"starts capture"| node_browser_capture
node_workspace -->|"uses audio tools"| node_audio_encoder
node_workspace -->|"requests capabilities and token"| node_api_client
node_api_client -->|"HTTP requests"| node_api_server
node_api_server -->|"creates server"| node_api_handlers
node_api_handlers -->|"validates language pairs"| node_language_rules
node_api_handlers -->|"mints temporary credential"| node_gemini
node_workspace -->|"streams live session"| node_gemini
node_workspace -->|"presents transcript"| node_transcript_ui
node_preview -->|"renders preview"| node_transcript_ui
node_workspace -.->|"plays translated voice"| node_audio_player
node_audio_player -->|"measures PCM duration"| node_pcm_mime
node_user -->|"uses desktop app"| node_desktop_app
node_desktop_app -->|"hosts live workspace"| node_workspace
node_desktop_app -->|"publishes transcript"| node_ipc
node_desktop_main -->|"registers IPC"| node_ipc
node_desktop_main -->|"starts audio host"| node_desktop_audio
node_desktop_audio -->|"uses process source selection"| node_desktop_picker
node_desktop_picker -->|"uses native audio module"| node_win_audio
node_desktop_preload -->|"exposes IPC API"| node_ipc

click node_home "https://github.com/sokmeankao/luma/blob/main/apps/web/src/app/page.tsx"
click node_workspace "https://github.com/sokmeankao/luma/blob/main/apps/web/src/components/LiveWorkspace.tsx"
click node_language "https://github.com/sokmeankao/luma/blob/main/apps/web/src/components/LanguagePairControls.tsx"
click node_language_catalog "https://github.com/sokmeankao/luma/blob/main/apps/web/src/lib/language-catalog.ts"
click node_capture_panel "https://github.com/sokmeankao/luma/blob/main/apps/web/src/components/CapturePanel.tsx"
click node_transcript_ui "https://github.com/sokmeankao/luma/blob/main/packages/ui/src/index.tsx"
click node_preview "https://github.com/sokmeankao/luma/blob/main/apps/web/src/app/preview/transcript/page.tsx"
click node_api_client "https://github.com/sokmeankao/luma/blob/main/apps/web/src/lib/api.ts"
click node_browser_capture "https://github.com/sokmeankao/luma/blob/main/packages/audio/src/browser-capture.ts"
click node_audio_encoder "https://github.com/sokmeankao/luma/blob/main/packages/audio/src/encoder.ts"
click node_pcm_mime "https://github.com/sokmeankao/luma/blob/main/packages/audio/src/pcm-mime.ts"
click node_audio_player "https://github.com/sokmeankao/luma/blob/main/packages/audio/src/translated-audio-player.ts"
click node_api_server "https://github.com/sokmeankao/luma/blob/main/services/api/cmd/server/main.go"
click node_api_handlers "https://github.com/sokmeankao/luma/blob/main/services/api/internal/httpapi/handlers.go"
click node_language_rules "https://github.com/sokmeankao/luma/blob/main/services/api/internal/languages/catalog.go"
click node_desktop_app "https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/renderer/src/App.tsx"
click node_desktop_main "https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/main/index.ts"
click node_desktop_preload "https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/preload/index.ts"
click node_desktop_picker "https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/main/pick-source.ts"
click node_desktop_audio "https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/main/win-audio-host.ts"
click node_ipc "https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/shared/ipc.ts"
click node_win_audio "https://github.com/sokmeankao/luma/blob/main/packages/win-audio/index.js"

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_home,node_workspace,node_language,node_language_catalog,node_capture_panel,node_transcript_ui,node_preview,node_api_client,node_user toneBlue
class node_browser_capture,node_audio_encoder,node_pcm_mime,node_audio_player toneAmber
class node_api_server,node_api_handlers,node_language_rules toneMint
class node_desktop_app,node_desktop_main,node_desktop_preload,node_desktop_picker,node_desktop_audio,node_ipc,node_win_audio toneRose
class node_gemini toneIndigo
```

## Components

### Live web experience

- [Home mode](https://github.com/sokmeankao/luma/blob/main/apps/web/src/app/page.tsx): `apps/web/src/app/page.tsx`
- [Live workspace](https://github.com/sokmeankao/luma/blob/main/apps/web/src/components/LiveWorkspace.tsx): `apps/web/src/components/LiveWorkspace.tsx`
- [Language selection](https://github.com/sokmeankao/luma/blob/main/apps/web/src/components/LanguagePairControls.tsx): `apps/web/src/components/LanguagePairControls.tsx`
- [Language catalog](https://github.com/sokmeankao/luma/blob/main/apps/web/src/lib/language-catalog.ts): `apps/web/src/lib/language-catalog.ts`
- [Capture controls](https://github.com/sokmeankao/luma/blob/main/apps/web/src/components/CapturePanel.tsx): `apps/web/src/components/CapturePanel.tsx`
- [Shared transcript UI](https://github.com/sokmeankao/luma/blob/main/packages/ui/src/index.tsx): `packages/ui/src/index.tsx`
- [Transcript preview](https://github.com/sokmeankao/luma/blob/main/apps/web/src/app/preview/transcript/page.tsx): `apps/web/src/app/preview/transcript/page.tsx`
- [API client](https://github.com/sokmeankao/luma/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### Audio capture and playback

- [Browser capture](https://github.com/sokmeankao/luma/blob/main/packages/audio/src/browser-capture.ts): `packages/audio/src/browser-capture.ts`
- [PCM encoding](https://github.com/sokmeankao/luma/blob/main/packages/audio/src/encoder.ts): `packages/audio/src/encoder.ts`
- [PCM format tools](https://github.com/sokmeankao/luma/blob/main/packages/audio/src/pcm-mime.ts): `packages/audio/src/pcm-mime.ts`
- [Translated audio player](https://github.com/sokmeankao/luma/blob/main/packages/audio/src/translated-audio-player.ts): `packages/audio/src/translated-audio-player.ts`

### Local API

- [API server](https://github.com/sokmeankao/luma/blob/main/services/api/cmd/server/main.go): `services/api/cmd/server/main.go`
- [API handlers](https://github.com/sokmeankao/luma/blob/main/services/api/internal/httpapi/handlers.go): `services/api/internal/httpapi/handlers.go`
- [Language catalog](https://github.com/sokmeankao/luma/blob/main/services/api/internal/languages/catalog.go): `services/api/internal/languages/catalog.go`

### Desktop companion

- [Desktop live app](https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/renderer/src/App.tsx): `apps/desktop/src/renderer/src/App.tsx`
- [Electron main process](https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/main/index.ts): `apps/desktop/src/main/index.ts`
- [Desktop preload bridge](https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/preload/index.ts): `apps/desktop/src/preload/index.ts`
- [Source picker](https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/main/pick-source.ts): `apps/desktop/src/main/pick-source.ts`
- [Windows audio host](https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/main/win-audio-host.ts): `apps/desktop/src/main/win-audio-host.ts`
- [Desktop IPC contract](https://github.com/sokmeankao/luma/blob/main/apps/desktop/src/shared/ipc.ts): `apps/desktop/src/shared/ipc.ts`
- [Windows audio module](https://github.com/sokmeankao/luma/blob/main/packages/win-audio/index.js): `packages/win-audio/index.js`

### Other components

- **User**
- **Gemini Live Translate**

## Connections

- User → Home mode: opens app (evidence: `README.md`)
- Home mode → Live workspace: shows live mode (evidence: `apps/web/src/app/page.tsx`)
- Live workspace → Language selection: renders controls (evidence: `apps/web/src/components/LiveWorkspace.tsx`)
- Language selection → Language catalog: derives language pairs (evidence: `apps/web/src/components/LanguagePairControls.tsx`)
- Live workspace → Capture controls: renders controls
- Live workspace → Browser capture: starts capture (evidence: `apps/web/src/components/LiveWorkspace.tsx`)
- Live workspace → PCM encoding: uses audio tools (evidence: `apps/web/src/components/LiveWorkspace.tsx`)
- Live workspace → API client: requests capabilities and token (evidence: `apps/web/src/components/LiveWorkspace.tsx`)
- API client → API server: HTTP requests (evidence: `apps/web/src/lib/api.ts`)
- API server → API handlers: creates server (evidence: `services/api/cmd/server/main.go`)
- API handlers → Language catalog: validates language pairs (evidence: `services/api/internal/httpapi/handlers.go`)
- API handlers → Gemini Live Translate: mints temporary credential (evidence: `services/api/internal/httpapi/handlers.go`)
- Live workspace → Gemini Live Translate: streams live session (evidence: `README.md`)
- Live workspace → Shared transcript UI: presents transcript (evidence: `README.md`)
- Transcript preview → Shared transcript UI: renders preview (evidence: `apps/web/src/app/preview/transcript/page.tsx`)
- Live workspace → Translated audio player: plays translated voice
- Translated audio player → PCM format tools: measures PCM duration (evidence: `packages/audio/src/translated-audio-player.ts`)
- User → Desktop live app: uses desktop app (evidence: `README.md`)
- Desktop live app → Live workspace: hosts live workspace (evidence: `apps/desktop/src/renderer/src/App.tsx`)
- Desktop live app → Desktop IPC contract: publishes transcript (evidence: `apps/desktop/src/renderer/src/App.tsx`)
- Electron main process → Desktop IPC contract: registers IPC (evidence: `apps/desktop/src/main/index.ts`)
- Electron main process → Windows audio host: starts audio host (evidence: `apps/desktop/src/main/index.ts`)
- Windows audio host → Source picker: uses process source selection (evidence: `apps/desktop/src/main/win-audio-host.ts`)
- Source picker → Windows audio module: uses native audio module (evidence: `apps/desktop/src/main/pick-source.ts`)
- Desktop preload bridge → Desktop IPC contract: exposes IPC API (evidence: `apps/desktop/src/preload/index.ts`)
