Aa14 terms · updated with the app
Every term below maps to behaviour that exists in the product — the same definitions the validator, the capacity model and the exporter use. Each entry is published as a DefinedTermin the page's structured data, with a plain-text mirror at /glossary.md.
The typed architecture document
GraphV1 is the document format that holds a whole system: a schema version, an array of typed nodes and an array of typed edges. It is validated with Zod on the client and on every API route, so a graph that passes is structurally identical wherever it is read. The agent bundle embeds the same document as docs/system-graph.json.
See also: AGENTS.md
One of 21 architecture primitives
A node type names a single architectural primitive, for example client.web, view.page, api.endpoint, service.module, data.entity, data.database, auth.provider, role, job.queue or external.service. Each type declares a Zod configuration schema, a default configuration, a category colour and the handle positions it accepts.
One of 14 semantic relations
Edges are not anonymous lines. Each edge names a relation such as navigates, calls, reads, writes, stores_in, authenticates, authorizes, publishes, consumes or triggers. The validator and the capacity model both read the relation, which is why an edge labelled reads produces a different model than one labelled publishes.
Rules for which edges may exist
The connection matrix defines which node types may connect and with which relation. Drawing a client straight into a database, or an entity call an endpoint, is refused in the canvas with the reason and the suggested alternative, before the graph is ever saved.
A finding with a code, severity and hint
The validator returns issues with a stable code, a severity of error, warning or info, the node involved and a hint describing the fix. There are 23 codes, covering missing primary keys, entities without a database, unresolved role references, duplicate endpoints, synchronous cycles and secrets pasted into configuration.
A replayable path through the system
The Studio detects entry points (clients and screens) and traces every hop through the graph, then groups the hops into named journeys. Selecting a journey highlights its nodes on the canvas so a reviewer can follow one request from screen to storage.
A labelled estimate, not a measurement
The capacity model pushes a target request rate from the entry points through the graph, applies a per-relation factor, and compares the resulting load against a per-type capacity table. It reports utilization per node, the first bottleneck, an estimated p50/p95 and an estimated error rate. The UI always labels it as an estimate.
Real load tests against the app itself
The Runtime Lab sends concurrent HTTP requests to POST /api/v1/simulate and records what actually happened: round-trip p50/p95, server handler milliseconds, throughput, error rate, request counts and heap/RSS. These numbers describe the running Next.js process, not the designed system.
A deterministic specification package
The agent bundle is a ZIP of 14 files: AGENTS.md, README.md, OPEN_QUESTIONS.md, .env.example, docs/system-graph.json, docs/architecture.md, docs/journeys.md, specs/screens.md, specs/api.openapi.yaml, specs/data-model.md, specs/prisma/schema.prisma, specs/roles-permissions.md, specs/integrations.md and tasks/plan.md. It is generated from the graph, so it cannot drift from the design.
Same graph in, same bytes out
File order, JSON key order and timestamps are fixed, and the ZIP is produced with a fixed compression level. Identical input produces identical bytes and the same SHA-256 checksum, which is reported in the X-Bundle-Checksum response header and can be diffed in version control.
No account, no database
Guest mode is the default access model. The proxy applies no gate, Better Auth is never constructed, and the health route reports database: "none". Projects are stored in the browser under the key bbs.studio.projects.v1 and never persist on a server. Setting APP_ACCESS_MODE=auth with a DATABASE_URL restores the hosted configuration.
Optimistic concurrency for the canvas
Every save increments a graph version. A save carries the version it started from; if another tab advanced the project first, the write is rejected with a conflict instead of silently overwriting the newer graph.
elkjs layered placement
Auto-layout runs the elkjs layered algorithm over the graph and writes the resulting coordinates back to the nodes. If the layout engine is unavailable, a deterministic grid fallback keeps the canvas usable.
The graph travels in the request
Validation, journey tracing, simulation and export are stateless routes: the graph is sent in the request body, the response is computed and returned with Cache-Control: no-store, and nothing is written to a database. That is what lets the app run as one process with no external services.
Open the canvas, start from a template, and watch the validator produce the codes described above on a real graph.