Entities
Table of Contents
1. Summary
An entity is one record the system keeps: a row, the C++ type that carries it, the repository that reads and writes it, the protocol that moves it, and the screen that shows it. One name runs through all of them.
This hub gathers the pages that describe those layers. Read Entity Lifecycle first if you are building one, and Entity naming if you are only choosing a name.
2. Where to start
| Page | Read it for |
|---|---|
| Entity Lifecycle | The order the layers must be built in, and the per-transport patterns |
| Entity naming | The table, entity, lookup and event names every entity follows |
| Codegen input org-file schema reference | The syntax of a model, and every pattern a model opts into |
3. Choosing the shape
An entity is authored as a model, not as code, and the shape must be chosen before anything is written. The shape decides what the generator produces.
- Codegen input org-file schema reference — the syntax for every pattern.
- Codegen patterns: choosing a model shape — which shape to pick, and the neighbouring shape it is mistaken for.
- Adding a flagged combo field to a codegen entity — a worked change to a model.
- How do I create a new entity? — the end-to-end recipe.
4. Naming, storing and addressing
| Page | What it owns |
|---|---|
| Entity naming | The name of the table, the type, the lookup and the event |
| PostgreSQL Architecture | Schema layout, roles, and the bi-temporal design |
| Data-Oriented Design | The three regimes, and how to review a model against them |
| Entity Addressing | How one record is named so a screen, a request and a stream all reach the same row |
| NATS entity protocol specification | The subject grammar, verbs and envelopes every entity message follows |
5. Writing one
Three rules a change must keep, each with its own page because each is easy to break in passing.
| Page | The rule |
|---|---|
| Entity-table writes | A write goes through the repository, so the claim and the audit stamps are made once |
| Entity-composed registrars | A registrar composes the entity's own rather than restating it |
| Where should an entity-mirror cache live? | Placement of a cache that mirrors an entity |
6. The component an entity lives in
| Page | What it covers |
|---|---|
| Component Architecture | The api/core/service split, and where each layer goes |
| Component Clean Standard | The checklist a component passes to join the codegen gates |
| How do I document an entity? | The manual chapter and screenshot names for a new entity |
7. See also
- Knowledge — the index this hub is listed under.