IF Commons GitHub

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.

projects to written as read and written by Governance: TypeScript, the definition DSL Logical: tables, columns, keys Physical: SQL for each dialect Physical: typed tables
The layers: edit the first, generate the rest
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

  1. Find the concept in governance: its page shows the file and line where it is written.
  2. Edit it there: add an attribute(...) or a relationship(...), give it a definition (the definition is the documentation), and annotate personal data with a purpose.
  3. Regenerate what follows: cd commons/data && bun tools/typed.ts --write
  4. Regenerate what follows: cd commons/data && bun run verify
  5. 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.
  6. 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.

Titles, headings, exports, tables, columns and requirements. Esc closes.