The layers
A model is written once, in governance, and everything else is made from it. Read the layers from the top: each is made from the one above it, and each element says which element it came from.
Diagram source
flowchart LR
G[Governance: TypeScript, the definition DSL] -->|projects to| L[Logical: tables, columns, keys]
L -->|written as| S[Physical: SQL for each dialect]
L -->|read and written by| T[Physical: typed tables]Governance
What the business means, written in TypeScript with the data definition DSL: `defineModule`, `concept`, `attribute`, `relationship`, `codeList` and annotations (privacy, security, ownership, lifecycle). This is the layer a person or an agent edits. A concept's `definition` is its documentation. Everything below it is made from it and is never edited by hand.
Holds: module, concept, attribute, relationship, codelist, code
Logical
The tables, columns, keys and constraints that a projection (`projectDomain`) makes of governance, independent of any engine. Not written by hand: change governance and the logical schema follows. Each element says which governance element it came from.
Holds: table, column, foreign-key, unique, index
Physical
The forms the logical schema takes: the SQL statements for each dialect (`bind(schema, { dialect })`) and the typed tables a program reads and writes (`sql/typed/models/<model>.auto.ts`, written by `bun tools/typed.ts --write`). Generated and committed: never edit them, change governance and generate again.
Holds: ddl, typed-table
How to change a model
- Find the concept in governance: its page shows the file and line where it is written.
- Edit it there: add an
attribute(...)or arelationship(...), give it adefinition(the definition is the documentation), and annotate personal data with a purpose. - Regenerate what follows:
cd commons/data && bun tools/typed.ts --write - Regenerate what follows:
cd commons/data && bun run verify - Never edit a generated file (its name has
.auto.) or the SQL: change governance and generate again. The pages of this site are made from the same values, so they follow. - Check: a concept, attribute, relationship or code list with no definition, and personal data held for no purpose, are findings on the Models page.
For an agent
Every page of this site has a Markdown twin (the same path with .md) and each model is published as JSON (models/<name>.json, listed in llms.txt). An element's id is stable, so the JSON and the pages name the same things, and the trace lists what each element is made into.