Data-Oriented Design in ORE Studio

The first statement is the founding principle of DOD. The five that follow are the operational axioms derived from it. Only the axioms produce review checks. The principle explains why the axioms hold; it is not itself a check, so never score it.

1. Data is memory — the principle. Code exists only to transform data from one representation to another. The representation decides the cost.
2. Access patterns drive layout. Organise data by how and when code reads and writes it together, not by real-world taxonomy.
3. Structure of Arrays (SoA) over Array of Structures (AoS). Prefer parallel contiguous arrays per attribute over arrays of fat heap-allocated objects.
4. Separate hot and cold data. Isolate state read or written on high-frequency paths from metadata read rarely or once.
5. Handles over pointers. Use keys, indices, and offsets instead of per-object heap pointers and object trees.
6. Batch over per-object. Write functions that process contiguous collections in bulk, not one call per object.

The rule is section 5.4 of Richard Fabian's Data-Oriented Design (2013), There is no Entity (dodmain/node5.html). The section names the step of turning a class into "containers of smaller objects, an approach often called composition" as a transitional state, and puts the destination beyond it: "A component based object is nothing more than the sum of its parts", and its definition is "an inventory with some construction arguments".

The reading this project takes is the one the trading model wrote down: no object graph is modelled; rows are atomised and keyed; relationships are foreign keys and joins; there is no parent that owns children, and no aggregate versions as a whole. See dfe15809, the trading data-oriented model.

Three consequences bind this project, and all are reviewable.

• The components are separate types. No aggregate type represents an entity, whether its parts are nested members or a read-time aggregate. Each component has its own type, its own key, and its own codec.
• There is no entity object, so no entity object travels. A message carries one typed array per component, joined by key. One component's fields never appear as nested objects inside another.
• The unified view is assembled for display. A screen that needs one row from several components reads the arrays for one page and zips them. The server keeps filtering, ordering, paging and the total, so the arrays stay aligned. A screen that spans several entities is a read model, never a client join; see NATS entity protocol specification.

This is the target for every component, not for one. Codegen does not reach it yet: it emits one aggregate type per entity and projects that type directly, so a grouped entity's members appear nested on the wire, as the trading instrument fixtures do with identity. The atomised shape is a codegen change, and until it lands an aggregate is a known defect against this rule rather than a licence for it. The atomised shape also relieves the translation-unit pressure the C1202 section records, because no unit reflects one wide entity type.

The target shape, the split rule, the part naming and the read are in The atomised entity: a central row and its parts.

ORE Studio is a database-backed application with Qt clients and a quantitative engine on QuantLib. DOD is not one rule for the whole codebase. A review that demands SoA for a CRUD entity, or accepts a pointer graph inside a simulation kernel, has misread the regime.

The three regimes say where an axiom applies. They do not say what a set of data is, and they are not a substitute for asking. A modeller classifies the data first, then chooses the pattern for that classification: Data classifications: entity, list, family, bundle, package and artefact. It is a closed set of six: an entity, a list of one entity kind, a family written in one transaction, a bundle of related families that one owner applies in one unit of work, a package that carries bundles between systems as bytes, and a boundary artefact. The same page names the anti-type — a hand-written union of unrelated entities presented as one struct — and the test that refuses it.

The rule that decides a set of different types is one question: do the families share an invariant that must hold at one instant, or one operation whose intent is all-or-nothing? With no relatedness, split the set into per-family or per-entity messages; if the bytes must still move, they are a package. With relatedness and one owner, use a bundle. With relatedness and several owners, no bundle spans them: use a package carrying one bundle per owner. A file's contents are not an invariant; a file is an artefact.

The form a modeller fills in, and the review artefact, is The data classification checklist.

Classification precedes the pattern, and it also outranks a compile error. A type that is correctly classified and still does not compile has a technical problem; denormalise for the compiler if the shape needs it, and keep the classification. A compile error never reclassifies the data.

The generated codecs have replaced compile-time reflection, so this limit no longer applies to them. It is recorded because the decomposition it forced is still in the models. A reflected struct had a hard shape limit that nothing in the type system expressed, and crossing it failed the build on MSVC with C1202.

MSVC capped the recursive type-dependency graph that reflection built. The count that mattered was the number of field names in one reflected literal, and that literal depended on how the type was written:

• A plain struct gets a literal of its own members. A nested struct member adds one name, not its members' names. Generated entities with as many as 59 plain members compile on MSVC; on 2026-10-03, 220 of the 287 reflected structs the models generate had more than nine members.
• Flattening a member adds the flattened struct's names to the parent's literal, recursively. Flatten is a JSON-shape decision, never a decomposition fix.
• Writing a std::variant with tags builds one literal over every field name reachable from the alternative being written. This is the shape that has failed: the 502-name trade detail wrapper in sprint 19, and the bond export carrier bond_instrument_data on main in October 2026.

The limit reaches C1202 by two paths. One is the width of a single literal, which is why moving a type between headers does not help and no compiler flag raises it on MSVC. The other is accumulation across a unit: a unit that reflects many individually safe literals can still fail. Measured 2026-10-13, the 24-member tenor_basis_swap_convention literal built in a unit of twelve repository headers and failed inside the configuration document handler, which reaches 58 document element types through 103 repository headers.

The rule: keep the names reachable from one tagged write small, by writing the parts of a large carrier separately rather than as one tagged aggregate. Splitting a wide entity into field_group members lowers the parent literal, so it is a remedy for the per-literal path. It is not a wire decision: the JSON stays flat per There is no entity above, and a change that nests it has changed a contract to fix a compile error. No direct-member count is the C1202 limit; the nine-member figure this page once gave was a margin, not a measured ceiling.

The accumulation path gives a second rule for document models. A model that aggregates several entity families hands its unit a literal width equal to the sum of them, so name one bundle per document model and split a document that covers two. A component's per-entity protocols do not help here, because a document protocol includes the domain headers directly and re-aggregates what the per-entity split separated.

That rule keeps a document message that a real invariant sanctions. It does not sanction a message that carries families the document merely lists. Where there is no cross-type invariant, the file is an artefact and each family has its own message, per Data classifications.

The artefacts a review reads, per component under projects/ores.<name>:

• modeling/*.org — the codegen entity, junction, and field-group models (where the component is codegen-driven). The lookup_entity metatype is reserved in codegen but has no authored instances; do not hunt for lookup models.
• The domain C++ types they generate, or hand-written domain headers in the core facet. This generated representation is the core data model, designed for performance; the review target.
• The SQL schema the entity maps to: the CREATE TABLE statements generated under projects/ores.sql/create/<component>/.
• Repository and service signatures: how code fetches collections and looks up records.
• Kernel entry points and their inner loops, for Regime 1 components.

A component review produces, per component:

• A regime classification with the reasons (what is hot, what is cold, where the boundaries are).
• A findings table: severity (Critical / Important / Minor), effort (Small / Medium / Large), and the criterion each finding maps to.
• A per-regime score of 1-5 where the regime applies.
• An overall data-model verdict and a debt level of Low / Medium / High.

Scores are anchored, not arithmetic. Pick the row the review most resembles:

The debt bands follow the score: 4-5 is Low, 3 is Medium, 1-2 is High. A regime that does not apply to the component is unscored, not scored 0. Two reviews of the same component should land within one point of each other; if they do not, the classification or the evidence was unclear, not the scale.

Hot-path claims need evidence: the loop structure, a profile, or a benchmark. Without evidence, record a layout risk as an opportunity, not a defect. A finding that demands a transformation outside the component's regime is a review error, not a finding.