# 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_json` the 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

```mermaid
flowchart TB
  ROOT(["ROOT<br/>bricks/artefact"])

  subgraph BASE["Base render kinds — LOCKED artefact_types · each extends ROOT directly"]
    direction LR
    T["table"]:::b
    R["relationship"]:::b
    AP["app"]:::b
    MD["media"]:::b
    W["workflow"]:::b
    RO["role"]:::b
    PM["permission"]:::b
    IG["integration"]:::b
    CO["component"]:::b
    DF["data_flow"]:::b
    PG["page"]:::l
    DT["data<br/>(seed row content)"]:::l
  end

  ROOT --> T & R & AP & MD & W & RO & PM & IG & CO & DF & PG & DT

  subgraph EXT["Extension library — extends is the primitive · artefact_type copied forward"]
    direction TB
    IN["input<br/>type = component"]
    DI["date_input<br/>type = component"]
    MF["club/members@v1<br/>type = table"]
  end

  IN -->|extends| CO
  DI -->|extends| IN
  MF -->|extends| T

  SCOPE["Who reads an extension follows<br/>who owns its catalog —<br/>platform (everyone) · a group · one person<br/>+ organisations it is shared with"]:::note
  EXT -.- SCOPE

  classDef b fill:#e7f6ec,stroke:#4a9e6b,color:#123;
  classDef l fill:#fdf3e0,stroke:#d6a24a,color:#321;
  classDef note fill:#fff8e6,stroke:#d6b36f,color:#4a3a1a;
```

*Green = built · amber = latent (handled by Bricks, not yet a first-class artefact).*

> **`data` is not `table`.** A recurring confusion: the amber `data` kind 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 latent `data` kind is a different thing entirely: the **seed row content** that pre-populates a table (reference/lookup rows like an `age_bracket` list, 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_type` is 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.
- **`extends` is 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 the `artefact_type` forward**: an `input` extends `component`, a `date_input` extends `input`, and all three stay `artefact_type: component`. What makes an extension specific is its `extends` chain and its concept — **never a new render kind**. So `input` and `date_input` are *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_input` extends `input` extends `component` — all three carry `artefact_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 why `artefact_type` is read directly off the ontology rather than resolved by climbing `extends` — 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. `extends` is 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 `members` table (`club/members@v1`) extends the platform's `table` base kind exactly the same way `date_input` extends `component` — 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

```mermaid
flowchart LR
  subgraph DESC["ONTOLOGIES · descriptions in the published store"]
    ON["a selection: the bricks a person ticked<br/>+ everything they require, by exact ref"]
  end

  DESC ==>|compose| TS["TenantSpec"]
  TS ==>|render| MAN["manifest ·<br/>table · relationship · app · component ops<br/>+ reasoned concept graph"]
  MAN ==>|apply| RUN

  subgraph RUN["ARTEFACTS · the RUNTIME the system reads to run itself"]
    direction TB
    RT1["table → Postgres table"]
    RT2["workflow → workflow_json<br/>the engine executes"]
    RT3["data_flow → egress guard gates on it"]
    RT4["role · permission → RLS policies read them"]
  end

  classDef x fill:#eaf0ff,stroke:#6f8fd6,color:#1a2a4a;
```

**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](/technical/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](https://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:

1. **Read** your tenant's artefacts — they carry their own type, spec and ancestry.
2. **Save** them as versioned, extendable ontologies, in your catalog, wherever you keep it: your own repository, a table, object storage, files on a laptop.
3. **Compose** a tenant spec from that catalog, with your own tooling.
4. **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](/technical/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

- **`extends` is the primitive; `artefact_type` is 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 `data` means seed row *content*, not tables — a `table`'s structure is a built kind.
- **Type is read directly, never inferred from lineage** — `extends` is 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](/technical/studio-ai-tools); the runtime artefacts are covered in [the data API](/technical/data-api-permissions), [workflows](/technical/rpc-and-workflows), and [data flows](/technical/data-flows).*
