# takagi/rofi-chrome-tab architecture

> Architecture diagram of the GitHub repository takagi/rofi-chrome-tab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/takagi/rofi-chrome-tab
- Repository: https://github.com/takagi/rofi-chrome-tab

## Overview

##### What this project is (type + purpose)
This repo is a **hybrid system** made of:
- a **Chrome Extension** (JS: `background.js`, `manifest.json`)
- a **native companion app** written in **Go** (`go/cmd/rofi-chrome-tab/main.go` + `go/internal/**`)
- a **Linux user workflow entrypoint** via **rofi** (`scripts/rofi-chrome-tab`) and config (`rofi_chrome_tab.sample.json`)

Purpose (from README + structure): **select/switch Chrome tabs from a rofi window**. That implies a **bridge** between Chrome (tab state + activation) and rofi (user selection UI).

The architecture strongly suggests **Chrome Native Messaging**:
- Chrome Extension ⇄ Native Host (Go) via stdin/stdout JSON messages
- rofi script ⇄ Go binary to display choices and execute the user’s selection

##### Chrome Extension side
- `manifest.json`: extension entrypoints + permissions (tabs, nativeMessaging, etc.)
- `background.js`: main extension runtime logic (listens to tab events, handles commands, talks to native host)

##### Go native host side
- `go/cmd/rofi-chrome-tab/main.go`: the runnable **native host** executable (the process Chrome spawns)
- `go/internal/command_receiver/**`: logic handling inbound “commands” (from rofi or from extension depending on protocol)
- `go/internal/event_receiver/**`: logic handling inbound “events” (tab updates, focus changes, etc.)
- `go/internal/protocol/**`: message schema (commands/events/actions/types) — this is the **contract** between extension and native host
- `go/internal/logging/**`, `go/internal/debug/**`: cross-cutting concerns (annotate as side concerns, not main containers)

##### Rofi / shell integration
- `scripts/rofi-chrome-tab`: user-invoked wrapper; likely runs `rofi`, calls the Go binary, formats output, etc.
- `rofi_chrome_tab.sample.json`: runtime configuration (paths, formatting, filters, etc.)

##### DevOps / QA

**Goal:** show who uses it and what systems it touches.

##### Native Host: `rofi-chrome-tab` (Go binary)

- User → Rofi: “invokes rofi-chrome-tab”
- Rofi → Script (`scripts/rofi-chrome-tab`): “runs wrapper”
- Script → Go native host: “request tab list / send selection”
- Chrome Extension ↔ Go native host: “Native Messaging JSON protocol”
- Chrome Extension → Chrome Tabs API: “list tabs / activate tab / listen to tab events”

**Notes to annotate:**
- Boundary: “Chrome extension sandbox” vs “local OS process”
- Communication channel: “Native Messaging (stdin/stdout JSON)”

**Goal:** show actual running processes and how data flows.

##### Extension → Chrome Tabs API: activates the selected tab

- Extension → Go host: “tab created/updated/removed/activated events” (stream)
- Go host: maintains in-memory view to serve rofi quickly

**Goal:** reflect the Go module boundaries from `go/internal/**`.

- **App Orchestrator** (`internal/app`)
- **Event Receiver** (`internal/event_receiver`)
- **Command Receiver** (`internal/command_receiver`)
- **Protocol Model / Codec** (`internal/protocol`)
- **Logging / Debug** (`internal/logging`, `internal/debug`)

- Receivers → Protocol: “decode/encode JSON messages”
- App ↔ Receivers: “register handlers / dispatch messages”
- App → Logging/Debug: “instrumentation”

Inside the **Chrome Extension** container, optionally break down:
- “Tab Event Listeners” (Chrome tabs events)
- “Native Messaging Client” (connect + send/receive)
- “Command Handler” (activate tab, focus window, etc.)

This gives a principal-engineer-level view grounded directly in directories/files.

##### Relationships and interactions to emphasize (project-specific)
- **The protocol contract** (`go/internal/protocol/*`) as a first-class element
- **Two-way messaging** (commands vs events)
- **Trust boundary + permissions**:
- Chrome extension permissions / APIs
- Native host running on OS (filesystem, processes)
- **User interaction loop**: rofi is the UI, Chrome is the target system

##### What “very detailed” means for this project (without overthinking)
To maximize accuracy, include:
- Both message directions: **Events** (Extension → Go) and **Commands** (Go → Extension)
- The script and rofi as explicit nodes (they’re essential to the user-facing behavior)
- The protocol package as the shared schema node
- A short note: “transport = Chrome Native Messaging over stdin/stdout”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% A) System Context Diagram
    %% =========================
    subgraph "A) System Context (External View)"
        direction TB

        User["User"]:::external

        subgraph "Local Machine / OS Boundary"
            direction TB
            Rofi["Rofi (Linux window switcher)"]:::external
            Wrapper["rofi-chrome-tab wrapper (shell script)"]:::script
            Config["Runtime config (JSON)"]:::config
            NativeHost["Native Host: rofi-chrome-tab (Go binary)"]:::process
        end

        subgraph "Chrome Browser Boundary"
            direction TB
            Chrome["Chrome Browser"]:::external
            Ext["Rofi Chrome Tab Extension"]:::process
            TabsAPI["Chrome Tabs API"]:::external
        end

        User -->|"invokes rofi-chrome-tab"| Rofi
        Rofi -->|"runs wrapper"| Wrapper
        Wrapper -->|"reads config"| Config
        Wrapper -->|"request tab list / send selection"| NativeHost

        Ext -->|"list/activate/listen to tab events"| TabsAPI
        Ext <-->|"Native Messaging JSON (stdin/stdout)"| NativeHost
        Chrome --- Ext
    end

    %% ==================================
    %% B) Container Diagram (Runtime + IPC)
    %% ==================================
    subgraph "B) Container Diagram (Runtime Processes + IPC)"
        direction TB

        User2["User"]:::external

        subgraph "Local Machine / OS (Runtime)"
            direction TB
            Wrapper2["scripts/rofi-chrome-tab"]:::script
            RofiUI["Rofi UI process"]:::process
            Config2["rofi_chrome_tab*.json"]:::config
            GoHost["Native Messaging Host process (Go)"]:::process
        end

        subgraph "Chrome (Runtime)"
            direction TB
            Bg["Extension background runtime (background.js)"]:::process
            TabsAPI2["Chrome Tabs API"]:::external
        end

        User2 -->|"1)run keybinding/command"| Wrapper2
        Wrapper2 -->|"2)spawn UI"| RofiUI
        Wrapper2 -->|"reads"| Config2

        Wrapper2 -->|"2)query candidates"| GoHost
        GoHost -->|"4)return formatted list"| Wrapper2
        RofiUI -->|"5)user selection (tab id/window id)"| Wrapper2
        Wrapper2 -->|"5)send selection"| GoHost

        GoHost <-->|"3)tab list request/response"| Bg
        Bg -->|"7)activate tab"| TabsAPI2

        %% Event-driven cache (ongoing)
        Bg -->|"tab change events (created/updated/removed/activated)"| GoHost
        GoHost -->|"6)activate tab command"| Bg
    end

    %% ==================================================
    %% C) Component Diagram (Go Native Host Internals + Protocol)
    %% ==================================================
    subgraph "C) Component Diagram (Inside Go Native Host)"
        direction TB

        subgraph "Go Native Host Container"
            direction TB

            MainGo["cmd/rofi-chrome-tab (main)"]:::process
            App["App Orchestrator (internal/app)"]:::module

            subgraph "Receivers"
                direction TB
                CmdRx["Command Receiver (internal/command_receiver)"]:::module
                EvtRx["Event Receiver (internal/event_receiver)"]:::module
            end

            subgraph "Protocol Contract"
                direction TB
                ProtocolDir["Protocol package (internal/protocol)"]:::module
                Action["Action model"]:::module
                Command["Command model"]:::module
                Event["Event model"]:::module
                Types["Shared types"]:::module
            end

            subgraph "Cross-cutting"
                direction TB
                Logging["Logging"]:::support
                Debug["Debug utilities"]:::support
            end
        end

        %% Internal wiring
        MainGo -->|"bootstraps"| App
        App -->|"register handlers / dispatch"| CmdRx
        App -->|"register handlers / dispatch"| EvtRx

        CmdRx -->|"decode/encode JSON"| ProtocolDir
        EvtRx -->|"decode/encode JSON"| ProtocolDir

        ProtocolDir -->|"defines"| Action
        ProtocolDir -->|"defines"| Command
        ProtocolDir -->|"defines"| Event
        ProtocolDir -->|"defines"| Types

        App -->|"instrumentation"| Logging
        App -->|"diagnostics"| Debug
        CmdRx -->|"logs"| Logging
        EvtRx -->|"logs"| Logging
    end

    %% ======================
    %% DevOps / CI (Optional)
    %% ======================
    subgraph "DevOps / QA"
        direction TB
        CI["GitHub Actions CI (Go build/test)"]:::devops
    end

    %% =============
    %% Click Events
    %% =============
    click Wrapper "https://github.com/takagi/rofi-chrome-tab/tree/main/scripts/rofi-chrome-tab"
    click Wrapper2 "https://github.com/takagi/rofi-chrome-tab/tree/main/scripts/rofi-chrome-tab"
    click Config "https://github.com/takagi/rofi-chrome-tab/blob/main/rofi_chrome_tab.sample.json"
    click Config2 "https://github.com/takagi/rofi-chrome-tab/blob/main/rofi_chrome_tab.sample.json"

    click Bg "https://github.com/takagi/rofi-chrome-tab/blob/main/background.js"
    click Ext "https://github.com/takagi/rofi-chrome-tab/blob/main/manifest.json"
    click MainGo "https://github.com/takagi/rofi-chrome-tab/blob/main/go/cmd/rofi-chrome-tab/main.go"
    click App "https://github.com/takagi/rofi-chrome-tab/blob/main/go/internal/app/app.go"
    click CmdRx "https://github.com/takagi/rofi-chrome-tab/blob/main/go/internal/command_receiver/receiver.go"
    click EvtRx "https://github.com/takagi/rofi-chrome-tab/blob/main/go/internal/event_receiver/receiver.go"

    click ProtocolDir "https://github.com/takagi/rofi-chrome-tab/tree/main/go/internal/protocol/"
    click Action "https://github.com/takagi/rofi-chrome-tab/blob/main/go/internal/protocol/action.go"
    click Command "https://github.com/takagi/rofi-chrome-tab/blob/main/go/internal/protocol/command.go"
    click Event "https://github.com/takagi/rofi-chrome-tab/blob/main/go/internal/protocol/event.go"
    click Types "https://github.com/takagi/rofi-chrome-tab/blob/main/go/internal/protocol/types.go"

    click Logging "https://github.com/takagi/rofi-chrome-tab/blob/main/go/internal/logging/logging.go"
    click Debug "https://github.com/takagi/rofi-chrome-tab/blob/main/go/internal/debug/debug.go"

    click CI "https://github.com/takagi/rofi-chrome-tab/blob/main/.github/workflows/go-ci.yml"

    click Ext "https://github.com/takagi/rofi-chrome-tab/blob/main/manifest.json"

    %% ======
    %% Styles
    %% ======
    classDef external fill:#ECEFF4,stroke:#4C566A,color:#2E3440,stroke-width:1px;
    classDef process fill:#5E81AC,stroke:#2E3440,color:#ECEFF4,stroke-width:1px;
    classDef module fill:#A3BE8C,stroke:#2E3440,color:#2E3440,stroke-width:1px;
    classDef support fill:#88C0D0,stroke:#2E3440,color:#2E3440,stroke-width:1px;
    classDef script fill:#EBCB8B,stroke:#2E3440,color:#2E3440,stroke-width:1px;
    classDef config fill:#D08770,stroke:#2E3440,color:#2E3440,stroke-width:1px;
    classDef devops fill:#B48EAD,stroke:#2E3440,color:#ECEFF4,stroke-width:1px;
```
