# codandobrasil/snowspeak architecture

> Architecture diagram of the GitHub repository codandobrasil/snowspeak, 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/codandobrasil/snowspeak
- Repository: https://github.com/codandobrasil/snowspeak

## Overview

SnowSpeak is a browser extension for live English-to-Brazilian-Portuguese captions and user-triggered response suggestions during browser calls. The user configures provider keys and starts capture for the invoked tab; the extension captures tab audio and optionally microphone audio, transcribes through Deepgram, translates locally in Chrome, and displays captions. A separate suggestion flow sends conversation context to OpenRouter only on request. The conversation is retained for an in-browser PDF report. The graph reflects the README and sampled wiring; unsampled translation and view internals are represented at their documented module paths.

Main entry points: [`apps/extension/src/sidepanel/main.ts`](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/sidepanel/main.ts) (Side panel), [`apps/extension/src/offscreen/session-controller.ts`](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/session-controller.ts) (Session controller), [`packages/engine/src/local-session.ts`](https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/local-session.ts) (Local session), [`apps/extension/src/offscreen/session-store.ts`](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/session-store.ts) (Session state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_panel["Side panel<br/>[main.ts]"]
  node_caption_view["Caption and controls<br/>[caption-view.ts]"]
  node_report_model["Report model<br/>[report-model.ts]"]
  node_report_page["PDF report page<br/>[main.ts]"]
end

subgraph group_extension["Extension runtime"]
  node_background["Service worker<br/>[service-worker.ts]"]
  node_offscreen["Offscreen runtime<br/>[main.ts]"]
  node_controller["Session controller"]
  node_capture["Audio capture<br/>[capture.ts]"]
  node_audio["Audio framing<br/>[pcm.ts]"]
  node_store[("Session state<br/>[session-store.ts]")]
  node_translation["Translation queue"]
  node_conversation[("Conversation log")]
end

subgraph group_engine["Session engine"]
  node_session["Local session<br/>[local-session.ts]"]
  node_pipeline["Channel pipeline"]
  node_utterance["Utterance assembly"]
  node_suggestions["Suggestion engine"]
end

subgraph group_integrations["Providers and output"]
  node_deepgram["Deepgram STT"]
  node_openrouter["OpenRouter suggester<br/>[openrouter.ts]"]
  node_chrome_translate["Chrome translator"]
end

node_user(("User"))
node_chrome["Chrome browser APIs"]

node_user -->|"starts session"| node_panel
node_panel -->|"sends start"| node_background
node_background -->|"gets tab stream"| node_chrome
node_background -->|"dispatches start"| node_offscreen
node_panel -->|"stores settings"| node_chrome
node_controller -->|"starts capture"| node_capture
node_capture -->|"captures tab and mic"| node_chrome
node_capture -->|"frames audio"| node_audio
node_controller -->|"creates session"| node_session
node_controller -->|"updates state"| node_store
node_audio -->|"provides frames"| node_controller
node_controller -->|"forwards audio"| node_session
node_session -->|"routes channels"| node_pipeline
node_pipeline -->|"streams audio"| node_deepgram
node_pipeline -->|"assembles segments"| node_utterance
node_session -->|"records utterances"| node_suggestions
node_suggestions -.->|"streams requested suggestion"| node_openrouter
node_session -->|"emits engine events"| node_controller
node_offscreen -->|"handles engine events"| node_translation
node_translation -->|"translates locally"| node_chrome_translate
node_chrome_translate -->|"uses translation API"| node_chrome
node_translation -->|"updates captions"| node_store
node_offscreen -->|"broadcasts state"| node_store
node_store -->|"provides session state"| node_panel
node_store -->|"records conversation"| node_conversation
node_panel -->|"builds report"| node_report_model
node_panel -->|"requests history"| node_conversation
node_panel -->|"opens report page"| node_chrome
node_report_model -->|"stores report data"| node_chrome
node_report_page -->|"prints to PDF"| node_chrome
node_user -->|"prints report"| node_report_page
node_panel -->|"renders captions"| node_caption_view

click node_panel "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/sidepanel/main.ts"
click node_caption_view "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/sidepanel/caption-view.ts"
click node_report_model "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/sidepanel/report-model.ts"
click node_report_page "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/report/main.ts"
click node_background "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/background/service-worker.ts"
click node_offscreen "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/main.ts"
click node_controller "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/session-controller.ts"
click node_capture "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/capture.ts"
click node_audio "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/audio/pcm.ts"
click node_store "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/session-store.ts"
click node_translation "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/translation-queue.ts"
click node_conversation "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/conversation-log.ts"
click node_session "https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/local-session.ts"
click node_pipeline "https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/channel-pipeline.ts"
click node_utterance "https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/utterance-assembler.ts"
click node_suggestions "https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/suggest/suggestion-engine.ts"
click node_deepgram "https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/stt/deepgram-browser.ts"
click node_openrouter "https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/suggest/openrouter.ts"
click node_chrome_translate "https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/translation/chrome-translator.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_panel,node_caption_view,node_report_model,node_report_page,node_user,node_chrome toneBlue
class node_background,node_offscreen,node_controller,node_capture,node_audio,node_store,node_translation,node_conversation toneAmber
class node_session,node_pipeline,node_utterance,node_suggestions toneMint
class node_deepgram,node_openrouter,node_chrome_translate toneRose
```

## Components

### User interface

- [Side panel](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/sidepanel/main.ts): `apps/extension/src/sidepanel/main.ts`
- [Caption and controls](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/sidepanel/caption-view.ts): `apps/extension/src/sidepanel/caption-view.ts`
- [Report model](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/sidepanel/report-model.ts): `apps/extension/src/sidepanel/report-model.ts`
- [PDF report page](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/report/main.ts): `apps/extension/src/report/main.ts`

### Extension runtime

- [Service worker](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/background/service-worker.ts): `apps/extension/src/background/service-worker.ts`
- [Offscreen runtime](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/main.ts): `apps/extension/src/offscreen/main.ts`
- [Session controller](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/session-controller.ts): `apps/extension/src/offscreen/session-controller.ts`
- [Audio capture](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/capture.ts): `apps/extension/src/offscreen/capture.ts`
- [Audio framing](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/audio/pcm.ts): `apps/extension/src/audio/pcm.ts`
- [Session state](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/session-store.ts): `apps/extension/src/offscreen/session-store.ts`
- [Translation queue](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/translation-queue.ts): `apps/extension/src/offscreen/translation-queue.ts`
- [Conversation log](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/offscreen/conversation-log.ts): `apps/extension/src/offscreen/conversation-log.ts`

### Session engine

- [Local session](https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/local-session.ts): `packages/engine/src/local-session.ts`
- [Channel pipeline](https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/channel-pipeline.ts): `packages/engine/src/channel-pipeline.ts`
- [Utterance assembly](https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/utterance-assembler.ts): `packages/engine/src/utterance-assembler.ts`
- [Suggestion engine](https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/suggest/suggestion-engine.ts): `packages/engine/src/suggest/suggestion-engine.ts`

### Providers and output

- [Deepgram STT](https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/stt/deepgram-browser.ts): `packages/engine/src/stt/deepgram-browser.ts`
- [OpenRouter suggester](https://github.com/codandobrasil/snowspeak/blob/master/packages/engine/src/suggest/openrouter.ts): `packages/engine/src/suggest/openrouter.ts`
- [Chrome translator](https://github.com/codandobrasil/snowspeak/blob/master/apps/extension/src/translation/chrome-translator.ts): `apps/extension/src/translation/chrome-translator.ts`

### Other components

- **User**
- **Chrome browser APIs**

## Connections

- User → Side panel: starts session
- Side panel → Service worker: sends start
- Service worker → Chrome browser APIs: gets tab stream
- Service worker → Offscreen runtime: dispatches start
- Side panel → Chrome browser APIs: stores settings
- Session controller → Audio capture: starts capture
- Audio capture → Chrome browser APIs: captures tab and mic
- Audio capture → Audio framing: frames audio
- Session controller → Local session: creates session
- Session controller → Session state: updates state
- Audio framing → Session controller: provides frames
- Session controller → Local session: forwards audio
- Local session → Channel pipeline: routes channels
- Channel pipeline → Deepgram STT: streams audio
- Channel pipeline → Utterance assembly: assembles segments
- Local session → Suggestion engine: records utterances
- Suggestion engine → OpenRouter suggester: streams requested suggestion
- Local session → Session controller: emits engine events
- Offscreen runtime → Translation queue: handles engine events
- Translation queue → Chrome translator: translates locally
- Chrome translator → Chrome browser APIs: uses translation API
- Translation queue → Session state: updates captions
- Offscreen runtime → Session state: broadcasts state
- Session state → Side panel: provides session state
- Session state → Conversation log: records conversation
- Side panel → Report model: builds report
- Side panel → Conversation log: requests history
- Side panel → Chrome browser APIs: opens report page
- Report model → Chrome browser APIs: stores report data
- PDF report page → Chrome browser APIs: prints to PDF
- User → PDF report page: prints report
- Side panel → Caption and controls: renders captions