Architecture

agentappbuilder sits between what you want and your repository. It is built on six principles. For each, this page says what works today and what is planned. Planned parts are not available yet.

The parts today

Part	Runs on	Role
Claude Code	Your machine	Reads your code, writes prototypes, captures your running app with a Playwright script, codes what you choose, with your subscription and your credentials. Holds one project key.
Agent server	Supabase Edge Function (Deno), eu-west-1	The MCP server at /mcp and the HTTP API at /api, including /api/captures, stateless. Checks the key and runs each tool and each capture in a transaction limited to its project.
Database	Supabase Postgres, eu-west-1	Projects, apps, screens, frames on two canvases, versions, links, notices, journal. Row level security on every table. Pushes changes to the canvas in real time.
Capture storage	Supabase Storage, eu-west-1	A private bucket of capture images. Only the agent server writes to it; members of the project read it through signed links.
Web app	Netlify, app.agentappbuilder.com	React, Vite and React Flow. Sign-in by email code, the Prototype and Live app canvases, settings and keys. Relays /mcp and /api to the agent server.

Trust goes one way: your Git, database and hosting credentials never leave your machine (only the project key is sent to the platform), and the platform sends nothing to your agent except the answers to its own calls.

P1. The repository is the source of truth

Every convention your agent needs should be a versioned file in your repository, and the platform should only keep metadata about it. If the platform disappeared, your repository would stay complete.

• Today: the platform never writes to your repository. It keeps prototypes, captures of your app and their metadata; your code, your rules and your history stay in your repository.
• Planned: the files that describe the project for the agent (development rules, one specification per change, the design system, the list of screen states, the plan in plan.md) live in your repository and the platform shows them.

P2. Prototype before code

Interface changes are explored as disposable HTML prototypes, with no logic and no network. Only what you choose is built.

• Today: your agent is told to prototype first and not to touch your code when you ask for a prototype. Frames are self-contained HTML, rendered with no script and no network. Each version can carry an optional contract, a JSON description of what the code must honor.
• Planned: the contract of the chosen version becomes the specification and the acceptance tests of the change.

P3. States are first-class

An app is a finite set of screens, each with a finite set of states: empty, loaded, error, modal open. Most defects in generated interfaces live in states nobody listed.

• Today: a frame is one state of one screen. Your agent is told to create one frame per state, and the canvas shows the states of a screen side by side. When your app runs, your agent reaches each state with a script on your machine and captures it: the Live app canvas shows how each state looks today, and you import the states you want into the prototype. The script lives outside your repository and is not replayed by the platform.
• Planned: a manifest of every state in your repository, each with a recipe that reaches it on a real deployment, replayed automatically.

Two canvases

Each app has a Prototype canvas and a Live app canvas. The same state can have a frame on each, with the same key.

	Prototype	Live app
Frames	HTML written by your agent, and captures you imported	Captures sent by your agent’s script
Versions	Numbered, never overwritten; one active, one implemented	None: a new capture replaces the previous one
Who changes it	Your agent adds versions; you choose the active one	Your agent captures again, or deletes a live frame when you ask
Links	Between prototype frames	Between live frames

Importing a live frame adds a capture version to the prototype frame of the same state, active and implemented at once. When you ask for a change on it, your agent recreates the screen as HTML first, then applies the change. The capture stays as a version to compare with.

P4. Quality by harness, not by trust

Your agent is never asked to be careful: the repository is equipped so that carelessness fails.

• Today: before reporting an implementation, your agent is told to run your app’s checks. The platform does not verify them.
• Planned: a harness your agent installs in your repository, through a pull request you review: strict typing and linting, tests written before code, integration tests on real services, security review, CI.

P5. The agent runs where the credentials are

Your agent executes on your machine, with your subscription, your Git access and your database access. The platform never receives them.

• Today: the platform stores no Git, database or hosting credential. Its tools only read and write the project’s own prototype data (apps, screens, frames, versions, links, implementation reports, notices, journal) and captures, and renew its claim link. Captures follow the same rule: the script runs on your machine, where your app and its demo credentials are, and the platform only receives images. It never connects to your app. Nothing it holds can push a commit or run a migration.
• Planned: a read-only GitHub connection, used only to show pull request and CI status. It will forward nothing to your agent.

P6. Human judgement at frame granularity, in your own chat

You review one screen state at a time, each with its own URL, and you say what to change in your own chat.

• Today: every frame has a URL your agent can read. The newest version is active, you can make an older one active again, and your agent reads the active version. The app never sends instructions to your agent; when you change a version that is already implemented, your agent asks you before production follows.

The four loops (roadmap)

The target is a definition of “done” made of four checks, from the cheapest to the most expensive. Only the first exists today.

Loop	Who checks	What	Status
L1. Prototype review	You, through frame URLs	One screen state at a time, before any code	Available today
L2. Acceptance tests	Machines	Tests generated from the contract’s texts, identifiers and interactions	Planned
L3. Continuous integration	Machines	Strict compilation, tests on real services, security review, state recipes on a preview deployment	Planned
L4. Live replay	Machines	State recipes replayed on staging after merge; a failure becomes a correction step in the plan	Planned

None of the planned loops relies on the agent’s own account of what it did: each runs against files and deployments that change only with a visible diff.

Also planned

• Live frames that load a deployed staging of your app in an iframe, built from the state manifest, next to the captures. Captures stay the way to show an app that runs only on your machine.
• The plan: the list of steps your agent keeps in plan.md, shown in the app with the state of each loop.