Overview

This section defines the foundational concepts of Entity and Subordinate Entity in the Arda system. These concepts underpin every data-bearing module — Items, Business Affiliates, Kanban Cards, Purchase Orders, and any future entity type. The behavioral contracts in this section describe the operations that all entities share; concrete entity pages document deviations and entity-specific extensions.

Sub-pages

Entity Data Authority Behaviors — GEN::ENT-DA: Cross-cutting lifecycle contract for main entities.
Entity Subordinate Behaviors — GEN::ENTSUB: Cross-cutting lifecycle contract for subordinate entities within a parent context.

Entity

An Entity is a piece of information that can change over time while retaining a fixed, immutable identity. Entities are the primary building blocks of the Arda system’s state.

Identity

Every entity carries a system-assigned UUID (eId) that is immutable and unique across the system. The identity is independent of the entity’s information contents — renaming an Item does not change its eId. An entity may also carry additional identifiers (name, SKU, GL code) that serve as human-readable keys, but only the eId is guaranteed to be permanent and globally unique.

Information Contents

The data an entity carries is described as a typed dictionary. The Class of an entity is determined by the type of that dictionary — for example, Item, BusinessAffiliate, or PurchaseOrder. All entities of the same class share the same set of possible fields, although individual instances may leave optional fields empty.

Metadata

In addition to its information contents, every entity carries metadata that describes its system context:

Tenant scope — The tenant that owns the entity. All entity access is scoped to a tenant; cross-tenant access is not permitted.
Lifecycle state — For reference data entities: Draft, Published, or Archived. For transactional entities: a process-specific state machine.
Authorship — The user who created the entity (createdBy) and the user who last modified it (author).
Temporal coordinates — When the entity was created and last modified, tracked bitemporally (see below).

Universe

A Universe is the set of all entities of a given class managed as a group within a scope. A Universe defines:

Membership — Which entities belong to it (typically all entities of a class within a single tenant).
Uniqueness constraints — Rules that prevent duplicate entities (for example, no two Items with the same name within a tenant).
Access control — A UniversalCriteria filter applied to every operation, enforcing tenant isolation and attribute-based access control.
Standard operations — Create, Read, Update, Delete, List, and Count.

Multiple Universes can exist for a given class — one per tenant, or one per parent entity for subordinate entities. The Universe is the operational boundary within which entity identity is unique and constraints are enforced.

Data Authority

The Data Authority is the architectural pattern that governs how entities are created, modified, inspected, and retired. It is organized into three layers:

Protocol Adaptor Layer — Handles communication protocols, request routing, marshalling and unmarshalling of payloads.
Service Layer — Contains business logic, validation rules, and orchestration of entity operations.
Persistence Layer — Manages storage and retrieval using bitemporal tables and an ORM abstraction.

Bitemporal Tracking

Every entity mutation is recorded with two independent time dimensions:

Effective time — When the change becomes effective for business logic and downstream workflows. This is the “real-world” time of the change.
Recorded time — When the change is physically stored in the database. This is the system clock time of the transaction.

Together these form a TimeCoordinates pair. Bitemporal tracking enables the system to answer questions like “What did this entity look like last Tuesday?” (as-of effective time) and “When did the system learn about this change?” (as-of recorded time). Corrections to past data are recorded as new versions without overwriting the original record.

Entity Versioning

Each version of an entity is a separate, immutable record identified by a unique record ID (rId). The version chain forms a linked list:

Field	Description
`eId`	Entity identity (immutable across all versions)
`rId`	Record identity (unique to this specific version)
`createdBy`	User who created the first version (never changes)
`createdAt`	TimeCoordinates of entity creation
`author`	User who created this version
`asOf`	TimeCoordinates of this version
`retired`	Boolean flag — `true` marks this version as a logical deletion
`previous`	The `rId` of the preceding version (`null` for the first version)

Deleting an entity does not remove data — it creates a new version with retired = true. The full history is always preserved.

Access Modes

An entity can be accessed in three ways:

Latest — The system returns the most recent version as of the current request time. This is the default for all interactive operations.
As-of TimeCoordinates — The system returns the version that was current at the specified effective and recorded times. Used for historical queries and audit.
Specific version — The system returns the exact version identified by a given rId. Used for pinned references and compliance.

Reference Data Lifecycle

Entities classified as reference data — slow-changing authoritative records such as Items, Business Affiliates, Units of Measure, and Currencies — follow a three-state lifecycle:

State	Description
Draft	Work-in-progress. Editable. Not visible in business processes. Only accessible to users with editing privileges.
Published	Active. Version-tracked. Visible to all authorized users. Usable in business processes (ordering, replenishment, etc.).
Archived	Retired from active use. No longer selectable in new business processes. Retained for audit and historical reference.

Allowed transitions:

Draft to Published — Requires full validation. On success, the entity becomes immediately operational.
Published to Archived — The entity is retired from active use.
Archived to Draft — A new draft version is created from the archived state, starting a new edit cycle.
Draft to Archived — A draft is discarded without ever being published.

Not all entities implement the full lifecycle. Some entities (for example, transactional records) use a process-specific state machine instead. The behavioral contracts in GEN::ENT-DA describe the reference data lifecycle as the default; entity-specific pages document alternative lifecycles.

Subordinate Entity

A Subordinate Entity is an entity whose existence and lifecycle depend on a parent entity. The relationship is a whole-part composition: the parent is the “whole” and the subordinates are its “parts.”

Composition Relationship

A parent entity may have zero or more subordinate entities of a given class.
A subordinate entity belongs to exactly one parent.
The subordinate stores its parent’s eId in its metadata (parentEId).
Subordinate entities are managed within a child universe scoped to the parent entity.

Examples in the current system:

Parent Entity	Subordinate Entity	Relationship
Item	ItemSupply	An Item has zero or more supply sources, each capturing vendor-specific sourcing data.
BusinessAffiliate	BusinessRole	An affiliate holds zero or more roles (VENDOR, CUSTOMER, CARRIER, etc.).

Lifecycle Dependency

The parent’s lifecycle constrains the subordinate’s lifecycle:

Creation — Subordinates can only be created after the parent exists.
Deletion — When a parent is deleted, all its subordinates are deleted as a cascade. The confirmation dialog for parent deletion must warn the user about this cascade.
Access — Subordinates are accessed through the parent entity’s detail view or through a parent-scoped API endpoint. There is no independent top-level list view for subordinate entities.

Scoped Access

Subordinate entities are queried through a universe scoped to their parent. The API pattern is:

GET    /{parent-type}/{parentEId}/{subordinate-type}          — list
POST   /{parent-type}/{parentEId}/{subordinate-type}          — create
PUT    /{parent-type}/{parentEId}/{subordinate-type}/{subEId} — update
DELETE /{parent-type}/{parentEId}/{subordinate-type}/{subEId} — delete

This scoping ensures that subordinate operations always occur in the context of a specific parent, enforcing the composition constraint at the API level.

Cross-Domain References

Subordinate entities may hold references to entities in other domains. For example, an ItemSupply (subordinate of Item, in the Reference Data domain) references a BusinessAffiliate (also Reference Data, but a separate entity). These cross-domain references enable bidirectional navigation — from an item to its suppliers and from a supplier to the items it supplies.

When a cross-domain reference target is renamed or deleted, the system may propagate the change to subordinates that hold the reference. The propagation strategy is defined per entity type and documented in the entity-specific use case pages.

Entity References

Entities reference other entities in two ways:

Floating References

A floating reference identifies an entity by its eId. Because the eId spans all versions, the interpretation of a floating reference changes as the referenced entity is updated. Floating references are used when the consumer always wants the latest version — for example, an ItemSupply’s reference to its parent Item.

Pinned References

A pinned reference identifies a specific version of an entity by its rId. The referenced data is frozen at the point in time when the reference was created. Pinned references are used when immutability matters — for example, a Purchase Order line that must reflect the item data as it was at the time the order was placed, regardless of subsequent edits.

The choice between floating and pinned references is a design decision made per relationship. The behavioral contracts in this section do not prescribe which reference type to use; entity-specific pages document the reference strategy for each relationship.