Architecture handbook

Start abstract.
Follow every arrow.

Four code-backed views of the same production system. No future-state boxes. No invisible “AI magic” layer.

Read repository handbook ↗Build with Cutable

Request path

System at a glance

Next.js is the interface. Go owns policy and orchestration. Neon is durable state. OpenRouter proposes work. E2B executes generated applications.

Cutable system context from browser through Vercel and the Go API to Neon, OpenRouter, and E2B

Product path

One user build

An authenticated, owner-scoped project moves through an atomic demo-or-BYOK gate, then streams agent events and an isolated preview back to the builder.

Cutable user flow from sign in and prompt through the run gate, agent, preview, and iteration

Control loop

Model proposes. Go controls. E2B executes.

The model returns one tool call at a time. Go constrains paths, dispatches registered tools, persists changed files, and returns results for the next decision.

Cutable AI agent loop showing OpenRouter decisions, Go tool execution, E2B operations, and Neon persistence

Production path

Trust and delivery

The runtime and delivery boundaries are explicit: browser session state, Vercel edge, Myprod control plane, Neon data plane, and digest-pinned container delivery.

Cutable trust boundaries and deployment path through GitHub, GHCR, Myprod, Nomad, and Traefik

Verification map

Claims resolve to code.

These links are the evidence behind the diagrams. Follow them when behavior changes; regenerate the views when the architecture changes.

Owner-scoped accessapps/backend/internal/store/store.goStore.Project includes user_id in the query.Atomic demo claimapps/backend/internal/store/store.goOne conditional UPDATE increments usage and returns the claim.Session-only BYOKapps/backend/internal/httpapi/websocket.goPer-run providers are built in the socket handler; no store call receives keys.React-root file pathsapps/backend/internal/agent/agent.gosafePath rejects traversal outside /home/user/react-app.Isolated executionapps/backend/internal/provider/e2b.goFilesystem and process calls target the project’s E2B sandbox.Serial model toolsapps/backend/internal/provider/openrouter.goparallel_tool_calls is disabled.Nonroot backendapps/backend/DockerfileThe final Distroless image runs as nonroot.Immutable delivery.github/workflows/publish-backend.ymlBuildx publishes commit tags and records the GHCR digest.

Honest boundaries

What the boxes do not promise.

OpenRouter and E2B are third-party processors for inference and execution.
The two-run demo is an account allowance, not a token or compute budget.
Preview availability depends on E2B lifetime and a successful Vite start.

Generated code still requires review before a real deployment.
Neon persists current files; Cutable does not provide Git history per project.
BYOK is session-only handling, not end-to-end provider encryption.