How aeroxy/web-bro works
1. System shape
- This is a static, browser-only agent workspace. There is no application backend.
- The app runs as a Vite-built React SPA, with the heavy work split into Web Workers so the UI stays responsive.
2. Primary UI shell
- src/main.tsx boots the app into src/app/App.tsx.
- The visible product is composed from feature panels: chat, workspace, log, and debug.
- Shared UI components such as the file tree, markdown rendering, thread sidebar, and capability gating are factored under src/components.
3. Central orchestration boundary
- src/app/store.ts is the main coordination layer.
- It holds application state, wires persistence, and orchestrates the agent loop across the UI, the model worker, and the workspace worker.
- For an architecture diagram, this is the best place to draw the “brain” of the app.
4. Model execution boundary
- src/workers/llm.worker.ts is responsible for loading and running the Gemma 4 E2B-it ONNX model in-browser via WebGPU.
- It handles prompt formatting, native tool-call prompting, streamed model output, and cancellation.
- The model artifacts are fetched from Hugging Face on first use and then cached locally by the browser.
5. Workspace / filesystem boundary
- src/workers/workspace.worker.ts owns interaction with the user-selected local folder.
- It performs directory traversal, file reads, text search, writes, and support for restoring overwritten content.
- This worker is the bridge to the File System Access API, so file operations are isolated from the main UI thread.
6. Agent tool loop
- The agent uses a shallow tool loop with four core actions: list_dir, search_text, read_file, and write_file.
- The store mediates the turn sequence: user input → model reasoning/tool request → workspace worker execution → updated context → final model answer.
- The readme note that existing files must be read before overwrite is an important behavioral constraint in this loop.
7. Persistence model
- src/lib/db.ts and related code persist data in IndexedDB only.
- Stored locally are chat threads, workspace sessions, settings, and write backups used for undo.
- This means the app has two local state domains: the selected workspace on disk, and the app’s own durable metadata in browser storage.
8. Undo and write safety
- File writes are not blind mutations: the previous file contents are snapshotted before overwrite.
- That backup enables the one-click undo flow described in the README and supported by the workspace worker and persistence layer.
- This is a key architectural boundary between “agent can modify files” and “user can recover prior state.”
9. Capability and environment gating
- src/components/CapabilityGate.tsx plus src/lib/capabilities.ts guard features that depend on browser support.
- The product is explicitly Chromium-first, requiring a secure context, WebGPU, and the File System Access API.
- This gating matters architecturally because large parts of the app are unavailable without those browser capabilities.
10. Shared data contracts and prompt shaping
- src/lib/contracts.ts, src/lib/chatml.ts, and src/lib/agent-prompt.ts define the message shapes and prompt format passed between UI, store, and worker.
- These files are the “schema boundary” that keeps the worker protocol, chat history, and tool-loop messaging consistent.
- src/lib/text.ts and other helpers support parsing and presentation rather than core orchestration.
11. Observability and diagnostics
- The log and debug feature panels provide runtime visibility into agent behavior, worker activity, and workspace state.
- This is useful in the diagram as a non-functional side channel off the main orchestration path.
12. Deployment and delivery
- The app is deployed as a static site, with public/_headers and public/_redirects supporting Cloudflare Pages-style hosting.
- There is no server-side rendering or API backend; all compute is client-side, and all persistence is local to the browser/device.
13. Testing boundaries
- Unit tests use mocked workers, so the normal test suite does not require the real model download.
- Playwright end-to-end tests cover the browser flow separately.
- This reinforces the repo’s main architectural split: pure UI/state logic vs. worker-backed runtime behavior.
Main entry points: store.ts Store · App.tsx App shell · ChatPanel.tsx Chat · llm.worker.ts LLM worker
Components 27
UI shell
React app entry, shell, and feature panels.
- Main · Bootstraps the React app.
src/main.tsx - App shell · Top-level composition of the visible workspace.
src/app/App.tsx - Store · Coordinates agent turns, state, persistence, and worker traffic.
src/app/store.ts - Chat · Conversation and agent interaction panel.
src/features/chat/ChatPanel.tsx - Workspace · Local folder and file-operation panel.
src/features/workspace/WorkspacePanel.tsx - Log · Runtime activity and event visibility.
src/features/log/LogPanel.tsx - Debug · Diagnostics and internal state inspection.
src/features/debug/DebugPanel.tsx - Thread list · Sidebar for chat thread navigation.
src/components/ThreadSidebar.tsx - File tree · Browser workspace file navigation.
src/components/FileTree.tsx - Markdown · Renders assistant and document content.
src/components/MarkdownContent.tsx - Capability gate · Blocks unsupported features on incompatible browsers.
src/components/CapabilityGate.tsx
Runtime
Workers and browser-backed execution boundaries.
- Capabilities · Detects secure context, WebGPU, and file-system support.
src/lib/capabilities.ts - LLM worker · Loads and runs the in-browser Gemma model.
src/workers/llm.worker.ts - Workspace worker · Owns folder traversal, reads, writes, search, and undo backups.
src/workers/workspace.worker.ts - Runtime · Selects and adapts the browser AI runtime implementation.
src/services/runtime.ts - Chrome AI · Adapter for browser AI capabilities.
src/services/chrome-ai-runtime.ts - Contracts · Shared message and tool protocol definitions.
src/lib/contracts.ts - ChatML · Message formatting between UI, store, and model worker.
src/lib/chatml.ts - Agent prompt · Shapes the agent instructions and tool loop context.
src/lib/agent-prompt.ts - File System API · User-selected local folder access boundary.
- WebGPU · Accelerates in-browser model execution.
Local data
IndexedDB persistence and external delivery targets.
- DB · Stores threads, sessions, settings, and write backups locally.
src/lib/db.ts - IndexedDB · Local durable storage used by the app.
- Hugging Face · First-use model download source, cached by the browser.
- Static hosting · Static-site delivery via Cloudflare Pages style hosting.
- Headers · Response headers for static deployment.
public/_headers - Redirects · Routing rules for static deployment.
public/_redirects
Connections 27
- Main → App shell: mounts · Bootstraps the SPA.
- App shell → Store: uses · App shell is driven by central state.
- App shell → Capability gate: wraps · Feature availability is gated at the shell level.
- App shell → Chat: renders · Visible chat panel.
- App shell → Workspace: renders · Visible workspace panel.
- App shell → Log: renders · Visible log panel.
- App shell → Debug: renders · Visible debug panel.
- Chat → Thread list: uses · Thread navigation is shared UI.
- Chat → Markdown: renders · Assistant content is markdown-rendered.
- Workspace → File tree: uses · Local files are shown in a tree.
- Capability gate → Capabilities: checks · Browser support detection.
- Store → LLM worker: orchestrates · Coordinates model turns and streamed output.
- Store → Workspace worker: orchestrates · Sends tool actions to workspace operations.
- Store → DB: persists · Writes durable app state and backups.
- Store → Contracts: speaks · Uses shared message shapes.
- Store → ChatML: formats · Builds model/chat payloads.
- Store → Agent prompt: templates · Shapes agent instructions and tool loop.
- Store → Runtime: selects · Chooses the browser runtime path.
- Runtime → Chrome AI: adapts · Runtime adapter boundary.
- LLM worker → WebGPU: runs on · Model execution depends on GPU-enabled browser support.
- LLM worker → Hugging Face: loads from · Model artifacts are fetched on first use.
- Workspace worker → File System API: uses · Folder and file access is isolated in the worker.
- Workspace worker → DB: backs up · Write safety depends on stored snapshots.
- DB → IndexedDB: stores in · All durable app data remains local to the browser.
- File System API → IndexedDB: separate domain · Workspace files live on disk; metadata lives in browser storage.
- Headers → Static hosting: supports · Static hosting configuration.
- Redirects → Static hosting: supports · Static hosting routing configuration.