Skip to content

Architecture

Archi edited this page Oct 18, 2026 · 1 revision

Architecture

DemoFlow is one monorepo with two halves: an execution plane that runs scenarios and renders videos on your machine, and a control plane (website and API) that will manage accounts, projects and the demo library. Today only the execution plane is a product; the control plane is scaffolding.

Overview

Part Path Runs on What it owns
@demoflow/core packages/core anywhere zod contracts: scenario, step, locator, project config, timeline, run result; JSON Schema export. Zod is its only dependency, no Node APIs
@demoflow/engine packages/engine Node Playwright execution, readiness checks, origin guard, pointer, masks, sync mark, recording, run files
@demoflow/renderer packages/renderer Node render plan (time map, cursor, camera, captions, key badges, masks, frame, failure) and the FFmpeg compositor, fonts, visual baselines
demoflow (CLI) apps/cli Node ≥ 20 commands, config and home resolution, app start, record, the MCP server, npm staging
fixture app apps/fixture Vite, :3680 the test target for real runs in CI
API apps/api NestJS, :8370 scaffolding: GET /health, Prisma with no models yet
web apps/web Next.js, :3670 scaffolding: one page
packages/shared packages/shared both glue between api and web only

The CLI bundles core, engine and renderer into one npm package, demoflow.

How it works

  1. Contracts first. Every file that crosses a boundary — the scenario, demoflow.config.json, timeline.json, result.json — is a zod schema in @demoflow/core, versioned with schemaVersion: 1 and exported as JSON Schema.
  2. The engine records; the renderer composes. The engine runs the steps and writes a plain recording (source.webm) plus a timeline of what happened when. It never draws effects into the page.
  3. The renderer is a pure function of the run directory. It reads the timeline and result.json, builds a JSON render plan, and FFmpeg executes it. Re-rendering a run never re-runs the browser.
  4. The CLI is the only entry point. run, record and mcp all end in the same run path; the MCP server starts demoflow run as a child process per task.
flowchart TB
  subgraph EP["Execution plane — your machine (Node)"]
    CLI["apps/cli<br/>run · validate · record · setup · mcp"]
    CORE["packages/core<br/>contracts (zod)"]
    ENG["packages/engine<br/>Playwright + Chromium"]
    REN["packages/renderer<br/>render plan + FFmpeg"]
    CLI --> ENG --> REN
    CLI --> REN
    CORE -.-> CLI
    CORE -.-> ENG
    CORE -.-> REN
  end
  subgraph CP["Control plane — scaffolding, Phase 5"]
    WEB["apps/web (Next.js)"] -->|HTTP| API["apps/api (NestJS)"] --> DB[("PostgreSQL")]
  end
  AGENT["Claude Code"] -->|"MCP over stdio"| CLI
  CLI -. "not built: Runner pairing" .-> API
Loading

Principles

  • Recording is separate from rendering — the source stays a faithful capture; every effect is applied afterwards from the timeline. ADR-0004, ADR-0005.
  • Scenarios and config are data, never code — JSON validated by a schema, so an agent can write them and a person can review them. ADR-0003.
  • One package, local first — the browser, the app and the secrets stay on the machine; what may cross to a future cloud is decided up front. ADR-0001, ADR-0008.
  • The source video is 1× — recorded at the viewport size; sharper capture paths were measured and rejected. ADR-0010.
  • Cross-platform — the execution plane is tested on Linux, macOS and Windows on every pull request. ADR-0002.

Using it

Limits / what it never does

  • The web app and the API do not talk to the CLI yet, and no account, Runner or upload exists. See Status and Roadmap.
  • The web app never talks to the database directly; only apps/api imports Prisma.
  • The renderer never reads the page; text on the video (captions, badges, failure card) is drawn by FFmpeg with the bundled Inter fonts.

See also

Clone this wiki locally