Docs/Codex/Schema

Schema

erDiagram
   patches ||--o{ entities                 : "patch"
   patches ||--o{ entity_diffs             : "from / to"
   patches ||--o{ entity_resolved_current  : "current"
   patches ||--o{ entity_links             : "patch"
   patches ||--o{ locale_strings           : "patch"
   patches ||--o{ source_keys              : "first / last seen"
   patches ||--o{ imports                  : "audit"
   patches }o--o| patches                  : "parent (forks)"
   entities }o--o| assets                  : "icon_hash → hash (no FK)"

   patches {
      bigint  id PK
      text    game
      text    branch
      text    version
      text    version_raw
      bigint  parent_patch_id FK
      tstz    imported_at
   }
   entities {
      bigint  row_id PK
      text    game
      text    branch
      text    type
      text    id
      bigint  patch_id FK
      text    content_hash
      jsonb   data "NULL = tombstone"
      jsonb   tags
      jsonb   links
      text    icon_hash
      jsonb   assets "multi-asset list"
   }
   entity_resolved_current {
      text    game PK
      text    branch PK
      text    type PK
      text    id PK
      bigint  patch_id FK
      jsonb   data
   }
   entity_diffs {
      bigint  id PK
      bigint  from_patch_id FK
      bigint  to_patch_id FK
      text    op "added | removed | changed"
      jsonb   changes
   }
   entity_links {
      bigint  id PK
      text    from_id
      text    rel
      text    to_id
      bigint  patch_id FK
   }
   source_keys {
      text    game PK
      text    type PK
      text    source_key PK
      text    codex_id
   }
   assets {
      text    hash PK "SHA-256"
      text    media_type
      bigint  bytes
      text    url
   }
   locale_strings {
      bigint  row_id PK
      text    game
      text    branch
      text    locale
      text    namespace
      text    key
      text    value "NULL = tombstone"
      bigint  patch_id FK
   }

Source-of-truth vs derived

LayerTables / views
Source of truthpatches, entities, locale_strings, assets
Derivedentity_resolved_current, entity_diffs, entity_links, source_keys, entity_current and locale_strings_current materialized views

The derived layer is a Postgres-side projection of the ledger — the materialized views (pre-computed query results that refresh on demand) and tables can be dropped and rebuilt from the source-of-truth tables without re-running an import. The HTTP API hot path reads entity_resolved_current; the ledger (entities) is consulted only for point-in-time lookups (?at_patch=) and history.

A snapshot

dark-and-darker on branch=main:

TableRows
patches3
entities (ledger)19,180
entity_resolved_current (hot read path)19,171
entity_links24,947
entity_diffs19,174
assets (~58 MB on disk)1,319
locale_strings (en only)524,081