Repository navigation
Architecture
Archi edited this page Oct 18, 2026
·
1 revision
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.
| 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.
-
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 withschemaVersion: 1and exported as JSON Schema. -
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. -
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. -
The CLI is the only entry point.
run,recordandmcpall end in the samerunpath; the MCP server startsdemoflow runas 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
- 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.
- Read a contract: packages/core/src; the generated JSON Schemas are in packages/core/schemas.
- Read what a run produced: Run Artifacts.
- Change a boundary: read the ADR index first; decisions are superseded by a new record, never rewritten.
- 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/apiimports Prisma. - The renderer never reads the page; text on the video (captions, badges, failure card) is drawn by FFmpeg with the bundled Inter fonts.
- How a Demo Flows · Rendering and Effects · MCP Server
- Contributing · Deployment and Releases
- Product vision (a starting point, not a contract)
- Specs 1 — core contracts, 3 — engine, 24 — FFmpeg renderer
DemoFlow · Issues · Decision records · Specs · MIT licensed
Start
Features
- Scenarios
- Recording Scenarios
- Running Demos
- Rendering and Effects
- Secrets and Masking
- Run Artifacts
- MCP Server
Operate
Reference