Frame Pilot AI

flowchart TB
  user(["Internal user"]):::user
  subgraph CP["Control plane, trusted"]
    dash["Dashboard UI"]:::core
    api["API v1"]:::core
    db[("PostgreSQL: run state")]:::core
    queue[("Redis: job queue")]:::core
    store[("Artifact storage")]:::core
    worker["Worker: orchestrator and stage runners"]:::core
    secrets[["Secret store"]]:::core
  end
  subgraph EXT["External services"]
    figma["Figma REST API"]:::ext
    llm["AI provider"]:::ext
    gh["GitHub via GitHub App"]:::ext
    host["Vercel build and hosting"]:::ext
  end
  subgraph SB["Isolated execution, untrusted"]
    sandbox["Sandbox: install, build, browser tests"]:::risk
  end
  user -->|"HTTPS"| dash
  dash -->|"REST and live events"| api
  api --> db
  api -->|"outbox"| queue
  queue -->|"stage jobs"| worker
  worker --> db
  worker --> store
  api -->|"signed links"| store
  worker -->|"read design, render images"| figma
  worker -->|"structured prompts"| llm
  worker -->|"create repo, commit"| gh
  worker -->|"deploy and poll"| host
  worker -->|"files in, reports out"| sandbox
  host -->|"build exact commit"| gh
  sandbox -.->|"live smoke tests"| host
  secrets -.-> worker
  secrets -.-> api
  classDef user fill:#F1E7D3,stroke:#B89B6A,color:#3B2F1E
  classDef core fill:#DCEFEA,stroke:#0F766E,color:#12302C
  classDef ext fill:#FFFFFF,stroke:#8FA9A3,color:#17302C,stroke-dasharray: 4 3
  classDef risk fill:#F6E1DD,stroke:#A63D36,color:#5A1E1A

sequenceDiagram
  autonumber
  actor U as User
  participant D as Dashboard and API
  participant W as Worker
  participant F as Figma
  participant M as AI model
  participant S as Sandbox
  participant G as GitHub
  participant V as Vercel
  U->>D: Submit project and Figma link
  D->>F: Check access and read outline
  alt Link invalid or not shared
    F-->>D: Access denied
    D-->>U: Explain how to fix
  else Accessible
    F-->>D: Pages, frames, version
    D-->>U: Suggested pages and routes
  end
  U->>D: Confirm and start
  D-->>U: Live progress stream opens
  D->>W: Queue first stage
  W->>F: Fetch frames, renders and images
  W->>M: Interpret design
  opt Blocking ambiguity
    W-->>U: Ask a question through the dashboard
    U->>W: Answer
  end
  W->>M: Plan the site
  W->>M: Write components and pages
  W->>S: Build and test
  S-->>W: Results and screenshots
  loop Up to 3 repair attempts while hard checks fail
    W->>M: Diagnose and propose a small patch
    W->>S: Apply, rebuild, retest
  end
  alt Quality gate failed
    W-->>U: Run failed, report attached
  else Quality gate passed
    W->>G: Create repository and commit
    W->>V: Deploy preview of that commit
    V-->>W: Preview ready
    W->>S: Live tests against preview URL
    W-->>U: Preview URL, commit and report
  end

flowchart TD
  S0(("Start")):::term --> Q(["queued"]):::state
  Q -->|"worker takes the job"| I(["ingesting design"]):::state
  Q -->|"cancelled before start"| CX(["cancelled"]):::bad
  I --> B(["building specification"]):::state
  B -->|"blocking question"| AW(["awaiting input"]):::user
  AW -->|"answered"| P(["planning"]):::state
  B -->|"no question"| P
  P --> G(["generating"]):::state
  G --> V(["validating"]):::state
  V -->|"checks failed, attempts left"| R(["repairing"]):::ai
  R -->|"patch kept or reverted"| V
  V -->|"quality gate passed"| PU(["publishing"]):::state
  V -->|"limit reached"| F(["failed"]):::bad
  PU --> D(["deploying"]):::state
  D -->|"preview ready"| VD(["verifying deployment"]):::state
  D -->|"deployment error"| F
  VD -->|"live tests passed"| OK(["succeeded"]):::ok
  VD -->|"live tests failed"| F
  F -.->|"retry from last checkpoint"| Q
  ANY(["any running state"]):::state -->|"cancel requested"| CC(["cancelling"]):::gate
  CC -->|"work stopped, sandbox removed"| CX
  classDef state fill:#DCEFEA,stroke:#0F766E,color:#12302C
  classDef user fill:#F1E7D3,stroke:#B89B6A,color:#3B2F1E
  classDef ai fill:#0F766E,stroke:#0B4F4A,color:#FFFFFF
  classDef gate fill:#FFF6E0,stroke:#B7791F,color:#4A3410
  classDef ok fill:#DDEEE2,stroke:#2E7048,color:#173D26
  classDef bad fill:#F6E1DD,stroke:#A63D36,color:#5A1E1A
  classDef term fill:#0B4F4A,stroke:#0B4F4A,color:#FFFFFF

erDiagram
  PROJECT ||--o{ DESIGN_SNAPSHOT : captures
  PROJECT ||--o{ GENERATION : runs
  PROJECT ||--o| REPOSITORY : "publishes to"
  DESIGN_SNAPSHOT ||--o{ ASSET : contains
  DESIGN_SNAPSHOT ||--o{ DESIGN_SPEC : "normalised into"
  DESIGN_SPEC ||--o{ GENERATION : "input to"
  GENERATION ||--o{ STAGE_RUN : executes
  GENERATION ||--o{ SOURCE_SNAPSHOT : "versions code"
  GENERATION ||--o{ QA_RUN : "checked by"
  QA_RUN ||--o{ QA_CHECK : contains
  GENERATION ||--o{ REPAIR_ATTEMPT : "repaired by"
  GENERATION ||--o{ DEPLOYMENT : deploys
  GENERATION ||--o{ WORKFLOW_EVENT : emits
  PROJECT {
    text id PK
    text name
    text figma_file_key
    jsonb settings
  }
  DESIGN_SNAPSHOT {
    text id PK
    text figma_version
    text raw_sha256
  }
  DESIGN_SPEC {
    text id PK
    text schema_version
    text spec_sha256
  }
  GENERATION {
    text id PK
    text status
    text current_stage
    text qa_verdict
  }
  STAGE_RUN {
    text id PK
    text stage
    int attempt
    timestamptz heartbeat_at
  }
  SOURCE_SNAPSHOT {
    text id PK
    int seq
    text tree_sha256
  }
  QA_RUN {
    text id PK
    text target
    text verdict
  }
  QA_CHECK {
    text id PK
    text check_type
    text status
    real metric
  }
  REPAIR_ATTEMPT {
    text id PK
    text outcome
  }
  REPOSITORY {
    text id PK
    text full_name
  }
  DEPLOYMENT {
    text id PK
    text environment
    text commit_sha
    text url
    bool known_good
  }
  WORKFLOW_EVENT {
    bigint seq PK
    text type
  }
  ASSET {
    text id PK
    text kind
    text sha256
  }

flowchart TD
  A["Source snapshot"]:::core --> B["Sandbox: install, type check, lint, build"]:::core
  B --> C["Browser tests: routes, errors, links, overflow, accessibility, journeys"]:::core
  C --> D["Screenshot comparison with Figma"]:::core
  D --> E{"All hard checks pass?"}:::gate
  E -->|"Yes"| F["Verdict: pass, or pass with warnings"]:::ok
  E -->|"No"| G{"Attempts and budget left?"}:::gate
  G -->|"No"| H["Stop safely: failed, with full history"]:::risk
  G -->|"Yes"| I["Trace failures to responsible files"]:::core
  I --> J["AI proposes a minimal patch"]:::ai
  J --> K["Apply to a copy, rebuild, retest"]:::core
  K --> L{"Fewer failures and nothing newly broken?"}:::gate
  L -->|"Yes"| M["Keep patch as new snapshot"]:::ok
  L -->|"No"| N["Revert to previous snapshot"]:::risk
  M --> E
  N --> G
  classDef core fill:#DCEFEA,stroke:#0F766E,color:#12302C
  classDef ai fill:#0F766E,stroke:#0B4F4A,color:#FFFFFF
  classDef gate fill:#FFF6E0,stroke:#B7791F,color:#4A3410
  classDef ok fill:#DDEEE2,stroke:#2E7048,color:#173D26
  classDef risk fill:#F6E1DD,stroke:#A63D36,color:#5A1E1A

flowchart LR
  subgraph Z1["Zone 1: trusted control plane, holds credentials, never runs generated code"]
    API["Dashboard and API"]:::core
    WK["Worker"]:::core
    SEC[["Secret store"]]:::core
    DB[("Database")]:::core
    OBJ[("Private artifact storage")]:::core
  end
  subgraph Z2["Zone 2: untrusted execution, runs generated code, holds no credentials"]
    SBX["Sandbox: limited resources, no network during build and test"]:::risk
  end
  subgraph Z3["Zone 3: external providers"]
    FIG["Figma"]:::ext
    LLM["AI provider"]:::ext
    GH["GitHub"]:::ext
    VC["Vercel build and hosting"]:::ext
  end
  SEC -.->|"short-lived, in memory"| WK
  SEC -.-> API
  API --> DB
  WK --> DB
  WK --> OBJ
  WK -->|"files only"| SBX
  SBX -->|"reports, treated as untrusted"| WK
  WK -->|"read-only token"| FIG
  FIG -->|"design content is untrusted"| WK
  WK -->|"design data, no secrets"| LLM
  LLM -->|"output is untrusted code"| WK
  WK -->|"token for one repository"| GH
  WK -->|"team-scoped token"| VC
  GH --> VC
  classDef core fill:#DCEFEA,stroke:#0F766E,color:#12302C
  classDef ext fill:#FFFFFF,stroke:#8FA9A3,color:#17302C,stroke-dasharray: 4 3
  classDef risk fill:#F6E1DD,stroke:#A63D36,color:#5A1E1A