# Bengal Bytes Studio — glossary

> Definitions for the architecture, validation and export concepts used by Bengal Bytes Studio.

Canonical URL: https://studio.bengalbytes.com/glossary

### GraphV1

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.

### Node type

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.

### Edge type

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.

### Connection matrix

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.

### Validation issue

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.

### Journey

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.

### Capacity model

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.

### Runtime Lab

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.

### Agent bundle

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.

### Deterministic export

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.

### Guest mode

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.

### Graph version

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.

### Auto-layout

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.

### Stateless API

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.
