Domain Design Overview

Arda’s domain modules share one design anatomy. This page states it once, in plain language, and maps each idea to the pages that own its full treatment — the functional module pages, the glossary, the module patterns, and the business flows. If you read nothing else before the module pages, read this.

1. Everything is history — the occurrence log

A module does not store “the current row” and overwrite it. It records occurrences — the acts themselves (create, update, submit, receive, revoke), each with its payload, its actor context, and its outcome. History is never erased; corrections are new occurrences. This is why every module page has an Operations table rather than a CRUD list: the operations are the domain vocabulary.

2. State is a projection — and refusals are first-class

The subject’s current state is computed from its committed history (last write wins, per field family), never stored as an independent truth that can drift. Every operation is bracketed by gates: preconditions checked at the moment of the act, against the subject’s real current state. A disallowed act is not an exception or a silent no-op — it is a recorded refusal with a precise reason, so the caller learns exactly what to fix and the audit trail keeps what was attempted. The glossary’s gate and refusal vocabulary is used in this exact sense on every module page.

3. Commitments and freezes

Documents compose freely, then commit: an order’s Submit, a receiving line’s Receive. At the freeze, the defining content stops changing and references to reference data become pins — reads as of a version, kept forever, never dangling. Before the freeze, references float and stay current; retirement of reference data gates new commitments only, never history. The full discipline is the Reference-Data Module Pattern.

4. Ownership by genesis

Where two subsystems could contend for the same resource (inventory pools held by kanban cycles, demand holdings, receiving lines), the design avoids coordination by minting the resource inside the owning act: a fresh pool is born in the act that attaches it, so a collision cannot be composed in the first place. Exclusivity then holds by construction — each holder kind publishes a provenance guarantee (a held pool is exactly what some committed act named), and the mint discipline keeps the holders disjoint. Runtime monitoring watches the discipline rather than legislating it.

5. Everything is observable

Modules announce what happened — notifications — and other modules react without being called. The caller-facing operation and the observer-facing notification are different contracts, documented separately on each module page. Cross-module consistency is convergent: listeners are idempotent, missed windows self-heal, and reconciliation records (e.g. the production delivery) are the durable source both sides settle against.

How this is verified

The anatomy is not aspirational: it is checked at three levels. Each module’s suite exercises its gates and refusals; law probes in the running system witness the design’s invariants continuously; and the formal design model (maintained in the working design record) proves the deep properties — the exclusivity laws above carry machine-checked proofs. The documentation on this site is written to stand on its own: where a page leans on a formal result, it states the result in prose and names the module that owns it.

Where to go next

• Functional documentation — the module pages: entities, operations, gates, notifications, per domain.
• Module status — what is built, what is designed, what is roadmap.
• Glossary — the model-defined vocabulary, grouped by owning domain.
• Business scenarios — end-to-end narratives showing the anatomy at work.
• Module patterns — the implementation-facing structure behind the module pages.