Architecture and Modeling Rules

Documentation status: guide — see Maturity and evidence.

Strictly separate entity, role, relation, and event

An entity has its own identity and continuity over time. A role is contextual and potentially temporary. A relation expresses a connection between entities or roles and may carry attributes, direction, validity, and provenance. An event records a dated fact that changes or observes the domain.

Mixing these categories produces ambiguous models, unstable schemas, and business rules that are difficult to locate. Make the distinction explicit from the first modeling iterations.

Protect ontology levels from contamination

A foundational package must not depend on sector concepts, even indirectly through convenient fields, status codes, or enumerations. Cross-domain packages must also remain understandable without mandatory reference to one sector.

When a supposedly reusable package cannot be explained independently from a specific domain, move the specialization upward or split out a cleaner reusable core.

Treat time as a native domain property

Do not add temporal meaning at the end as only CreatedAt and UpdatedAt. Roles, relationships, statuses, agreements, classifications, and responsibilities often have validity intervals or historical meaning. Model that meaning explicitly when it affects the domain.

Design actions as complete business intentions

An action should represent a meaningful business intent, with preconditions, invariants, effects, history behavior, and published events. Prefer AssignRole or ApproveInvoice over technical operations such as UpdateRow.

Avoid hard-coded enumerations when the domain needs a pattern

Use fixed enumerations only for genuinely closed vocabularies. When values have lifecycle, extensibility, hierarchy, ownership, or sector variation, model an explicit concept or classification structure instead.

Reuse through specialization, not duplication

Higher ontology levels should specialize or compose lower-level concepts. Do not copy a foundational model into each sector package and then diverge it independently. Reuse should preserve conceptual identity and make specialization explicit.