# breschio/drawbridge architecture

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

- Interactive diagram: https://gitdiagram.com/breschio/drawbridge
- Repository: https://github.com/breschio/drawbridge

## Overview

Drawbridge is a Chrome extension for turning browser-based UI feedback into project-local tasks that AI coding tools can process. The main flow is annotate a running page, capture context and a screenshot, save and sync tasks, then process them through the deployed bridge workflow. The graph also includes documented rectangle annotations, task-status tracking, project connection, workflow deployment, and legacy-file migration. Some subsystem links are based on README descriptions because the relevant implementation excerpts were incomplete.

Main entry points: [`chrome-extension/content_script.js`](https://github.com/breschio/drawbridge/blob/main/chrome-extension/content_script.js) (Annotation Capture), [`chrome-extension/background.js`](https://github.com/breschio/drawbridge/blob/main/chrome-extension/background.js) (Extension Toolbar), [`chrome-extension/utils/taskStore.js`](https://github.com/breschio/drawbridge/blob/main/chrome-extension/utils/taskStore.js) (Task Store), [`chrome-extension/moat.js`](https://github.com/breschio/drawbridge/blob/main/chrome-extension/moat.js) (Task Drawer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Browser Capture"]
  node_toolbar["Extension Toolbar<br/>[background.js]"]
  node_content["Annotation Capture<br/>[content_script.js]"]
  node_sidebar["Task Drawer<br/>[moat.js]"]
  node_screenshot["Screenshot Capture<br/>[background.js]"]
end

subgraph group_tasks["Task Management"]
  node_taskstore["Task Store<br/>[taskStore.js]"]
  node_migration["Legacy Migration"]
  node_markdown["Markdown Generator"]
  node_safe["Safe Local Storage<br/>[safeStorage.js]"]
end

subgraph group_project["Project Sync"]
  node_directory[("Connected Project Files")]
  node_handle[("Directory Handle Persistence<br/>[persistence.js]")]
end

subgraph group_agents["Agent Workflows"]
  node_templates["Workflow Templates"]
  node_bridge["Bridge Workflow<br/>[bridge.md]"]
end

node_user(("Developer"))
node_page["Running App"]
node_codingtool(("AI Coding Tool"))

node_user -->|"opens drawer"| node_toolbar
node_toolbar -->|"checks readiness"| node_content
node_toolbar -->|"toggles"| node_sidebar
node_user -->|"annotates UI"| node_content
node_content -->|"reads element context"| node_page
node_content -.->|"requests capture"| node_screenshot
node_screenshot -->|"captures visible tab"| node_page
node_content -->|"saves tasks"| node_taskstore
node_sidebar -.->|"displays task queue"| node_taskstore
node_content -->|"rebuilds task list"| node_markdown
node_taskstore -->|"reads and writes tasks"| node_directory
node_markdown -->|"writes task summary"| node_directory
node_user -->|"connects project"| node_handle
node_handle -->|"persists access handle"| node_directory
node_content -->|"deploys workflows"| node_templates
node_templates -->|"installs agent files"| node_directory
node_codingtool -->|"runs workflow"| node_bridge
node_bridge -->|"processes task files"| node_directory
node_migration -->|"converts legacy files"| node_directory
node_safe -.->|"stores local values"| node_directory

click node_toolbar "https://github.com/breschio/drawbridge/blob/main/chrome-extension/background.js"
click node_content "https://github.com/breschio/drawbridge/blob/main/chrome-extension/content_script.js"
click node_sidebar "https://github.com/breschio/drawbridge/blob/main/chrome-extension/moat.js"
click node_screenshot "https://github.com/breschio/drawbridge/blob/main/chrome-extension/background.js"
click node_taskstore "https://github.com/breschio/drawbridge/blob/main/chrome-extension/utils/taskStore.js"
click node_migration "https://github.com/breschio/drawbridge/blob/main/chrome-extension/utils/migrateLegacyFiles.js"
click node_markdown "https://github.com/breschio/drawbridge/blob/main/chrome-extension/utils/markdownGenerator.js"
click node_safe "https://github.com/breschio/drawbridge/blob/main/chrome-extension/utils/safeStorage.js"
click node_handle "https://github.com/breschio/drawbridge/blob/main/chrome-extension/utils/persistence.js"
click node_templates "https://github.com/breschio/drawbridge/tree/main/chrome-extension/rules-templates"
click node_bridge "https://github.com/breschio/drawbridge/blob/main/chrome-extension/rules-templates/bridge.md"

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_toolbar,node_content,node_sidebar,node_screenshot toneBlue
class node_taskstore,node_migration,node_markdown,node_safe toneAmber
class node_directory,node_handle toneMint
class node_templates,node_bridge toneRose
class node_user,node_page,node_codingtool toneIndigo
```

## Components

### Browser Capture

- [Extension Toolbar](https://github.com/breschio/drawbridge/blob/main/chrome-extension/background.js): `chrome-extension/background.js`
- [Annotation Capture](https://github.com/breschio/drawbridge/blob/main/chrome-extension/content_script.js): `chrome-extension/content_script.js`
- [Task Drawer](https://github.com/breschio/drawbridge/blob/main/chrome-extension/moat.js): `chrome-extension/moat.js`
- [Screenshot Capture](https://github.com/breschio/drawbridge/blob/main/chrome-extension/background.js): `chrome-extension/background.js`

### Task Management

- [Task Store](https://github.com/breschio/drawbridge/blob/main/chrome-extension/utils/taskStore.js): `chrome-extension/utils/taskStore.js`
- [Legacy Migration](https://github.com/breschio/drawbridge/blob/main/chrome-extension/utils/migrateLegacyFiles.js): `chrome-extension/utils/migrateLegacyFiles.js`
- [Markdown Generator](https://github.com/breschio/drawbridge/blob/main/chrome-extension/utils/markdownGenerator.js): `chrome-extension/utils/markdownGenerator.js`
- [Safe Local Storage](https://github.com/breschio/drawbridge/blob/main/chrome-extension/utils/safeStorage.js): `chrome-extension/utils/safeStorage.js`

### Project Sync

- **Connected Project Files**
- [Directory Handle Persistence](https://github.com/breschio/drawbridge/blob/main/chrome-extension/utils/persistence.js): `chrome-extension/utils/persistence.js`

### Agent Workflows

- [Workflow Templates](https://github.com/breschio/drawbridge/tree/main/chrome-extension/rules-templates): `chrome-extension/rules-templates`
- [Bridge Workflow](https://github.com/breschio/drawbridge/blob/main/chrome-extension/rules-templates/bridge.md): `chrome-extension/rules-templates/bridge.md`

### Other components

- **Developer**
- **Running App**
- **AI Coding Tool**

## Connections

- Developer → Extension Toolbar: opens drawer (evidence: `README.md`)
- Extension Toolbar → Annotation Capture: checks readiness (evidence: `chrome-extension/background.js`)
- Extension Toolbar → Task Drawer: toggles (evidence: `chrome-extension/background.js`)
- Developer → Annotation Capture: annotates UI (evidence: `README.md`)
- Annotation Capture → Running App: reads element context (evidence: `README.md`)
- Annotation Capture → Screenshot Capture: requests capture (evidence: `README.md`)
- Screenshot Capture → Running App: captures visible tab (evidence: `chrome-extension/background.js`)
- Annotation Capture → Task Store: saves tasks (evidence: `chrome-extension/content_script.js`)
- Task Drawer → Task Store: displays task queue (evidence: `README.md`)
- Annotation Capture → Markdown Generator: rebuilds task list (evidence: `chrome-extension/content_script.js`)
- Task Store → Connected Project Files: reads and writes tasks (evidence: `chrome-extension/utils/taskStore.js`)
- Markdown Generator → Connected Project Files: writes task summary (evidence: `chrome-extension/utils/markdownGenerator.js`)
- Developer → Directory Handle Persistence: connects project (evidence: `README.md`)
- Directory Handle Persistence → Connected Project Files: persists access handle (evidence: `chrome-extension/utils/persistence.js`)
- Annotation Capture → Workflow Templates: deploys workflows (evidence: `chrome-extension/content_script.js`)
- Workflow Templates → Connected Project Files: installs agent files (evidence: `README.md`)
- AI Coding Tool → Bridge Workflow: runs workflow (evidence: `README.md`)
- Bridge Workflow → Connected Project Files: processes task files (evidence: `README.md`)
- Legacy Migration → Connected Project Files: converts legacy files (evidence: `chrome-extension/utils/migrateLegacyFiles.js`)
- Safe Local Storage → Connected Project Files: stores local values