The concepts graph & ontologies
Bricks Technical Documentation
What Bricks means by concept, ontology and artefact — how ontologies describe a system, artefacts are the runtime that system reads to run itself, and extension is the primitive that puts bricks together.
Bricks builds a system by putting bricks together. The "bricks" are artefacts, and the vocabulary that describes how they fit is a library of ontologies. Underneath every app is also a concepts graph — a human-legible map of what the app means — kept alongside the machinery that runs. This page defines the three words, shows how ontologies extend each other, and how a selection of them composes into a running system of artefacts.
Three words, three roles
- Concept — a unit of meaning. "The Members table", "the check-in workflow", "the coach role". A concept is what a human reasons about: a kind, a canonical English label, localized display text, and a lifecycle state (live, partial, planned, retired).
- Ontology — a description: the footprint of a system. What ran in the past, what should run again as a replica, or what is planned to run a certain way — depending on how it is used. An ontology is dormant by nature: it describes, it does not run. Ontologies form a library connected by extension.
- Artefact — the runtime: the configuration the system actually reads to run itself. A table is the Postgres table; a workflow is the
workflow_jsonthe engine executes; a data flow is the declaration the egress guard enforces. An artefact also describes itself — it declares its own intrinsic type and its provenance.
The unifying idea (an artefact is an ontology): both share one self-defining structure — a type it declares about itself, a lineage it was forked from, and the concept it realises. The ontology is that structure at rest (a description); the artefact is the same structure materialised as runtime. It makes no sense for half the system to be artefacts and half not — that is the whole point of Bricks.
Base kinds and the extension primitive
Green = built · amber = latent (handled by Bricks, not yet a first-class artefact).
datais nottable. A recurring confusion: the amberdatakind does not mean "tables are unsupported."table(green) is a fully first-class, built artefact — it materialises the Postgres table (its columns, keys, indexes). The latentdatakind is a different thing entirely: the seed row content that pre-populates a table (reference/lookup rows like anage_bracketlist, starter records). Structure ships as artefacts today; rows are not an artefact kind — a manifest can load them through a dedicated data-loading operation, but nothing registers them as artefacts. Tables are supported — the contents poured into them are not a first-class artefact kind.
Two things carry an artefact, and neither is answered by walking the lineage:
artefact_typeis intrinsic. It is the small, locked set of render kinds the system knows how to materialise — the dispatcher's targets. Each base kind extends the root directly; the base kinds are not layered on each other. Adding a kind here means adding a materialiser.extendsis the primitive. Any ontology may extend any other — a base kind, a platform-wide "vanilla" ontology available to everyone, or a tenant/agency's own ontology. Extension copies theartefact_typeforward: aninputextendscomponent, adate_inputextendsinput, and all three stayartefact_type: component. What makes an extension specific is itsextendschain and its concept — never a new render kind. Soinputanddate_inputare component extensions, not base kinds.
Where an extension lives is the catalog that holds it, and who reads it follows who owns that catalog: the platform (the vanilla catalog, readable by everyone), a group (a company's own catalog), or one person. The owner can also share a catalog with an organisation — see Catalogs below.
Extending an ontology
Extension is a single, small operation: point a new ontology at a parent (any existing ontology — a base kind or another extension), copy the parent's artefact_type forward, and give it its own concept.
extend(parent, artefact_type ← parent.artefact_type, concept) → new ontology
ref: the new ontology's own coordinate
extends: the parent's ref (provenance — never dispatch)
artefact_type: copied from the parent, never re-declared
concept: what this specific ontology means
Two things fall straight out of "copy forward, never re-declare":
- A chain never changes what it renders as.
date_inputextendsinputextendscomponent— all three carryartefact_type: component. Walk the chain as far as you like; the render kind at the end is the same one at the start. This is whyartefact_typeis read directly off the ontology rather than resolved by climbingextends— the climb would give the same answer, but only because nothing along the way is allowed to change it. - Extension only adds. A child ontology narrows or specialises what its parent means (a date input is a more specific kind of input) — it does not redefine the parent's render kind, and it does not remove anything the parent declared.
extendsis pure ancestry: useful for lineage, audit, and "what was this forked from," but it plays no part in how the artefact is built or in idempotency. - A fork is also an extension. A tenant's
memberstable (club/members@v1) extends the platform'stablebase kind exactly the same waydate_inputextendscomponent— the mechanism does not distinguish "specialising a UI primitive" from "forking a table for one tenant." Extension is the one operation; what varies is only who authored the result and whether it stays platform-owned or becomes tenant-modifiable.
Catalogs — groups of ontologies, not ontologies themselves
A catalog is not an ontology. An ontology describes one thing (a table, a workflow, a specific date-input component). A catalog is a curated group of ontologies scoped to a domain — a named set someone assembled because those ontologies belong together for a reason: they serve the same platform, the same business vertical, the same kind of user, the same use case, or the same publisher's product line. ref resolves within a catalog; a catalog itself is the thing that groups many refs into a coherent, extendable set.
What scopes a catalog is the domain it was assembled around — not who happens to publish it. Authorship (platform, an agency, a partner) is one attribute of a catalog, not the defining one. In practice, the domains that plausibly justify a catalog include:
- Platform-wide — genuinely universal building blocks, useful regardless of business or vertical. This is the vanilla catalog: the base kinds (table, workflow, component, …), each extending root directly.
- A business vertical — ontologies recurring across a category of business (e.g. an internal library scoped to one vertical, built from what actually recurs across real tenants in it).
- A user persona — ontologies shaped around how a particular kind of user works, rather than a business category.
- A use case — ontologies assembled around solving one recurring problem, independent of vertical or persona.
- An agency's own product — an agency publishing a catalog of its templates/patterns as something it offers, the way a template marketplace would.
Today the platform ships the vanilla catalog and hosts catalogs owned by a group (a company's catalog — Bricks' own brand catalog is one) or by one person. Who reads a catalog follows its owner:
- Everyone reads the vanilla catalog.
- A person reads the catalogs they own and those owned by a group they belong to, in whichever organisation they are working. Every member of a group co-manages the group's catalogs.
- An organisation reads a catalog its owner shared with it. The owner — the person, or an admin of the owning group — grants an organisation access (granting also takes the right to administer that organisation); every member of it, and its Studio, then reach the catalog while working there, until the share is revoked. Sharing gives access and never copies: an artefact made from a shared ontology keeps that ontology's ref, which still says where it came from after the share ends.
What is not built: a partner tier (a partner's published product line), and any public discovery — there is no directory where a catalog is advertised to people it was not shared with. What is settled is the mechanism: whatever the domain, a catalog is reached the same way — an ontology's ref resolves against it, and every entry carries its own artefact_type, extending some parent.
Where things live
The catalog is written as files, wherever its owner keeps them, and nothing runs from them. Once published it is a live store of documents, each addressed by its ref, that the platform reads. An artefact record declares and tracks the provenance of every artefact of every kind. The runtime is the actual thing the system runs, which the artefact record points to.
The concepts graph: nodes, why-logs, soft pointers
The concept graph is the meaning layer that sits beside the artefacts. It is built from three records:
- Concepts — the nodes, one per unit of meaning, unique within a tenant by kind and label.
- Glosses — an append-only "why" log on a concept. Each is a terse one-sentence note ("dark mode hurt accessibility for our users") that captures a decision so future work inherits the reasoning. Short by design; an unchanged rebuild adds none.
- Refs — soft pointers from a concept to the real thing it stands for.
The defining choice: refs have no hard database link to their targets. When the table or workflow a ref points at is deleted, the ref does not break — it becomes a tombstone that remembers the last-known name. The graph becomes an informational memory instead of corrupting. A concept usually carries two refs — a physical ref to the concrete machinery (authoritative) and an ontology ref to the artefact's catalogue coordinate, so ancestry is queryable rather than buried in prose.
Composition: ontologies become the running system
Composition is what turns a set of ontologies into a system of artefacts. A selection of the extension library composes into a TenantSpec, which renders into a manifest of artefact.upsert operations (one op, keyed by artefact_type) plus a reasoned concept graph, which apply materialises into runtime. Everything in the bottom box is the running system — read by the engine, the egress guard, RLS.
What each step does:
- Compose is deterministic. The spec holds exactly the bricks in the selection, plus whatever those bricks declare they require. A brick can be selected more than once, each time labelled with what it is for (two calendars: one for training sessions, one for bookings). A requirement resolves only by its exact ref, version included — a near miss is reported as a gap, never quietly replaced by something similar. Nothing is dropped: every input ends up in the spec, or in its list of gaps or conflicts.
- Render emits the tables, the relationships between them those tables imply, one app per app the selection asks for (built from the standard app base, with a home page that shows the components placed in it), and the components, each in the app it was chosen for. It does not yet emit roles, permissions, workflows, data flows or the other kinds: those are returned as deferred, visible with their ref, never dropped. Render also writes why each brick is there into the concept graph.
- Apply handles every kind. What render defers can still be reached by authoring the manifest directly — see creating a tenant-spec manifest.
The composer. Composing from bricks is a way into a new organisation, beside the discovery conversation with Studio. The person says what they need; an AI proposes bricks from the catalogs they may use; the person adjusts the selection and builds a backbone, which Studio takes over without having to invent it:
- Who sees it. People holding the compose right (platform admins, and people a platform admin granted it to); onboarding offers it only to them.
- The proposal. One AI call reads a short index of the tables and components the person may use and proposes some, one sentence each on why, and the apps to build them into. It chooses only among what it was shown: anything else it names is dropped. Relationships between the chosen tables are added by the platform, not by the AI. A proposal is paid in Bricks tokens, like a Studio turn, unless the person's proposals are free.
- The person decides. The bricks are shown grouped by catalog and linked by what each needs, on a map or as a list. Each can be removed, moved to another app, or seen working on demo data before anything is built; any brick the person may use can be added by hand.
- Named projects. A person keeps any number of named compositions, each with the need it answered and its proposal, saved with or without a build, and visible to them alone.
- Building rebuilds the project's draft. Each build saves the selection and rebuilds that project's own draft organisation from scratch — a brick taken out disappears — through the same checks as any apply. Its apps are published, so the person opens them right there, next to the plan: failures, gaps, deferred items and what is left for Studio. Building is free.
- Open in Studio. Opening a built project turns its draft into a live organisation, through the same provisioning the discovery conversation uses — for the person, or for a group that lets them create organisations on its behalf. A project never built, or partly failed, cannot be opened.
- No branding. The result is a backbone, not a finished app: the apps carry neutral defaults and no brand until Studio gives them one.
Seeing bricks working. Every catalog a person may use can be browsed with its bricks shown working: components rendered on demo data, workflows run on sample inputs in a rehearsal that is always undone and never reaches an inbox, a payment or another service. Demo data is the catalog's; nothing that builds an organisation reads it.
Beside composition, the graph also accretes. Studio AI creates a table, role or workflow and updates the concept graph in the same motion. The unified artefact.upsert op is live for table, relationship, app, media, workflow, role, permission, integration, component, data_flow, and for the retention and export declarations. Two kinds are still latent — page and data (seed row content — not tables, whose structure is a built kind): Bricks runs them, but does not express them as first-class artefacts.
You own your catalog; the manifest is the only contract
A catalog is yours to own, to host, and to write in whatever vocabulary you already use. If your team keeps its ontologies in OWL, in schema.org terms, or in a house format nobody else uses, that is not a problem to be solved — it is simply outside what we govern.
The only contract is the manifest. A tenant is provisioned by applying a manifest of operations. The coordinates in that manifest (ref, its ancestry extends) are free-form identifiers — nothing validates that they look like ours. A manifest coordinated by https://schema.org/Person or urn:owl:acme#Organization is accepted exactly like one coordinated by a Bricks ref, because dispatch reads an artefact's own artefact_type and never its coordinate.
So you can run the whole cycle yourself, with nothing to request from us:
- Read your tenant's artefacts — they carry their own type, spec and ancestry.
- Save them as versioned, extendable ontologies, in your catalog, wherever you keep it: your own repository, a table, object storage, files on a laptop.
- Compose a tenant spec from that catalog, with your own tooling.
- Apply it — the one step that touches us.
An artefact your team authored in one tenant can then go into your own catalog and be composed into the next tenant from there.
What the platform hosts is optional. The published catalog store, catalogs a group manages from the platform, sharing a catalog with an organisation, and the composer all save you work, but none is required: anything you express with your own catalog and your own tooling works through the manifest whether or not you use them.
One practical note: our own render step resolves Bricks-style refs against Bricks catalogs, so a foreign-vocabulary catalog produces its manifest through your own tooling rather than through render. Hand-authoring or generating a manifest is a documented, supported path — see creating a tenant-spec manifest.
How it surfaces to you
You never edit these records by hand. Tenant members can read their concept graph; writing it is reserved to admins and the assistant. In the Studio you talk to the AI, and the graph is what it consults to understand your app, where your explanations are remembered as glosses, and what keeps a stable English name per concept while showing you a localized label.
Worth knowing
extendsis the primitive;artefact_typeis copied forward — a specialization is an extension, never a new render kind.- Base kinds are locked; two runtime kinds are still latent — page and data are not first-class artefacts through the unified op. Here
datameans seed row content, not tables — atable's structure is a built kind. - Type is read directly, never inferred from lineage —
extendsis provenance/audit only. - Refs tombstone on deletion — they remember the last name rather than breaking.
- A catalog is a domain-scoped group of ontologies, not an ontology itself — the platform ships the vanilla catalog and hosts catalogs owned by a group or a person; an owner can share a catalog with an organisation. What is not built is a partner tier and any public discovery of catalogs you were not given.
- Composing is deterministic — the composer builds exactly what was ticked plus what it requires, previews and rehearses before writing, and uses no AI; render still defers every kind beyond tables, relationships, apps and components.
- You own your catalog — host it where you like, write it in OWL or schema.org terms if that is what you use. The manifest is the only contract; what the platform hosts for catalogs is optional.
This page describes the v3 model and says what runs today, what is latent (run by Bricks but not yet a first-class artefact) and what is not built. The graph is read and written by the assistant in Studio AI tools; the runtime artefacts are covered in the data API, workflows, and data flows.