pat/wursor
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity
Files
1b2967d206750c0b5fdb295109421a9158b95bb1
wursor/Originmain-Implementation-Guide-v1_0.md
T
SinachPat 71296f82af first commit
2026-04-23 04:20:14 +01:00

46 KiB
Raw Blame History

ORIGINMAIN

Implementation Guide

AI-Native Design Engineering Platform

Version 1.0 | April 2026 | Patrick --- Product Lead | Confidential

1. Executive Overview

This Implementation Guide translates the Originmain PRD into a concrete, layer-by-layer engineering blueprint. It is the primary technical reference for every developer who will build, integrate, test, or deploy the product. It covers the full stack --- from infrastructure provisioning to AI pipeline design --- and is structured as a progressive sequence of implementation layers, each of which must be stable before the next begins.

The guide follows Originmain's phased roadmap (Phases 1--4 from the PRD) and maps each feature requirement to a specific layer, technology choice, and implementation approach. Where trade-offs exist, the rationale for the selected approach is documented explicitly.

PRINCIPLE Every architectural decision in this guide is subordinate to one constraint: the design surface and the code diff must be the same continuous action. Any trade-off that creates a perceptible gap between a visual edit and a code change is unacceptable.

Layer Name Primary Technology Phase 0 Infrastructure & DevOps Vercel, Supabase, Render, GitHub Actions 1 1 Canvas UI Shell React 19, Fluent UI v9, Griffel 1 2 Live Rendering Engine Sandboxed iframe, Module Federation, Webpack 5 1 3 Visual Editing & Diff Engine Custom AST, TypeScript, react-fiber-utils 1 4 Origin Graph & Data Store PostgreSQL, pg_graphql, Supabase Realtime 1 5 Design Language Runtime JSON Schema, Zod, custom validator 1 6 AI Completion Layer Claude Sonnet 4 API, Anthropic SDK 2 7 Agent Bridge (MCP) Model Context Protocol, WebSocket, tRPC 2 8 Multi-Origin Ingestion Linear SDK, Slack API, GitHub REST 2 9 Multiplayer & Presence Liveblocks, CRDT, Yjs 3 10 Platform & Extensions Plugin API, SSO, SCIM, audit logs 4

2. Development Prerequisites

2.1 Required Team Roles

Before a single line is written, the following roles must be staffed. The product has a high degree of complexity in its rendering and diffing subsystems; under-resourcing these areas is the leading cause of scope collapse in similar products.

Role Count Critical Responsibility Lead Frontend / Design Engineer 1 Canvas UI, component palette, Fluent 2 integration Rendering Engine Engineer 1--2 Sandboxed iframe renderer, Module Federation, hot reload Diff Engine Engineer 1 AST diffing, Intent Diff schema, component-level change tracking Backend / Data Engineer 1 PostgreSQL schema, pg_graphql, Origin Graph, Supabase setup AI / Agent Engineer 1 Claude API integration, Completion Zones, Agent Bridge (MCP) DevOps / Platform Engineer 0.5 CI/CD, infra provisioning, environment management Product Designer (Fluent 2) 1 Originmain's own UI, design token system, interaction design

2.2 Local Development Environment

  • Node.js 22 LTS (use nvm for version management)

  • pnpm 9+ as the package manager (workspaces enabled for monorepo)

  • Docker Desktop for local PostgreSQL and Redis

  • Supabase CLI for local database branching and migrations

  • Vercel CLI for local preview deployments

  • GitHub CLI (gh) for PR automation and Actions triggers

2.3 Repository Structure

Originmain is a pnpm monorepo with the following top-level packages:

Package Path Description app packages/app Main canvas application (React 19, Next.js 15 App Router) renderer packages/renderer Sandboxed iframe rendering engine and Module Federation host diff-engine packages/diff-engine AST differ, Intent Diff schema, change tracker origin-graph packages/origin-graph PostgreSQL schema, Supabase migrations, pg_graphql resolvers ai-layer packages/ai-layer Claude API client, Completion Zone processor, prompt library agent-bridge packages/agent-bridge MCP server, WebSocket protocol, coding agent adapters design-language packages/design-language JSON Schema validator, token pipeline, guidance file runtime ui packages/ui Shared Fluent 2 component wrappers and Originmain-specific components integrations packages/integrations Linear, Slack, GitHub ingestion connectors e2e packages/e2e Playwright end-to-end test suites

3. Layer 0 --- Infrastructure & DevOps

3.1 Cloud Architecture

Originmain's infrastructure is built on three primary cloud providers, selected for complementary strengths: Vercel for edge-first frontend delivery, Supabase for managed PostgreSQL with real-time and GraphQL, and Render for long-running backend services (Agent Bridge, rendering workers).

Service Provider Purpose Tier (Launch) Frontend App Vercel (Pro) Next.js 15 app, edge functions, ISR Pro --- $20/mo Primary Database Supabase (Pro) PostgreSQL, Origin Graph, auth, realtime Pro --- $25/mo Redis Cache Upstash Redis Session cache, rate limiting, queue Pay-per-use Agent Bridge Server Render Long-running MCP WebSocket server Hobby --- $5/mo Object Storage Supabase Storage Artboard screenshots, design language files Included in Pro CDN / Edge Vercel Edge Network Static assets, API edge caching Included in Pro Email (Transactional) Resend Auth emails, notifications Free tier Error Monitoring Sentry Frontend and backend error tracking Team --- $26/mo Analytics PostHog Product analytics, session replay, feature flags Free tier (1M events)

3.2 CI/CD Pipeline

Every pull request triggers a full pipeline via GitHub Actions. The pipeline is defined as code in .github/workflows/ and enforces quality gates that cannot be bypassed. No code reaches production without passing all gates.

  1. Lint & type-check (ESLint, TypeScript strict mode) --- must pass with zero errors

  2. Unit tests (Vitest) --- must maintain 80%+ coverage on diff-engine and origin-graph packages

  3. Build verification --- all packages must build cleanly

  4. Visual regression (Playwright + Percy) --- no unreviewed visual diffs

  5. Supabase migration dry-run --- schema changes validated against production snapshot

  6. Preview deployment to Vercel --- every PR gets a unique preview URL

  7. Production deployment on merge to main --- gated by all above steps

3.3 Environment Strategy

Three environments run in parallel: local (developer machine), staging (auto-deployed from main branch), and production. Each environment has an isolated Supabase project and Vercel deployment. Staging uses production data snapshots (anonymized) refreshed weekly.

CRITICAL The sandboxed rendering iframe communicates with the host app via postMessage. CSP headers must be configured precisely: the frame's origin must be explicitly whitelisted in the host app's Content-Security-Policy. A misconfigured CSP is the single most common rendering failure mode.

4. Layer 1 --- Canvas UI Shell

4.1 Framework & Technology

The canvas application is built with Next.js 15 (App Router) and React 19. The infinite canvas is implemented using a combination of CSS transforms and a custom viewport state manager --- NOT a third-party canvas library like react-flow or Konva, which lack the semantic structure required for component-level interaction.

Concern Technology Rationale Framework Next.js 15 App Router RSC for meta-layer content, client components for canvas Component Library @fluentui/react-components v9 PRD mandate; Fluent 2 is the design system CSS-in-JS Griffel (via Fluent 2) Fluent 2's native styling system; zero runtime overhead Canvas Primitives Custom React + CSS transform Full control over hit testing, selection, and Z-order State Management Zustand + Immer Lightweight, performant; supports undo/redo middleware Data Fetching TanStack Query v5 Cache management, optimistic updates, background sync Routing Next.js App Router Workspace / artboard URL structure Auth Clerk Team-aware auth, org management, RBAC

4.2 Canvas Architecture

The canvas is a full-viewport React tree with three stacked layers, managed by absolute positioning and pointer-events toggling:

  • Background Layer: Grid, guides, rulers --- purely decorative, rendered on a canvas element for performance

  • Artboard Layer: The collection of Live Artboards, each an absolutely positioned iframe wrapper with overlay controls

  • UI Chrome Layer: Toolbars, inspectors, panels --- all Fluent 2 components, rendered above the canvas

Viewport state (pan offset, zoom level) is managed in a single Zustand store and applied via a CSS transform matrix to the Artboard Layer. This approach enables smooth 60fps panning and zooming without re-rendering the artboard content.

4.3 Fluent 2 Integration

Originmain's own UI uses the following Fluent 2 pattern as its root structure. This must be established before any other UI work begins:

// packages/app/src/app/layout.tsx

import { FluentProvider, webLightTheme } from '@fluentui/react-components';

export default function RootLayout({ children }) {

return <FluentProvider theme={webLightTheme}>{children}</FluentProvider>;

}

NOTE Custom brand theming is achieved via createLightTheme(brandVariants) where brandVariants maps Originmain's #0F52BA palette to the 16 BrandVariants slots. Store the custom theme in packages/ui/src/themes/originmain-theme.ts.

4.4 Codebase File Browser (@pierre/trees)

Originmain exposes two tree-based navigation surfaces with different requirements, and they are served by different libraries. This distinction is architectural, not cosmetic.

Artboard Navigator (Fluent 2 Tree + TreeItem). The left-panel tree that shows workspace hierarchy, artboard groups, and project folders. This surface is UX-first: it navigates product metadata, never grows beyond a few hundred nodes, and must visually match the Fluent 2 design language that governs the rest of the chrome. Fluent 2's Tree and TreeItem components are the correct choice here --- they carry built-in ARIA roles, keyboard navigation, and Fluent token integration at zero additional cost. Implementation path: packages/app/src/components/navigator/ArtboardTree.tsx.

Codebase File Browser (@pierre/trees). When Originmain connects to a React or Next.js repository, a separate file browser panel renders the connected codebase's file tree. This surface has categorically different requirements: real codebases contain thousands of files, git status indicators are essential (added, modified, deleted, renamed, untracked, ignored), path-aware search is required, and virtualization is not optional --- it is the baseline. @pierre/trees (Apache 2.0, from The Pierre Computer Co.) is built precisely for this use case. It renders trees of 5,000+ files instantly via automatic row virtualization (only visible rows mount), shows git status badges natively via the gitStatus prop, supports three fileTreeSearchMode options for filtering, and collapses single-child directory chains via the flattenEmptyDirectories option. Its ARIA compliance (tree, treeitem, aria-level, aria-posinset, aria-setsize) matches Fluent 2's accessibility standards. Implementation path: packages/app/src/components/codebase/CodebaseFileTree.tsx.

Install: pnpm add @pierre/trees. The library ships a React component as its primary API. Pass the file tree data structure (nodes with name, path, type, children, and optional gitStatus fields), and the component handles all rendering, virtualization, and keyboard interaction. Theming is applied via CSS custom properties on the container element, which allows Fluent 2 token values to be projected into the tree's visual layer without adopting the Pierre design language wholesale.

5. Layer 2 --- Live Rendering Engine

5.1 Architecture Overview

The Rendering Engine is the technical heart of Originmain and its most differentiated component. It renders a connected application's actual React component tree inside a sandboxed iframe, preserving full interactivity, state, and design token fidelity. This is fundamentally different from screenshot-based rendering (which produces a static image) or Figma-style rendering (which draws components from a spec, not the actual code).

5.2 Module Federation Setup

The rendering approach uses Webpack 5 Module Federation to share the connected application's components into the Originmain renderer without bundling them directly. The connected app exposes a Module Federation remote; the Originmain renderer host imports from it at runtime.

Role Party Configuration Remote Connected Application Exposes component routes via ModuleFederationPlugin; runs on localhost:3001 (dev) or CDN (prod) Host Originmain Renderer Consumes remote components; renders them in sandboxed iframes with injected design context Shared React, React-DOM Singleton shared to prevent duplicate React instances across host and remote

5.3 Sandboxing Model

Each Live Artboard renders inside an iframe with a carefully scoped sandbox attribute. The sandboxing serves two purposes: security isolation (the rendered app cannot access the host's DOM or cookies) and visual isolation (the rendered app's global CSS cannot leak into the canvas chrome).

  • iframe sandbox attribute: allow-scripts allow-same-origin allow-forms

  • Communication protocol: window.postMessage with structured message types defined in packages/renderer/src/protocol.ts

  • Component tree extraction: a lightweight React DevTools hook injected into the iframe reads the Fiber tree and posts it to the host via the protocol

  • Design token injection: Originmain injects a script before the remote app initialises that patches the Fluent 2 FluentProvider with the team's custom brand theme

5.4 Rendering Triggers

A Live Artboard can be created from any of the following origins, each handled by a distinct ingestion path:

Origin Type Ingestion Path Metadata Captured App Route URL User pastes URL; renderer navigates iframe to route Route path, component tree, design tokens, timestamp Linear Issue Linear SDK fetches issue; linked screenshot or URL rendered Issue ID, title, reporter, linked PR/commit Slack Message Slack API fetches message; screenshot or URL rendered Channel, author, timestamp, thread context Git Commit Hash GitHub API fetches commit; checks out and renders that tree Commit SHA, author, branch, diff from HEAD Manual Fork User duplicates an existing artboard Parent artboard ID, fork timestamp, author

6. Layer 3 --- Visual Editing & Diff Engine

6.1 Intent Diff Schema

The Intent Diff is the core data structure of Originmain. It is the contract between the design surface and the code agent. Unlike a pixel diff (which compares images) or a DOM diff (which compares HTML), an Intent Diff operates at the component level --- it describes changes in terms of the React component tree, props, and design tokens.

The Intent Diff schema (TypeScript):

interface IntentDiff {

artboardId: string;

timestamp: ISODateString;

author: UserId;

changes: ComponentChange[];

summary: string; // AI-generated natural language summary

beforeScreenshot: StorageUrl;

afterScreenshot: StorageUrl;

}

6.2 Visual Editing Implementation

Visual editing is implemented as an overlay system: a transparent interaction layer sits above the rendered iframe and intercepts mouse events. When a user clicks a component, the renderer identifies it via the Fiber tree map and renders selection handles. Drag operations are translated into prop changes (position, size, padding) and appended to the current Intent Diff.

Edit Operation Component-Level Change Produced Coding Agent Target Resize component width/height prop or className token change Inline style or Tailwind/Fluent token update Reposition element CSS position/margin/padding change Layout class or inline style update Swap component Component reference change (e.g. SecondaryButton -> PrimaryButton) Import statement + JSX element replacement Edit text children prop text node change JSX text node replacement Change colour Design token reassignment (colorBrandBackground, etc.) Token variable update in theme file Add/remove element Insertion/deletion in component subtree JSX child addition or removal

6.3 Undo/Redo & Branch Exploration

Undo/redo is implemented via a Zustand middleware that maintains a linear history stack per artboard. Branch exploration (fork an artboard and try both directions) is implemented at the data model level: forking creates a new artboard record in the Origin Graph with a parent reference, both sharing the same rendering origin but accumulating independent change histories.

6.4 Code-Level Diff Rendering (@pierre/diffs)

The Diff Engine (Section 6.1) computes Intent Diffs at the AST and component-prop level --- this is the logic layer and is custom TypeScript. A separate concern is the visual rendering of code-level diffs in two specific surfaces: the export panel (where a developer previews what code changes will be applied to their codebase before accepting), and the Agent Bridge communication view (where the coding agent's implementation status is shown alongside the design intent). For these surfaces, @pierre/diffs (Apache 2.0, from The Pierre Computer Co.) is the designated renderer.

@pierre/diffs is built on Shiki for syntax highlighting, uses CSS Grid and Shadow DOM for layout (resulting in fewer DOM nodes and faster paint than DOM-heavy alternatives), and ships three React components: MultiFileDiff (multiple changed files in one panel), PatchDiff (a git patch string rendered directly), and FileDiff (two arbitrary file contents compared). All three share a common prop set for configuration, annotations, and styling. The annotation framework is the critical capability for Originmain: it allows line-level context to be injected inline --- specifically, the natural-language summary phrases from the Intent Diff can be anchored to the exact lines they describe, giving developers a directly connected view of design intent and code change simultaneously.

The library supports both stacked (unified) and split (side-by-side) rendering modes. The export panel uses split mode by default (showing the before state in one column and the proposed after state in the other) and falls back to stacked on narrower drawer widths. The Agent Bridge communication view uses stacked mode to prioritise vertical information density alongside the chat-style agent dialogue.

Theming: @pierre/diffs uses Shiki themes for syntax colouring. Map Fluent 2's webLightTheme and webDarkTheme to appropriate Shiki themes (github-light and github-dark-dimmed are the recommended defaults) and override the diff gutter and background colours via CSS custom properties on the container element to match Fluent 2 surface tokens (colorNeutralBackground1, colorNeutralBackground2). This produces a visually coherent diff panel without requiring the Pierre colour palette. Install: pnpm add @pierre/diffs. Primary implementation path: packages/app/src/components/diff/CodeDiffPanel.tsx.

7. Layer 4 --- Origin Graph & Data Store

7.1 PostgreSQL Schema

The Origin Graph is stored in PostgreSQL (Supabase) as a directed acyclic graph. The core entities are Workspaces, Artboards, Origins, Diffs, and Agents. All tables use UUIDs as primary keys and include created_at / updated_at timestamps.

Table Key Columns Description workspaces id, name, owner_id, plan, settings_jsonb Top-level tenant boundary; one per team artboards id, workspace_id, name, origin_id, parent_artboard_id, metadata_jsonb The core canvas unit; tracks lineage via parent_artboard_id origins id, type (ENUM), source_ref, source_metadata_jsonb Typed origin record: GIT_COMMIT, LINEAR_ISSUE, SLACK_MESSAGE, URL, FORK intent_diffs id, artboard_id, author_id, changes_jsonb, summary, status (ENUM) Each saved change set; status: DRAFT, EXPORTED, IMPLEMENTED, BLOCKED agent_sessions id, artboard_id, diff_id, agent_type, messages_jsonb, status Bidirectional Agent Bridge conversation log design_language_files id, workspace_id, name, schema_jsonb, version Uploaded design language JSON/YAML, validated and stored team_members id, workspace_id, user_id, role (ENUM) Role: OWNER, DESIGNER, ENGINEER, PM, VIEWER

7.2 pg_graphql API

Supabase's pg_graphql extension auto-generates a GraphQL API from the PostgreSQL schema. Originmain uses this as the primary data API for the frontend, supplemented by tRPC endpoints for write-heavy operations (diff creation, agent sessions) that require complex server-side logic.

PERF The most expensive query is the Origin Graph traversal (finding all ancestors or descendants of an artboard). Pre-compute and cache ancestry paths in a materialised view (artboard_ancestry) updated by a trigger on INSERT to artboards. This avoids recursive CTEs at query time.

8. Layer 5 --- Design Language Runtime

8.1 Design Language File Format

A Design Language File is a JSON document that defines a team's design system rules. It is validated against a JSON Schema on upload and stored in the design_language_files table. The runtime loads it into memory for use by the AI layer, visual editing constraints, and Completion Zone validation.

The file structure:

  • tokens: Colour, typography, spacing, and motion tokens (maps to Fluent 2 token names where applicable)

  • components: Per-component usage rules (allowed props, forbidden variants, required ARIA attributes)

  • screens: Screen-level rules (which components are allowed, mandatory sections, layout constraints)

  • voice: Tone-of-voice rules for AI-generated text content

  • accessibility: Global WCAG requirements and custom accessibility rules

8.2 Validation Pipeline

Every AI completion and every visual edit that changes a design token is validated against the active Design Language File in real time. Violations are shown as inline annotations on the artboard --- not blocking errors, but visible warnings that require explicit acknowledgement before exporting a diff.

9. Layer 6 --- AI Completion Layer

9.1 Claude API Integration

The AI layer is built on Claude Sonnet 4 via the Anthropic SDK. All AI features route through a single AI gateway service (packages/ai-layer) which manages API key rotation, rate limiting, cost tracking, and prompt versioning. No AI calls are made directly from the frontend.

AI Feature Model Input Output Completion Zone fill Claude Sonnet 4 Zone context, design language file, surrounding components Structured component tree or content JSON Diff summary generation Claude Sonnet 4 Raw component-level changes (JSON) Natural language summary for human review Cross-artboard query Claude Sonnet 4 Natural language query + Origin Graph metadata Filtered artboard list with reasoning Design system drift report Claude Sonnet 4 Live app screenshot + design language file Drift violations with corrective Intent Diffs Agent Bridge Q&A Claude Sonnet 4 Coding agent question + artboard context Design agent answer with visual reference

9.2 Completion Zone Implementation

A Completion Zone is a React component rendered in the UI chrome layer over the relevant region of an artboard. The zone UI (Fluent 2 Card with intent selector and submit button) communicates with the AI layer via tRPC. The AI response is rendered as a proposed overlay on the artboard; the designer accepts, modifies, or rejects it before it is committed to the Intent Diff history.

9.3 Prompt Engineering Guidelines

  • Every prompt includes: the team's design language file as a system constraint, the component tree context of the target region, and before/after screenshots of the artboard

  • Prompts are versioned in packages/ai-layer/src/prompts/ and tested with an evaluation harness before deployment

  • Temperature is set to 0.3 for completion tasks (deterministic quality) and 0.7 for generative variation tasks (creative alternatives)

  • All AI outputs are validated against the Design Language File schema before being presented to the user; invalid outputs are silently regenerated up to 3 times before surfacing an error

10. Layer 7 --- Agent Bridge (MCP)

10.1 Protocol Architecture

The Agent Bridge is an MCP (Model Context Protocol) server that exposes Originmain's design context to external coding agents. It runs as a long-lived WebSocket server (Render) alongside a REST endpoint for polling-based agents. The bridge is bidirectional: it pushes diffs to coding agents and receives implementation status updates in return.

10.2 MCP Server Tools

The Originmain MCP server exposes the following tools to connected coding agents:

MCP Tool Input Output get_pending_diffs workspace_id, artboard_id (optional) Array of IntentDiff objects with status EXPORTED get_artboard_context artboard_id Full artboard metadata, component tree, design language file, before/after screenshots ask_design_agent diff_id, question: string Claude-generated answer from the design agent with visual reference update_diff_status diff_id, status, notes Acknowledges implementation; updates diff record in Origin Graph get_design_language workspace_id The team's active design language file for local validation

10.3 Coding Agent Adapters

Phase 2 ships with first-party adapters for Cursor and Claude Code. Each adapter wraps the MCP protocol in the coding agent's native integration format:

  • Cursor: .cursorrules file + MCP server config in cursor_settings.json; adapter translates IntentDiff to Cursor's 'edit plan' format

  • Claude Code: CLAUDE.md auto-generation + MCP server declaration; adapter streams IntentDiff as a structured task to the Claude Code session

  • Generic: Raw MCP JSON-RPC over WebSocket for custom integrations

11. Layers 8--10 --- Integrations, Multiplayer & Platform

11.1 Layer 8: Multi-Origin Ingestion

Each integration is an isolated connector in packages/integrations that implements the OriginIngester interface: ingest(source) => Origin. Connectors run as serverless functions (Vercel Edge Functions) to minimise latency on the ingestion path.

Integration SDK / API Ingestion Flow Linear @linear/sdk v2 Webhook on issue update -> fetch issue + attachments -> render linked URL or screenshot as artboard Slack @slack/bolt v4 Event API on message_posted -> parse URL or attachment -> render as artboard with Slack thread context GitHub @octokit/rest Webhook on PR open/push -> render affected routes at commit SHA -> diff against base branch artboard Intercom Intercom REST API Inbound webhook on user report -> extract annotated screenshot -> create artboard with user context metadata

11.2 Layer 9: Multiplayer & Presence

Real-time multiplayer is implemented using Liveblocks, which provides CRDT-based shared state, presence, and conflict resolution. The Liveblocks room maps 1:1 to a Workspace. Each artboard is a Liveblocks Storage object. Presence (cursor positions, active artboard, selection state) uses Liveblocks Presence API with a 50ms update throttle.

IMPORTANT Multiplayer is a Phase 3 feature. Design the data model and state management for eventual multiplayer from Phase 1 (use Zustand stores that can be swapped for Liveblocks storage without API changes), but do not integrate Liveblocks until Phase 3 to avoid complexity creep.

11.3 Layer 10: Platform & Extensions

The Plugin API (Phase 4) is a sandboxed JavaScript execution environment (based on the Figma Plugin API model) that allows third parties to:

  • Read artboard metadata and Intent Diffs via a read-only API

  • Write new artboards and origins via a write API (requires approval)

  • Register custom Completion Zone types with custom AI prompts

  • Add custom ingestion connectors beyond the first-party set

Enterprise features (Phase 4) include: SSO via SAML 2.0 (Clerk Enterprise), SCIM user provisioning, workspace-level audit logs (Supabase audit log extension), and white-label theming via the Fluent 2 createLightTheme API.

12. Testing Strategy

Layer Test Type Tooling Coverage Target Diff Engine Unit Vitest 95% --- this is the most critical package Origin Graph Integration Vitest + Supabase local 80% on all query paths Design Language Runtime Unit Vitest 90% on validator logic AI Layer Eval harness Custom eval framework + Anthropic evals 80% acceptance rate on completions Agent Bridge Contract Pact (consumer-driven contracts) All MCP tools covered Canvas UI Component Storybook + Chromatic All Fluent 2 wrapper components Rendering Engine Visual regression Playwright + Percy All route renders covered Full product E2E Playwright 10 critical user journeys

12.1 The 10 Critical E2E Journeys

  1. Connect an app and render its first Live Artboard from a route URL

  2. Make a visual edit and verify the correct Intent Diff is generated

  3. Export a diff to Cursor via the Agent Bridge and verify receipt

  4. Upload a Design Language File and verify AI completion respects its constraints

  5. Ingest a Linear issue and render its linked screen as an artboard

  6. Fork an artboard and verify independent change histories

  7. Use the Cross-artboard Query to find all artboards matching a natural language filter

  8. Complete a Completion Zone and accept the AI-generated content

  9. Verify multiplayer presence shows correct cursor positions for two users

  10. Generate a Design System Drift report and verify corrective diffs are accurate

13. Security Considerations

Risk Mitigation Sandboxed iframe XSS Strict CSP, sandbox attribute, postMessage origin validation, no allow-same-origin + allow-scripts combined for untrusted content Design Language File injection JSON Schema validation on upload, Zod runtime parsing, no eval() of file contents AI prompt injection via artboard content Sanitise all user-generated content before including in AI prompts; use Anthropic's system prompt boundary strictly API key exposure All Anthropic API calls server-side only; Clerk JWT required on all tRPC routes; environment variables never in client bundle Origin Graph data leakage Row-level security (RLS) in Supabase on all tables; workspace_id checked on every query; Clerk JWT verified server-side Agent Bridge abuse MCP connections require a signed workspace token; rate-limited to 100 diff exports per hour per workspace; all sessions logged Module Federation supply chain Pin remote versions; validate module hashes on load; disallow dynamic remote URLs from untrusted sources

14. Phase-by-Phase Build Plan

Phase 1: Foundation (Months 1--4)

Deliverables at the end of Phase 1 constitute the Minimum Viable Product for internal use:

Week Milestone Acceptance Criteria 1--2 Monorepo scaffold, CI/CD, Supabase setup All packages build; GitHub Actions pipeline green; Supabase local running 3--4 Fluent 2 canvas shell (Layout, Toolbar, Inspector) Canvas chrome renders; pan/zoom works; Fluent 2 tokens applied 5--7 Rendering Engine v1 (iframe + Module Federation) Connected Next.js app renders inside canvas artboard 8--10 Visual editing + Diff Engine v1 Click-to-select, drag-to-resize; Intent Diff generated on every edit 11--12 Origin Graph v1 (PostgreSQL + pg_graphql) Artboard CRUD; metadata stored; basic query API working 13--14 Design Language File upload + validation File uploaded; AI and editing constrained to its rules 15--16 Diff export (JSON + NL summary) Intent Diff exported to clipboard and file; summary generated by Claude

Phase 2: Intelligence (Months 5--8)

Week Milestone Acceptance Criteria 17--18 AI Completion Zones v1 Designer draws zone; Claude generates completion; accepted or rejected 19--21 Agent Bridge v1 (MCP server + Cursor adapter) Cursor receives IntentDiff; status update flows back to artboard 22--23 Linear + Slack ingestion Linear issue renders as artboard; Slack screenshot renders as artboard 24--26 Claude Code adapter + bidirectional Q&A Claude Code receives diff; design agent answers coding agent questions 27--28 Closed beta preparation: onboarding, docs, support 100 design engineering teams onboarded to closed beta

Phase 3: Scale (Months 9--12)

Week Milestone Acceptance Criteria 29--32 Liveblocks multiplayer integration Two users edit simultaneously; presence cursors visible; no data conflicts 33--35 Cross-artboard natural language querying Query returns correct artboard set; Origin Graph traversal < 200ms 36--38 Design system drift detection Drift report generated; corrective diffs exported; coding agent applies them 39--40 Vue + Svelte rendering support Vue and Svelte routes render as Live Artboards 41--44 Public beta preparation and launch Public beta live; self-serve onboarding; pricing page active

15. Performance Targets

Operation Target Measurement Artboard initial render (cold) < 3 seconds Playwright performance.timing from navigation to iframe loaded Artboard re-render after edit < 500ms Time from mouse-up on drag to updated visual feedback Intent Diff generation < 100ms Time from edit commit to diff appearing in inspector panel Diff export to coding agent < 2 seconds Time from export button click to coding agent receiving payload AI Completion Zone fill < 8 seconds (P90) Time from zone submission to completion rendered in artboard Canvas pan/zoom 60fps sustained Chrome DevTools frame rate monitor during continuous pan gesture Origin Graph query (complex) < 500ms p95 query time in production (measured via Supabase Query Analytics) Cross-artboard NL query < 5 seconds Time from query submission to results rendered

Appendix: Key Dependencies

Package Version Purpose react 19.x Core UI framework next 15.x App framework, routing, RSC @fluentui/react-components 9.x Design system and component library @griffel/react 1.x CSS-in-JS (included with Fluent 2) zustand 5.x Canvas state management @tanstack/react-query 5.x Server state and caching @trpc/server + @trpc/client 11.x Type-safe API layer @anthropic-ai/sdk 0.x (latest) Claude API client @modelcontextprotocol/sdk latest MCP server and client @supabase/supabase-js 2.x Database, auth, storage, realtime @liveblocks/client 2.x Multiplayer CRDT (Phase 3) @linear/sdk 2.x Linear integration @slack/bolt 4.x Slack integration @octokit/rest 20.x GitHub integration zod 3.x Runtime schema validation vitest 2.x Unit and integration testing playwright 1.x E2E and visual regression testing yjs 13.x CRDT underlying Liveblocks (Phase 3) @pierre/diffs 1.x (latest) Code-level diff rendering (export panel & Agent Bridge view) @pierre/trees latest Codebase file browser (git status, virtualization, search)

End of Implementation Guide --- Originmain v1.0

Reference in New Issue View Git Blame Copy Permalink