# williamkapke/kapture architecture

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

- Interactive diagram: https://gitdiagram.com/williamkapke/kapture
- Repository: https://github.com/williamkapke/kapture

## Overview

##### Project type and purpose
- This is a full-stack browser-automation system comprised of:
- A Chrome DevTools Extension (“extension/”) that exposes a DevTools panel and background/content scripts for automating browser actions via the Chrome DevTools Protocol.
- An MCP Server (“server/”) implemented in TypeScript/Node.js that speaks the Model Context Protocol over WebSocket and manages browser tabs, commands, and resources.
- A Test Electron App (“test-app/”) as a sample client to launch and test the extension and server integration.
- End-to-end tests (“e2e/”) validating the extension’s automation commands.
- A static Website (“website/”) for documentation and usage guides.

##### File structure
- Top-level directories:
- extension/ – manifest.json, background.js, content-script, DevTools panel HTML/CSS/JS, a modular “modules/” folder for individual automation commands (click, fill, screenshot, etc.).
- server/ – a CLI entry (cli.ts), WebSocket transport (websocket-transport.ts), MCP handlers (browser-command-handler.ts, tool-handler.ts), tab registry/manager, YAML loaders, static assets (`static/`).
- test-app/ – Electron entry (main.js), preload script, renderer UI, demo of stdio↔WebSocket bridge.
- e2e/ – Mocha tests driving the extension via a headless Chrome instance.
- .github/ – CI/CD workflows for building/publishing the extension and site.

##### Key insights from the README
- Three-layer architecture:
1. Chrome Extension (DevTools panel + background script)
2. WebSocket Bridge (in server or via CLI “bridge” command)
3. MCP Server (handles protocol, tools, tab registry)
- Supports multiple AI clients (Claude Desktop, Cline, etc.) connecting concurrently.
- No external database; state is held in‐memory in the tab registry.
- Commands are modular and pluggable (each tool implementation in `extension/modules` and `server/src`).

##### Final advice
- Be exhaustive: break out the individual server modules (websocket manager, CLI, tool handlers, YAML loader) and extension modules.
- Multi-client connectivity: show multiple AI clients converging on the same WebSocket endpoint.
- Both control flow (commands) and event flow (notifications).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Extension Layer
    subgraph "Browser Extension Layer"
        direction TB
        Panel["DevTools Panel UI"]:::ext
        Background["Background Script"]:::ext
        Content["Content Script"]:::ext
        subgraph "Extension Modules"
            direction TB
            modClick["Click Module"]:::ext
            modFill["Fill Module"]:::ext
            modScreenshot["Screenshot Module"]:::ext
        end
        subgraph "Extension Helpers"
            direction TB
            pageHelpers["Page Helpers"]:::ext
            tabManager["Tab Manager"]:::ext
            tabState["Tab State"]:::ext
        end
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        BridgeCommand["Bridge Command"]:::trans
        WebSocketTrans["WebSocket Transport"]:::trans
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        CLI["CLI Entry"]:::srv
        Setup["Setup"]:::srv
        Index["Server Start (index.ts)"]:::srv

        subgraph "Transport & Manager"
            direction TB
            WSManager["Browser WebSocket Manager"]:::srv
        end

        subgraph "Protocol Handlers"
            direction TB
            BCommand["Browser Command Handler"]:::srv
            ToolHandler["Tool Handler"]:::srv
            MCPManager["MCP Server Manager"]:::srv
        end

        subgraph "Tab Registry"
            direction TB
            TabRegistry["Tab Registry"]:::srv
            TabUtils["Tab Utils"]:::srv
        end

        subgraph "Resource & YAML Loaders"
            direction TB
            ResourceHandler["Resource Handler"]:::srv
            YAMLLoader["YAML Loader"]:::srv
        end

        subgraph "Static Assets"
            direction TB
            StaticWelcome["welcome.html"]:::srv
            StaticTest["test.html"]:::srv
        end
    end

    %% AI Clients & Test App
    subgraph "AI Clients & Test App"
        direction TB
        Claude["Claude Desktop"]:::client
        Cline["Cline"]:::client
        TestApp["Test Electron App"]:::client
    end

    %% Connections
    Panel -->|"commands"| Background
    Background -->|"MCP JSON over WebSocket"| WebSocketTrans
    BridgeCommand -->|"stdio↔WebSocket"| WebSocketTrans
    WebSocketTrans -->|"WebSocket connect"| WSManager
    CLI --> Setup --> Index
    Index --> WSManager
    WSManager --> BCommand
    WSManager --> ToolHandler
    BCommand --> TabRegistry
    ToolHandler --> TabRegistry
    TabRegistry --> TabUtils
    ToolHandler --> ResourceHandler
    ResourceHandler --> YAMLLoader
    Index --> StaticWelcome
    Index --> StaticTest
    WSManager -->|"notifications/events"| Background
    WSManager -->|"notifications/events"| Claude
    WSManager -->|"notifications/events"| Cline
    WSManager -->|"notifications/events"| TestApp
    Background -->|"DevTools Protocol"| Content
    Background --> modClick
    Background --> modFill
    Background --> modScreenshot
    Content -->|"exec commands"| modClick
    Content --> modFill
    Content --> modScreenshot
    pageHelpers --> Content
    tabManager --> TabRegistry
    tabState --> TabRegistry

    %% Click Events
    click Panel "https://github.com/williamkapke/kapture/blob/master/extension/devtools.html"
    click Panel "https://github.com/williamkapke/kapture/blob/master/extension/panel.html"
    click Background "https://github.com/williamkapke/kapture/blob/master/extension/background.js"
    click Content "https://github.com/williamkapke/kapture/blob/master/extension/content-script.js"
    click modClick "https://github.com/williamkapke/kapture/blob/master/extension/modules/background-click.js"
    click modFill "https://github.com/williamkapke/kapture/blob/master/extension/modules/background-fill.js"
    click modScreenshot "https://github.com/williamkapke/kapture/blob/master/extension/modules/background-screenshot.js"
    click pageHelpers "https://github.com/williamkapke/kapture/blob/master/extension/page-helpers.js"
    click tabManager "https://github.com/williamkapke/kapture/blob/master/extension/modules/tab-manager.js"
    click tabState "https://github.com/williamkapke/kapture/blob/master/extension/modules/tab-state.js"
    click BridgeCommand "https://github.com/williamkapke/kapture/blob/master/server/src/bridge.ts"
    click WebSocketTrans "https://github.com/williamkapke/kapture/blob/master/server/src/websocket-transport.ts"
    click CLI "https://github.com/williamkapke/kapture/blob/master/server/src/cli.ts"
    click Setup "https://github.com/williamkapke/kapture/blob/master/server/src/setup.ts"
    click Index "https://github.com/williamkapke/kapture/blob/master/server/src/index.ts"
    click WSManager "https://github.com/williamkapke/kapture/blob/master/server/src/browser-websocket-manager.ts"
    click BCommand "https://github.com/williamkapke/kapture/blob/master/server/src/browser-command-handler.ts"
    click ToolHandler "https://github.com/williamkapke/kapture/blob/master/server/src/tool-handler.ts"
    click TabRegistry "https://github.com/williamkapke/kapture/blob/master/server/src/tab-registry.ts"
    click TabUtils "https://github.com/williamkapke/kapture/blob/master/server/src/tab-utils.ts"
    click ResourceHandler "https://github.com/williamkapke/kapture/blob/master/server/src/resource-handler.ts"
    click YAMLLoader "https://github.com/williamkapke/kapture/blob/master/server/src/yaml-loader.ts"
    click StaticWelcome "https://github.com/williamkapke/kapture/blob/master/server/static/welcome.html"
    click StaticTest "https://github.com/williamkapke/kapture/blob/master/server/static/test.html"
    click TestApp "https://github.com/williamkapke/kapture/blob/master/test-app/main.js"

    %% Styles
    classDef ext fill:#BBDEFB,stroke:#0D47A1;
    classDef trans fill:#C8E6C9,stroke:#1B5E20;
    classDef srv fill:#A5D6A7,stroke:#2E7D32;
    classDef client fill:#FFE0B2,stroke:#E65100;
```
