Architecture

Overview

Flower automation uses the Chrome DevTools Protocol (CDP) end-to-end. The gateway runs a loopback WebSocket relay (default 127.0.0.1:4323), and the Flower MV3 extension attaches chrome.debugger to a tab and forwards CDP requests/responses.

Gateway (Node)                    Extension (Flower)                 Chrome tab
  CDP relay WS  <--------------->  chrome.debugger.sendCommand  <-->  page
  + task loop        token            onEvent -> relay
  WebSocket /ws  (flower.register metadata only)

Components

Gateway (`apps/gateway`)

Express + WebSocket server. Handles job orchestration, chat routing, optional Discord hooks, codegen / code-executor paths, the CDP relay, and the browser agent loop (including Waggle).

Directory	Role
`src/server/`	API routes, stores, Discord flower manager, chat routing
`src/browser/`	CDP relay, Flower commands, Waggle, LLM client
`src/codegen/`	Code executor, project / subtask / process managers
`src/auth/`	Authentication, rate limiting
`src/settings/`	Persistent settings store

Web UI (`apps/web`)

Next.js dashboard. Pages include Dashboard, Districts (Jobs), Bridges, Approvals, Activity Log, AI History, Chat, Flowers, and Settings.

CLI (`apps/cli`)

Invoked via node beebridge.mjs at the repo root after npm run build:cli. Starts compiled gateway and production Next.js by default (--dev for development servers); also stop, gateway token, auth/model flows, and a keyboard-driven TUI. See the CLI reference.

Chrome Extension — Flower (`extension/`)

MV3 extension. Attaches chrome.debugger to a tab and relays CDP commands from the gateway. Maintains two tabs when Waggle is active: task tab (automation target) and pinned Waggle tab (web AI like ChatGPT / Claude).

Project Structure

beebridge/
├── apps/
│   ├── gateway/          # @beebridge/gateway
│   │   └── src/
│   │       ├── server/   # API, stores, chat routing
│   │       ├── browser/  # CDP relay, Flower, waggle, LLM
│   │       ├── codegen/  # Code executor, managers
│   │       ├── auth/
│   │       └── settings/
│   ├── web/              # @beebridge/web — Next.js dashboard
│   └── cli/              # @beebridge/cli — process helpers
├── extension/            # MV3 Flower — relay + chrome.debugger
├── packages/
│   ├── shared/           # @beebridge/shared — shared types
│   └── core/             # @beebridge/core — planner, approval gate, queue
├── docs/guides/
├── beebridge.mjs         # Root CLI loader
└── package.json          # Workspaces + scripts

Environment Variables

Variable	Default	Description
`beebridge_HOME`	(auto)	Repo root for spawned `npm run` commands from the CLI
`beebridge_GATEWAY_URL`	`http://localhost:4321`	Gateway HTTP base URL for CLI / TUI
`beebridge_GATEWAY_TOKEN`	(unset)	Bearer token; falls back to `GATEWAY_TOKEN` or `~/.beebridge/gateway-token`
`GATEWAY_TOKEN`	(auto-generated)	If unset, a token may be generated and saved under `~/.beebridge/gateway-token`
`PORT`	`4321`	Gateway HTTP port
`BEEBRIDGE_CDP_RELAY_PORT`	`PORT + 2`	Loopback CDP relay (e.g. `4323`)
`BEEBRIDGE_WEB_PORT`	`3000`	Shown in gateway help page for linking to the Next.js app
`GITHUB_CLIENT_ID`	—	GitHub OAuth app client ID (optional aliases: `BEEBRIDGE_GITHUB_CLIENT_ID`, `AIBRIDGE_GITHUB_CLIENT_ID`)
`NODE_TLS_REJECT_UNAUTHORIZED`	`1`	Set to `0` for dev only

Flower Commands

Command	Description
`navigate`	Open a URL
`click`	Click an element by selector
`type`	Type into an input
`read`	Read visible text
`scroll`	Scroll the page
`wait`	Wait for a duration
`ai_chat` / `ai_read_response`	Chat UI automation (often Waggle tab)
`screenshot`	Visible viewport capture

Overview

Components

Gateway (apps/gateway)

Web UI (apps/web)

CLI (apps/cli)

Chrome Extension — Flower (extension/)