Codegen org-entity meta-model
Table of Contents
A codegen entity model is a single literate org-mode file that
describes one entity (e.g. party) and drives code generation across
every technical space that entity touches: SQL and several independent
C++ facets (e.g. ores.cpp.domain, ores.cpp.repository,
ores.cpp.qt). In MASD terms, this hub — together with its
segment pages — is the metamodel for one metatype, ores.codegen.entity
(domain_entity); it is one entry in the Codegen meta-model registry of
all eight metatypes ores.codegen recognises. It does not describe any
one entity, it describes what any entity model file is allowed to
contain. See Applied MASD for how ORE Studio instantiates MASD's
logical/physical space, metatype, facet, and archetype concepts, and
for why an entity model file looks the way it does at all (§ "The
entity model file as a unified literate document") — those concepts
are exactly the organising principle this hub uses below.
This page stays deliberately short: an overview, the file-level conventions every entity model shares regardless of which facets it uses, and a table routing to the segment page that documents each facet's fields, worked example, and paste blocks in full. Go to a segment page for the exhaustive per-property reference; come back here only for the shape of the file as a whole.
Role: structural metamodel, not variability
This hub and its segment pages are the structural metamodel — they
answer "what shape can an entity have": which fields, sections, and
artefacts a model file may declare, root conventions common to every
technical space (TS) below, then specialised per TS (SQL), then
further specialised per sub-TS where one TS itself splits into several
independent facets (C++ splits into domain/repository/service/
protocol/NATS/Qt/generator/presentation, each its own segment page
below). A segment page may name a knob when a structural artefact
only exists because that knob is set (e.g. SQL's hierarchy function
exists only if :has_parent_id: true) — but the knob's authoritative
type, default, and effect live in exactly one place, never here: the
ORE Studio Variability Model. That document answers the other
question — "how is one fixed shape's projection tuned" — cross-cutting
by feature bundle rather than by TS/facet, since that is variability's
natural organising axis, not structure's. Neither document repeats the
other's content; each links to the other at the point the reader needs
it.
File-level conventions
See Codegen entity meta-model — file-level conventions: file naming, required frontmatter, and the prose body — the conventions every entity model shares regardless of which facets it uses, and the document-type archetype (ores.doc.modeling.entity_org) that scaffolds them.
compass add entity_org --shape <name> scaffolds a new entity model
with a named domain_entity shape's knobs already set correctly
(simple-text-key, fk-scoped, hierarchical-composite, richest,
timeseries — sampled from the reference entities in the shape
table below), rather than the bare, unknobbed skeleton a plain
compass add entity_org produces. Anything the shape can't derive
(actual columns, foreign-key targets, display fields, …) is left as
an explicit TODO in the scaffolded file, never silently omitted.
Individual --entity-<knob> flags override any preset value.
Segments
Entity specializes Base with its own frontmatter type and one typed
field per segment below — Codegen meta-model documents Base and
CommonFrontmatter on their own, without any metaclass's
specialization. An entity is modelled as a set of segments, which loosely correspond
to the properties needed to support the various aspects of the
technical spaces the entity targets — Keys and columns and SQL
for the database layer, one segment per independent C++ facet
(domain, repository, service, protocol, NATS, Qt, generator,
presentation) for the application layer. Segment classes are drawn
empty here — each has its own structural fields, documented on its
own page, not duplicated in this overview. Several segments also
document their own paste blocks.
(Source: org_entity_meta_model.puml,
rendered with plantuml.)
Every segment below is its own page — this table is the routing table, not the reference itself.
| Segment | What it covers | Facets |
|---|---|---|
| Keys and columns | Flags, Primary key, Natural keys, Columns — shared by C++ and SQL. | ores.cpp.domain, ores.cpp.repository |
| SQL | Table naming, the has_parent_id hierarchy knob. | ores.sql.schema |
| C++ Domain | Domain includes: the plain domain struct. | ores.cpp.domain |
| C++ Repository | Flags, Repository, Entity includes, Conventions, Table display: entity, mapper, CRUD. | ores.cpp.repository |
| C++ Service | Business-logic wrapper, authorization, event firing on mutation. | ores.cpp.service |
| C++ Protocol | Request/response message struct definitions. | ores.cpp.protocol |
| C++ NATS | Command pipeline (handler, sub-registrar) and event pipeline (eventing, event-registrar, event-cache) — one flow, five facets. | ores.cpp.nats-handler +4 more (see segment page) |
| C++ Qt | MDI window, detail dialog, controller, client model. | ores.cpp.qt |
| C++ Generator | Custom repository methods' generator sibling: fake-data generators. | ores.cpp.generator |
| C++ Presentation | History-diff field rendering. | ores.cpp.presentation |
See also
- Codegen entity — post-generation checklist — the fixed manual integration steps every newly-generated entity still needs.
- Codegen meta-model — the registry this hub is one entry of, and the common frontmatter every metatype (including this one) specializes.
- Applied MASD — the methodology this hub instantiates.
- Variability — the abstract MASD vocabulary (feature, feature bundle, profile, binding point, configuration scope) this hub's § "Role" above borrows.
- ORE Studio Variability Model — the variability metamodel counterpart to this structural one: every authored knob's type, default, effect, and feature-vs-predicate classification, organised by feature bundle rather than by TS/facet.
- Codegen input org-file schema reference — a shallow, quick-reference index across all eight entity-model doc types (
entity,lookup_entity,junction,field_group,table, …), one line per section. This hub is the deep-dive forores.codegen.entityspecifically; that page is the map of the whole territory.