ArchitectureLab

Thumbnail
Main Page
Use case

Inspiration

Architecture diagrams in software engineering are usually static, dead pictures—boxes and lines on a whiteboard that capture none of the underlying physics: no capacity limits, no queueing behavior, and no failure modes. When engineers ask an AI assistant for architecture review, the agent is forced to guess what the user is looking at from a screenshot, prose, or brittle DOM scraping. It has no semantic context, no knowledge of the active flow, and no ability to test hypotheses.

We built Executable ArchitectureLab to turn system design diagrams into a live, executable, shared workbench between a human engineer and an in-browser AI agent using WebMCP. Instead of treating the agent as a disconnected chatbot, WebMCP enables the browser page to expose the exact scope, revision, and constraints the engineer is currently focusing on—allowing human and agent to simulate incidents, uncover bottlenecks, and co-design mitigations together.

What it does

Executable ArchitectureLab is a WebMCP-native architecture studio where a person and an AI agent collaborate on the same live system model:

Context Follows Human Attention: Three global read-only tools are available at load (get_architecture_summary, list_simulation_scenarios, get_component_catalog). When the user selects a specific request flow (e.g., Checkout → Redis → Product DB), three scoped tools dynamically register; the moment the selection clears, they are immediately revoked. The agent’s capabilities literally follow the human’s focus.
Deterministic Failure Simulation: The agent (or the human) can run simulated load and failure scenarios (such as a 10× traffic surge combined with a Redis cache outage). The simulator models queueing delays, load shedding, and retry amplification to pinpoint the exact bottleneck (e.g., database connection saturation) and generates an ordered causal event chain presented across structured KPI metric cards.
Draft-Only Patch Proposals with Revision Binding: When asked for a mitigation, the agent uses propose_architecture_patch to draft a concrete change (e.g., adding a read replica or increasing capacity) alongside expected trade-offs. The proposal is bound to the current graph revision (baseRevision). If the human modifies the graph in the meantime, stale proposals are automatically disabled and rejected.
Strict Human-in-the-Loop Safety: The agent cannot apply changes or delete components. There is no destructive tool registered in the system. The proposal sits in the review queue as a diff until the human clicks Apply, which is the only operation that mutates the architecture graph and increments the revision.
Prompt Injection Resilience: Component notes can contain untrusted user content (including our seeded prompt injection test in Redis). The tools flag this data with untrustedContentHint and fence it as data, ensuring that even if an instruction attempts to hijack the agent, there are no destructive tools available for it to misuse.

How we built it

We implemented the project using React 19, TypeScript, Vite, and custom SVG styling, strictly adhering to the latest WebMCP imperative API specification:

WebMCP Adapter (src/webmcp/adapter.ts): Encapsulates all interactions with document.modelContext. Manages dynamic tool lifecycles using AbortController (since unregisterTool() is absent from the spec), serializes JSON schemas safely, shields runtime errors, and emits real-time activity logs for on-screen visibility.
Smart Output Budgeting (src/webmcp/tools.ts): Enforces Chrome’s recommended 1.5K character output budget. Instead of naively truncating from the end (which would silently cut off critical modelling assumptions and disclaimers), our assemble() engine dynamically drops non-essential sections while preserving crucial headers, causal events, and assumptions.
Port & Controls Seam (src/contracts/): A strict architectural boundary separating the read-only WebMCP tool surface (ArchLabPort) from the mutation surface (ArchLabControls). A static AST test asserts that src/webmcp/ never imports controls.
Deterministic Simulation Engine (src/contracts/fixture/): Models the FlashCart e-commerce architecture with synchronous paths (CDN, Gateway, Checkout, Redis, DBs) and asynchronous tails (Order Queue, Invoice Worker, Email), calculating realistic queue penalties and dependency interactions.
Automated Verification Harness (scripts/verify-live.mjs & Vitest): A 31-test Vitest suite covering revision safety, patch validation, and causal models, coupled with a Playwright harness that launches installed Google Chrome with WebMCP flags enabled (WebMCPSupport, WebMCPTesting) to validate 23 live contract assertions against the deployed production origin.

Challenges we ran into

Adapting to Evolving WebMCP Specifications: The standard moved from navigator.modelContext to document.modelContext, and APIs like provideContext(), clearContext(), and unregisterTool() were removed. We built strict guardrail tests to ensure no deprecated or removed APIs leaked into the codebase.
Race Conditions in Dynamic Registration: In WebMCP, duplicate tool names throw errors if a re-registration races a pending abort. Furthermore, React 19's StrictMode double-invokes effects on mount. We solved this in adapter.ts by serializing registrations on per-tool promise chains and tracking abort signals cleanly.
Avoiding Dangerous Output Truncation: Simply cutting strings at 1,500 characters dropped the disclaimer "Every number is synthetic and directional" from the most detailed replies—the exact answers judges and users are most likely to believe. We engineered section-based assembly to drop optional metrics first and keep disclaimers intact.
Deployment & Origin Isolation Requirements: WebMCP requires origin isolation (window.originAgentCluster === true). Configuring vercel.json with Origin-Agent-Cluster: ?1, ensuring /debug rewrites functioned without 404s, and managing cross-origin headers required thorough end-to-end verification.

Accomplishments that we're proud of

Zero-Destructive Architectural Guarantee: Proved that human-in-the-loop safety can be enforced structurally through interface isolation and static scanning tests rather than relying on LLM prompt compliance.
Dynamic, Context-Aware Capability Surface: Achieved seamless registration and revocation of WebMCP tools that mirror user selection in real time without flickering or race conditions.
Interactive Zero-Dependency Canvas: Crafted a lightweight, responsive SVG canvas featuring animated packet traces, zoom controls, clear architectural lanes, and live bottleneck heatmaps without bloated external canvas libraries.
31 Vitest & 23 Live Browser Verification Checks: Built comprehensive regression coverage and an automated Playwright harness validating production deployment in real Chrome.
Transparent Agent Activity: Every tool call, duration, payload, and output preview is streamed live to the UI and the /debug dashboard, making agent reasoning inspectable and demo-ready.

What we learned

WebMCP transforms web apps from static viewports into structured, bidirectional workspaces where human and AI capabilities complement each other seamlessly.
Gating tool availability via the registration lifecycle (registerTool + AbortSignal) is far more reliable than writing prompt-based flow control instructions ("call tool A before tool B"), which models often misunderstand or ignore.
Designing with character budgets, schema validation, and origin isolation from day one is essential when building robust WebMCP applications.

What's next for ArchitectureLab

Freeform Drag-and-Drop Topology: Expanding the canvas from structured architectural lanes into a full freeform drag-and-drop editor allowing custom node creation and connection routing.
Custom Architecture Modeling: Allowing engineers to define and import their own distributed systems, microservices, and queue topologies via JSON or OpenAPI specs.
Export to Infrastructure-as-Code (IaC): Enabling the agent to translate human-approved architecture revisions directly into Terraform, Pulumi, or Docker Compose manifests.
Advanced Multi-Region Simulation: Expanding the simulation engine to model multi-region failover, consensus algorithms (Raft/Paxos), and partition tolerance (CAP theorem scenarios).