# stefanbringuier/omarchy-notebooklm-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/stefanbringuier/omarchy-notebooklm-bridge
- Repository: https://github.com/stefanbringuier/omarchy-notebooklm-bridge

## Overview

NotebookLM Bridge is an Omarchy bar-widget that lets users list notebooks, add sources, and ask questions through an experimental unofficial CLI, with browser handoff as a fallback. The widget sends requests to a local NDJSON dispatcher; source additions are validated before backend dispatch, and responses return to the panel. Handoff opens the notebook and may copy a source, but does not upload files or submit questions. The README documents the UI capabilities; sampled QML was unavailable, so internal UI wiring is shown only at the documented panel-to-dispatcher boundary.

Main entry points: [`notebook_bridge/dispatcher.py`](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/dispatcher.py) (Operation router), [`Panel.qml`](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/Panel.qml) (Notebook panel), [`bin/notebook_bridge.py`](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/bin/notebook_bridge.py) (Dispatcher entry), [`notebook_bridge/handoff.py`](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/handoff.py) (Browser handoff)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Widget interface"]
  node_bar["Bar widget<br/>[BarWidget.qml]"]
  node_panel["Notebook panel<br/>[Panel.qml]"]
  node_add["Add sources<br/>[AddView.qml]"]
  node_ask["Ask question<br/>[AskView.qml]"]
  node_picker["Notebook picker<br/>[NotebookPicker.qml]"]
  node_results["Results view<br/>[ResultView.qml]"]
  node_settings["Settings and login<br/>[SettingsView.qml]"]
  node_files["File browser<br/>[FileBrowser.qml]"]
  node_history["History view<br/>[HistoryView.qml]"]
end

subgraph group_dispatch["Local dispatcher"]
  node_entry["Dispatcher entry<br/>[notebook_bridge.py]"]
  node_protocol["NDJSON protocol<br/>[protocol.py]"]
  node_router["Operation router<br/>[dispatcher.py]"]
  node_validation["Input preflight<br/>[validation.py]"]
  node_registry["Backend registry<br/>[adapters.py]"]
end

subgraph group_backends["Notebook backends"]
  node_cli["Consumer CLI adapter<br/>[consumer_cli.py]"]
  node_handoff["Browser handoff<br/>[handoff.py]"]
end

subgraph group_state["Configuration and state"]
  node_config["Config and aliases<br/>[config.py]"]
  node_receipts["Receipt writer<br/>[receipts.py]"]
end

node_user(("User"))
node_notebooklm["notebooklm CLI"]
node_google["NotebookLM service"]
node_browser["Browser and clipboard"]
node_configfile[("User config")]
node_receiptfile[("Receipt log")]

node_user -->|"opens"| node_bar
node_bar -->|"opens"| node_panel
node_panel -->|"selects Add"| node_add
node_panel -->|"selects Ask"| node_ask
node_panel -->|"opens settings"| node_settings
node_panel -->|"selects notebook"| node_picker
node_add -->|"stages files"| node_files
node_add -->|"sends request"| node_entry
node_ask -->|"sends request"| node_entry
node_settings -->|"sends login request"| node_entry
node_picker -->|"requests notebooks"| node_entry
node_history -.->|"shows view"| node_panel
node_entry -->|"parses request"| node_protocol
node_entry -->|"dispatches request"| node_router
node_router -->|"loads preferences"| node_config
node_config -->|"reads and writes"| node_configfile
node_router -->|"preflights sources"| node_validation
node_router -->|"selects backend"| node_registry
node_registry -->|"registers handler"| node_cli
node_registry -->|"registers handler"| node_handoff
node_router -->|"dispatches CLI operation"| node_cli
node_cli -->|"runs commands"| node_notebooklm
node_notebooklm -.->|"accesses notebooks"| node_google
node_router -->|"dispatches fallback"| node_handoff
node_handoff -->|"opens notebook"| node_browser
node_handoff -.->|"copies source"| node_browser
node_router -->|"records outcome"| node_receipts
node_receipts -->|"appends metadata"| node_receiptfile
node_entry -->|"returns response"| node_results
node_results -->|"renders outcome"| node_panel

click node_bar "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/BarWidget.qml"
click node_panel "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/Panel.qml"
click node_add "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/AddView.qml"
click node_ask "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/AskView.qml"
click node_picker "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/NotebookPicker.qml"
click node_results "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/ResultView.qml"
click node_settings "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/SettingsView.qml"
click node_files "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/FileBrowser.qml"
click node_history "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/HistoryView.qml"
click node_entry "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/bin/notebook_bridge.py"
click node_protocol "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/protocol.py"
click node_router "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/dispatcher.py"
click node_validation "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/validation.py"
click node_registry "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/adapters.py"
click node_cli "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/consumer_cli.py"
click node_handoff "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/handoff.py"
click node_config "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/config.py"
click node_receipts "https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/receipts.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_bar,node_panel,node_add,node_ask,node_picker,node_results,node_settings,node_files,node_history,node_user,node_browser toneBlue
class node_entry,node_protocol,node_router,node_validation,node_registry,node_configfile,node_receiptfile toneAmber
class node_cli,node_handoff toneMint
class node_config,node_receipts toneRose
class node_notebooklm,node_google toneIndigo
```

## Components

### Widget interface

- [Bar widget](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/BarWidget.qml): `BarWidget.qml`
- [Notebook panel](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/Panel.qml): `Panel.qml`
- [Add sources](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/AddView.qml): `components/AddView.qml`
- [Ask question](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/AskView.qml): `components/AskView.qml`
- [Notebook picker](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/NotebookPicker.qml): `components/NotebookPicker.qml`
- [Results view](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/ResultView.qml): `components/ResultView.qml`
- [Settings and login](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/SettingsView.qml): `components/SettingsView.qml`
- [File browser](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/FileBrowser.qml): `components/FileBrowser.qml`
- [History view](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/components/HistoryView.qml): `components/HistoryView.qml`

### Local dispatcher

- [Dispatcher entry](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/bin/notebook_bridge.py): `bin/notebook_bridge.py`
- [NDJSON protocol](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/protocol.py): `notebook_bridge/protocol.py`
- [Operation router](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/dispatcher.py): `notebook_bridge/dispatcher.py`
- [Input preflight](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/validation.py): `notebook_bridge/validation.py`
- [Backend registry](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/adapters.py): `notebook_bridge/adapters.py`

### Notebook backends

- [Consumer CLI adapter](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/consumer_cli.py): `notebook_bridge/consumer_cli.py`
- [Browser handoff](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/handoff.py): `notebook_bridge/handoff.py`

### Configuration and state

- [Config and aliases](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/config.py): `notebook_bridge/config.py`
- [Receipt writer](https://github.com/stefanbringuier/omarchy-notebooklm-bridge/blob/main/notebook_bridge/receipts.py): `notebook_bridge/receipts.py`

### Other components

- **User**
- **notebooklm CLI**
- **NotebookLM service**
- **Browser and clipboard**
- **User config**
- **Receipt log**

## Connections

- User → Bar widget: opens
- Bar widget → Notebook panel: opens
- Notebook panel → Add sources: selects Add
- Notebook panel → Ask question: selects Ask
- Notebook panel → Settings and login: opens settings
- Notebook panel → Notebook picker: selects notebook
- Add sources → File browser: stages files
- Add sources → Dispatcher entry: sends request
- Ask question → Dispatcher entry: sends request
- Settings and login → Dispatcher entry: sends login request
- Notebook picker → Dispatcher entry: requests notebooks
- History view → Notebook panel: shows view
- Dispatcher entry → NDJSON protocol: parses request
- Dispatcher entry → Operation router: dispatches request
- Operation router → Config and aliases: loads preferences
- Config and aliases → User config: reads and writes
- Operation router → Input preflight: preflights sources
- Operation router → Backend registry: selects backend
- Backend registry → Consumer CLI adapter: registers handler
- Backend registry → Browser handoff: registers handler
- Operation router → Consumer CLI adapter: dispatches CLI operation
- Consumer CLI adapter → notebooklm CLI: runs commands
- notebooklm CLI → NotebookLM service: accesses notebooks
- Operation router → Browser handoff: dispatches fallback
- Browser handoff → Browser and clipboard: opens notebook
- Browser handoff → Browser and clipboard: copies source
- Operation router → Receipt writer: records outcome
- Receipt writer → Receipt log: appends metadata
- Dispatcher entry → Results view: returns response
- Results view → Notebook panel: renders outcome