Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
124 lines (96 loc) · 7.13 KB

ARCHITECTURE.md

File metadata and controls

124 lines (96 loc) · 7.13 KB
Raw

Architecture

Boundaries

BrowserWeave is split into two product surfaces:

  1. Core is a UI-independent Go runtime, CLI, HTTP API, recorder, and MCP server.
  2. Studio is a React application that only depends on the versioned Core contract.

Core owns browser lifecycle, workflow semantics, permissions, interaction policy, and audit events. Studio never talks directly to a Chrome debugging endpoint.

Browser lifecycle is attach-only: Core selects browser.cdpURL, BROWSERWEAVE_CDP_URL, or one unambiguous local CDP endpoint and never launches a browser process. Target policy is independent: a run may create a disposable/preserved page or exclusively lease and attach to an unambiguous existing page. Reused pages are detached, never closed, so workflows do not require a navigate node and independent runs can continue the same authenticated page state. See CDP attach and Browser Targets.

Core packages

Package Responsibility
core/workflow DSL types, parsing, diagnostics, input validation, compile plan
core/engine Run state machine, retries, variables, templates, callbacks, outputs
core/browser Browser-independent operation contract
core/browser/chrome Chrome lifecycle, page JS locator runtime, CDP input and network domains
core/behavior Pointer path and transient safe-point planning
core/hook Capability-limited embedded JavaScript callbacks
core/event Run/node event bus and signed webhook delivery
core/ai Vendor-neutral model Provider/Resolver plus OpenAI-compatible HTTP adapters
core/authoringagent V2 action canonicalization, PlanV2/GraphIR contracts, deterministic Workflow compilation, typed resource repair, coverage, and no-progress audit
core/value Provider-independent typed comparison and predicate semantics
core/recorder Page event capture and workflow generation
mcpserver Workflow-level AI tools over official MCP Go SDK
studio/server File-backed workflow revisions/versions, durable run/event history, and the integration control API

Element interaction

Ordinary action nodes never accept persisted absolute coordinates.

  1. Core serializes the locator and arguments as data.
  2. A versioned JavaScript locator runtime runs in the page execution context.
  3. It traverses the document and open shadow roots, or invokes the user locator function.
  4. It returns current semantic metadata and getBoundingClientRect() geometry.
  5. Core scrolls and resolves a second time to account for layout changes.
  6. A target point is sampled inside the current valid rectangle.
  7. A curved path is planned from the per-tab virtual pointer position.
  8. CDP Input commands dispatch mouse movement, press, release, or text input.
  9. A final page-side hit test prevents clicking an element that became occluded.

Coordinates exist only during steps 5–8 and are not written back to the workflow, run step outputs, or execution events. Those surfaces retain only safe semantic element metadata such as tag, role, and accessible name.

Workflow state machine

Each node executes:

resolve templates
→ before hooks
→ action with node deadline
→ completion signal
→ after/success hooks
→ persist step output
→ emit event
→ choose labeled outgoing port

The runtime executes one graph token at a time. Typed bindings preserve exact JSON values between inputs, vars, steps, model results, actions, and subflows. Declarative condition, explicit JavaScript branch, dynamic switch, capability-limited evaluate, bounded sequential foreach, numeric for, pre-test while, and post-test until are supported. A structured loop remains a DAG: its body route terminates at an owner-bound loop.end, loop.continue, or loop.break, while Core performs repetition internally and exits through done. Version-pinned workflow.call executes an isolated child frame through a published-workflow resolver while inheriting the root browser session; only declared child outputs cross the frame boundary. Parallel graph tokens, richer lexical iteration scopes, independent child browser leases, and durable checkpoints remain roadmap items. Workflow-level network listeners already run concurrently with the main token. Interrupt guards also observe unexpected DOM state concurrently, but their handler graphs acquire exclusive browser-action ownership only at scheduler safe points before resuming the main token.

The control plane can also compose a business group's latest immutable shared guard-policy version into every member workflow. Composition happens before compile/validation, rejects local/shared ID collisions, and records the policy version on the run. Policy drafts are not runtime dependencies. This keeps the Core runner unaware of Studio storage while giving cross-workflow recovery a governed lifecycle.

Only the root run owns browser Start/Close. Nested call frames reuse the connected browser, have independent inputs/variables/step outputs, and are bounded by exact-reference recursion and depth checks. Studio resolves calls only from immutable published workflow versions. v1alpha1 deliberately keeps child node/debug events out of the parent event stream, leaving the parent workflow.call node as the observable boundary.

JavaScript separation

There are two independent JavaScript environments:

  • Page JavaScript runs inside Chrome and can resolve/inspect DOM elements.
  • Hook JavaScript runs inside Goja and receives JSON-compatible context only.

Hook JavaScript has no Node.js standard library, filesystem, process, browser, or ambient network objects. It returns declarative patches, outputs, events, and control decisions that the Go engine validates and applies.

Network model

Chrome's passive Network domain builds completed HTTPExchange objects. CDP callbacks only update an in-memory correlation table; response body retrieval runs outside the synchronous target callback. Consumers use filtered subscriptions or network.wait nodes.

The recent completed-exchange window prevents a fast response from being lost between a click node and the immediately following network wait node.

Request interception and mutation via the CDP Fetch domain are deliberately deferred. Passive observation cannot accidentally leave a browser request paused.

Control surfaces

  • CLI: validation, execution, recording, Studio server, MCP server.
  • HTTP: workflow CRUD/publishing, versioned asynchronous runs, idempotency, cancellation, status, SSE and callbacks.
  • Studio: workflow library, source/graph authoring, recording review and AI enhancement, input form, publishing, integration contract, diagnostics and run history.
  • MCP: node catalog, validation, revision-safe draft create/read/update/publish, recording Bundle access, ad-hoc/saved runs, status and cancellation at the workflow level.

Studio renders workflow graphs with React Flow and uses Dagre's network-simplex ranking for fresh documents and explicit smart layout. Workflow changes preserve manual coordinates, while loading, importing, or applying a new recording gets a fresh dependency-aware layout so node IDs from another workflow cannot reuse stale positions.