henrylau1103/aub

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.