# henrylau1103/aub architecture

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

- Interactive diagram: https://gitdiagram.com/henrylau1103/aub
- Repository: https://github.com/henrylau1103/aub

## Overview

AUB is a monorepo for a local-first UI contract system: it scans an existing app, turns a screen into a validated “Blueprint,” lets a human review and edit that contract in a browser editor, then hands an agent a package it can implement and prove against.

1. Core domain model
- The central artifact is the Blueprint file (`*.ui.json`, with YAML/Markdown/lock variants).
- Blueprints describe semantic UI trees, layout, interactions, responsive variants, acceptance criteria, and optional provenance.
- Multi-screen products use a separate project file (`*.aub.project.json`) that references multiple Blueprint files and a navigation graph.
- A project-specific `aub.registry.json` can add namespaced component types and production implementations.

2. Schema and type system boundary
- `schema/` is the canonical contract layer.
- `schema/ui-blueprint.schema.json`, `schema/ui-project.schema.json`, `schema/aub-ci.schema.json`, and related schemas define what can be validated and shipped.
- `schema/types.ts` and `schema/registry/components.json` drive the generated TypeScript unions and schema enums, so the registry is the source of truth for supported semantic component types.

3. Browser editor subsystem
- `apps/editor/` is a Vite + React SPA that runs entirely in the browser.
- It provides the visual canvas, palette, properties panels, workflow/project bars, blueprint panel, and import dialog.
- The editor owns human-facing authoring: drag/drop, layout editing, localization, template selection, previewing, and saving Blueprint/project state.

4. Workspace connection and live repo integration
- The editor is not a standalone drawing tool; it connects to a local workspace through the MCP server via `workspace-client` and session state.
- In a target repo, `npx aub-workspace init` installs AUB metadata and workflows without changing app source.
- The editor then uses the local server to load/save Blueprints, inspect templates, review component candidates, and point at the app’s own dev preview URL.

5. MCP server subsystem
- `apps/mcp-server/` is the agent-facing automation layer.
- It exposes the same workspace capabilities over stdio and Streamable HTTP, which makes it usable from MCP clients and from the editor’s local loop.
- Its tools cover discovery, scanning, template generation, blueprint/project CRUD, validation, locking, diffing, migration, component resolution, handoff export, and implementation-report submission.

6. Workspace and repository access layer
- The MCP server’s internal workspace/repo modules mediate all filesystem access to the target app.
- This is the boundary where AUB reads the existing repository, writes `.aub/` artifacts, inspects routes/components, and avoids direct edits to application code unless the user/agent is intentionally implementing a change.
- Candidate custom components are staged first, then promoted to the registry only after approval.

7. Agent handoff and adapter layer
- `adapters/` contains prompt formats for Codex, Claude Code, and Copilot.
- These adapters do not change the Blueprint schema; they only change the instruction packaging for a specific agent.
- Handoff artifacts include the Blueprint, markdown summaries, screenshots, acceptance evidence, and adapter-specific prompt files inside an `.aub.zip`.

8. CLI and script orchestration
- `packages/workspace-cli/` provides the user-facing `aub-workspace` command.
- `scripts/` contains the repo’s automation entry points: validation, migration, diffing, import/export, registry generation, CI verification, report scoring, and workspace-loop helpers.
- Most operational flows are script-driven rather than hidden inside the editor, which keeps the system reproducible in terminals and CI.

9. Import and conversion pipelines
- AUB can ingest existing UI sources through dedicated pipelines, especially Angular component bundles and Design Bridge exports for Figma/Penpot.
- These imports normalize external sources into the Blueprint format, with provenance and diagnostics preserved where possible.
- Scanner output is intentionally candidate-first: custom components are reviewed before they become registry-backed semantic types.

10. Evidence and verification pipeline
- The repo treats implementation evidence as part of the contract.
- Implementation reports capture mappings, screenshots, overflow/accessibility checks, and acceptance evidence; they can be verified and scored.
- The CI gate and local verifier enforce that Blueprint requirements and evidence align before PRs are considered safe.

11. Documentation, examples, and benchmark corpus
- `docs/` contains the architectural rules, safety model, agent workflow, and schema/versioning guidance.
- `examples/` provides canonical Blueprints, projects, registry examples, and workspace fixtures for real app shapes.
- `benchmarks/` measures agent readability and implementation quality against controlled prompts and expected outputs.

12. Deployment and delivery surface
- `site/` is the public landing/documentation site, deployed to GitHub Pages.
- `apps/editor` is also published as a browser demo under a separate Pages path.
- GitHub Actions handle CI and Pages publishing, so the repo’s public demo and its validation gates are both automated.

13. Architectural shape to diagram
- Think of AUB as three connected planes: a schema/validation core, a browser authoring experience, and an agent/workspace automation backend.
- Data flows from existing app source → scan/import/template generation → Blueprint review/editing → handoff package or MCP-driven implementation → implementation report/evidence verification.
- The important trust boundary is between the target application repository and AUB’s contract layer: AUB reads, proposes, validates, and verifies, while actual app changes remain in the target repo.

14. Main runtime technologies
- Node.js 24+ and pnpm drive the monorepo tooling.
- The editor is React + Vite.
- The server is a Node MCP service with stdio and HTTP transport.
- GitHub Actions provide CI, Pages publishing, and PR safety enforcement.

Main entry points: [`apps/editor/src/App.tsx`](https://github.com/henrylau1103/aub/blob/main/apps/editor/src/App.tsx) (Editor), [`schema/ui-blueprint.schema.json`](https://github.com/henrylau1103/aub/blob/main/schema/ui-blueprint.schema.json) (Schemas), [`apps/mcp-server/src/workspace.ts`](https://github.com/henrylau1103/aub/blob/main/apps/mcp-server/src/workspace.ts) (Workspace access), [`apps/mcp-server/src/server.ts`](https://github.com/henrylau1103/aub/blob/main/apps/mcp-server/src/server.ts) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core contract"]
  node_blueprint["Blueprints<br/>contract artifact<br/>[dashboard.ui.json]"]
  node_project["Projects<br/>multi-screen contract"]
  node_registry["Registry<br/>component catalog<br/>[components.json]"]
  node_schemas["Schemas<br/>schema layer"]
  node_types["Typegen<br/>type unions<br/>[types.ts]"]
end

subgraph group_authoring["Browser authoring"]
  node_editor["Editor<br/>React SPA<br/>[App.tsx]"]
  node_canvas["Canvas<br/>visual editor<br/>[Canvas.tsx]"]
  node_panels["Panels<br/>authoring UI"]
  node_editor_state["Editor state<br/>browser state<br/>[store.ts]"]
  node_workspace_client["Workspace client<br/>repo session client"]
end

subgraph group_automation["Agent automation"]
  node_mcp_server[("MCP server<br/>automation service<br/>[server.ts]")]
  node_workspace["Workspace access<br/>repo boundary<br/>[workspace.ts]"]
  node_tools["Tools<br/>MCP actions<br/>[scan-project-ui.ts]"]
  node_importers["Importers<br/>conversion pipeline"]
  node_handoff["Handoff<br/>package export"]
  node_verification["Verification<br/>evidence pipeline"]
end

subgraph group_delivery["Delivery surface"]
  node_cli["CLI<br/>workspace command<br/>[aub-workspace.mjs]"]
  node_scripts["Scripts<br/>orchestration<br/>[ci-verify.mjs]"]
  node_site["Site<br/>[index.html]"]
  node_ci["CI<br/>github actions<br/>[ci.yml]"]
end

node_schemas -->|"define"| node_blueprint
node_schemas -->|"define"| node_project
node_registry -->|"drives"| node_types
node_schemas -->|"generate"| node_types
node_editor -->|"author"| node_blueprint
node_editor -->|"manage"| node_project
node_canvas -->|"compose"| node_editor
node_panels -->|"support"| node_editor
node_editor_state -->|"power"| node_editor
node_workspace_client -->|"connect"| node_mcp_server
node_mcp_server -->|"uses"| node_workspace
node_workspace -->|"read/write"| node_blueprint
node_workspace -->|"read/write"| node_project
node_tools -->|"expose"| node_mcp_server
node_tools -->|"invoke"| node_importers
node_importers -->|"normalize"| node_blueprint
node_handoff -->|"export"| node_mcp_server
node_verification -->|"gate"| node_ci
node_cli -->|"init"| node_workspace
node_scripts -->|"validate"| node_schemas
node_scripts -->|"package"| node_handoff
node_site -->|"publish"| node_ci
node_verification -->|"score"| node_handoff

click node_blueprint "https://github.com/henrylau1103/aub/blob/main/examples/dashboard.ui.json"
click node_project "https://github.com/henrylau1103/aub/blob/main/examples/project/app.aub.project.json"
click node_registry "https://github.com/henrylau1103/aub/blob/main/schema/registry/components.json"
click node_schemas "https://github.com/henrylau1103/aub/blob/main/schema/ui-blueprint.schema.json"
click node_types "https://github.com/henrylau1103/aub/blob/main/schema/types.ts"
click node_editor "https://github.com/henrylau1103/aub/blob/main/apps/editor/src/App.tsx"
click node_canvas "https://github.com/henrylau1103/aub/blob/main/apps/editor/src/components/Canvas.tsx"
click node_panels "https://github.com/henrylau1103/aub/blob/main/apps/editor/src/components/PropertiesPanel.tsx"
click node_editor_state "https://github.com/henrylau1103/aub/blob/main/apps/editor/src/lib/store.ts"
click node_workspace_client "https://github.com/henrylau1103/aub/blob/main/apps/editor/src/lib/workspace-client.ts"
click node_mcp_server "https://github.com/henrylau1103/aub/blob/main/apps/mcp-server/src/server.ts"
click node_workspace "https://github.com/henrylau1103/aub/blob/main/apps/mcp-server/src/workspace.ts"
click node_tools "https://github.com/henrylau1103/aub/blob/main/apps/mcp-server/src/tools/scan-project-ui.ts"
click node_importers "https://github.com/henrylau1103/aub/blob/main/scripts/import-design-bridge.mjs"
click node_handoff "https://github.com/henrylau1103/aub/blob/main/scripts/handoff-package.lib.mjs"
click node_verification "https://github.com/henrylau1103/aub/blob/main/schema/implementation-report.schema.json"
click node_cli "https://github.com/henrylau1103/aub/blob/main/packages/workspace-cli/bin/aub-workspace.mjs"
click node_scripts "https://github.com/henrylau1103/aub/blob/main/scripts/ci-verify.mjs"
click node_site "https://github.com/henrylau1103/aub/blob/main/site/index.html"
click node_ci "https://github.com/henrylau1103/aub/blob/main/.github/workflows/ci.yml"

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_blueprint,node_project,node_registry,node_schemas,node_types toneBlue
class node_editor,node_canvas,node_panels,node_editor_state,node_workspace_client toneAmber
class node_mcp_server,node_workspace,node_tools,node_importers,node_handoff,node_verification toneMint
class node_cli,node_scripts,node_site,node_ci toneRose
```

## Components

### Core contract

Schema, blueprint/project models, registry, and validation boundaries.

- [Blueprints](https://github.com/henrylau1103/aub/blob/main/examples/dashboard.ui.json): contract artifact · Primary UI contract files and variants for single-screen authoring and exchange. · `examples/dashboard.ui.json`
- [Projects](https://github.com/henrylau1103/aub/blob/main/examples/project/app.aub.project.json): multi-screen contract · Project files that assemble multiple blueprints and navigation structure. · `examples/project/app.aub.project.json`
- [Registry](https://github.com/henrylau1103/aub/blob/main/schema/registry/components.json): component catalog · Namespaced semantic component types and production implementation mapping. · `schema/registry/components.json`
- [Schemas](https://github.com/henrylau1103/aub/blob/main/schema/ui-blueprint.schema.json): schema layer · Canonical JSON schemas for blueprints, projects, CI, registry, design bridges, and reports. · `schema/ui-blueprint.schema.json`
- [Typegen](https://github.com/henrylau1103/aub/blob/main/schema/types.ts): type unions · Generated TypeScript unions and project types derived from the schema and registry. · `schema/types.ts`

### Browser authoring

The in-browser editor and its workspace-aware UI state.

- [Editor](https://github.com/henrylau1103/aub/blob/main/apps/editor/src/App.tsx): React SPA · Browser-based blueprint and project authoring experience. · `apps/editor/src/App.tsx`
- [Canvas](https://github.com/henrylau1103/aub/blob/main/apps/editor/src/components/Canvas.tsx): visual editor · Drag/drop canvas for layout, preview, and spatial editing. · `apps/editor/src/components/Canvas.tsx`
- [Panels](https://github.com/henrylau1103/aub/blob/main/apps/editor/src/components/PropertiesPanel.tsx): authoring UI · Palette, properties, blueprint, project, workflow, and workspace panels. · `apps/editor/src/components/PropertiesPanel.tsx`
- [Editor state](https://github.com/henrylau1103/aub/blob/main/apps/editor/src/lib/store.ts): browser state · Draft storage, history, i18n, templates, registry access, and viewport quality logic. · `apps/editor/src/lib/store.ts`
- [Workspace client](https://github.com/henrylau1103/aub/blob/main/apps/editor/src/lib/workspace-client.ts): repo session client · Browser-side bridge to the local workspace session and server capabilities. · `apps/editor/src/lib/workspace-client.ts`

### Agent automation

MCP server, workspace access, import/scan, handoff, and verification flows.

- [MCP server](https://github.com/henrylau1103/aub/blob/main/apps/mcp-server/src/server.ts): automation service · Agent-facing workspace automation service over stdio and HTTP. · `apps/mcp-server/src/server.ts`
- [Workspace access](https://github.com/henrylau1103/aub/blob/main/apps/mcp-server/src/workspace.ts): repo boundary · Filesystem and repository mediation for reading app source and writing AUB artifacts. · `apps/mcp-server/src/workspace.ts`
- [Tools](https://github.com/henrylau1103/aub/blob/main/apps/mcp-server/src/tools/scan-project-ui.ts): MCP actions · Discovery, scan, CRUD, validation, diff, migration, component resolution, and handoff tools. · `apps/mcp-server/src/tools/scan-project-ui.ts`
- [Importers](https://github.com/henrylau1103/aub/blob/main/scripts/import-design-bridge.mjs): conversion pipeline · Angular and Design Bridge ingestion that normalizes external sources into Blueprints. · `scripts/import-design-bridge.mjs`
- [Handoff](https://github.com/henrylau1103/aub/blob/main/scripts/handoff-package.lib.mjs): package export · Adapter-specific prompt packaging, markdown, screenshots, and evidence into .aub.zip. · `scripts/handoff-package.lib.mjs`
- [Verification](https://github.com/henrylau1103/aub/blob/main/schema/implementation-report.schema.json): evidence pipeline · Implementation reports, scoring, and CI/local checks that confirm contract alignment. · `schema/implementation-report.schema.json`

### Delivery surface

CLI, scripts, site, and CI/CD packaging.

- [CLI](https://github.com/henrylau1103/aub/blob/main/packages/workspace-cli/bin/aub-workspace.mjs): workspace command · User-facing aub-workspace command for init and workspace operations. · `packages/workspace-cli/bin/aub-workspace.mjs`
- [Scripts](https://github.com/henrylau1103/aub/blob/main/scripts/ci-verify.mjs): orchestration · Repo automation for validation, migration, registry generation, benchmarks, and workspace loops. · `scripts/ci-verify.mjs`
- [Site](https://github.com/henrylau1103/aub/blob/main/site/index.html): docs site · Public documentation and landing pages deployed via GitHub Pages. · `site/index.html`
- [CI](https://github.com/henrylau1103/aub/blob/main/.github/workflows/ci.yml): github actions · Repository safety gates and Pages publishing workflows. · `.github/workflows/ci.yml`

## Connections

- Schemas → Blueprints: define · Blueprint files must validate against the schema layer.
- Schemas → Projects: define · Project structure is schema-governed.
- Registry → Typegen: drives · Registry contents generate supported semantic type unions.
- Schemas → Typegen: generate · TypeScript types are derived from schema definitions.
- Editor → Blueprints: author · The editor creates and edits blueprint contracts.
- Editor → Projects: manage · The editor also edits multi-screen project state.
- Canvas → Editor: compose · Canvas is the main spatial editing surface.
- Panels → Editor: support · Panels expose palette, properties, workflow, and workspace controls.
- Editor state → Editor: power · Local browser state powers drafting, history, templates, and localization.
- Workspace client → MCP server: connect · Editor uses the local workspace server through the client bridge.
- MCP server → Workspace access: uses · Server operations are mediated through the repository access layer.
- Workspace access → Blueprints: read/write · Workspace layer loads and persists blueprint artifacts.
- Workspace access → Projects: read/write · Workspace layer loads and persists project artifacts.
- Tools → MCP server: expose · MCP tools are the server's functional surface.
- Tools → Importers: invoke · Scan and import paths feed conversion pipelines.
- Importers → Blueprints: normalize · Imported UI sources are normalized into blueprints.
- Handoff → MCP server: export · Server exports handoff packages for agents.
- Verification → CI: gate · CI enforces validation and evidence checks.
- CLI → Workspace access: init · CLI bootstraps AUB metadata and workspace workflows.
- Scripts → Schemas: validate · Automation scripts validate and migrate contracts against schemas.
- Scripts → Handoff: package · Scripts assemble export artifacts and prompts.
- Site → CI: publish · Pages deployment is controlled by CI workflows.
- Verification → Handoff: score · Implementation evidence is checked against the handoff contract.