> For the complete documentation index, see [llms.txt](https://voyzu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://voyzu.gitbook.io/docs/customising-and-extending-voyzu/domain-data-model-specification.md). # Domain Data Model Specification *** ## Concept A **Domain Data Model (DDM)** defines the **structure, meaning, and rules of a business entity**, independent of implementation. A DDM: * is **not** a database schema * is **not** an API contract * is **not** a UI specification Instead, it defines: * data shape * what that data means * how it relates to other data * what states it can be in * what rules must always hold All system entry points (UI, API, imports, jobs) operate against the same DDM. > The DDM is the **canonical definition of a business entity**. *** ## Canonical Sections A DDM is always composed of the following numbered sections, in order. *** ### 1 Definitions > Domain-specific terms and derived classifications used throughout the model. * Used to define concepts that are: * not necessarily persisted * derived from data * reused across rules Examples: * “In use” * “Outstanding” * “Fully paid” #### 1.1 List of Definitions A list of definitions *** ## 2 Properties > Persisted data fields of the object. * Represents the **stored shape** of the entity * Includes:. * identifiers * fields with foreign keys * Excludes: * system-wide fields such as audit fields * computed values that are not persisted * helper functions * transient UI data #### **2.1 Properties Matrix** A table of persisted properties with property meta-information. See the example DDM. #### 2.2 Additional Property constraints > Rules that apply to individual properties or their modification, beyond those already listed in above Properties Examples: * format constraints This is presented as a simple table with the field name and a description of the constraint *** #### 2.3 Sub-objects (optional) > Structured child data that forms part of the object. Domain models may contain sub objects. Whether to model an object as a sub-object or give it a domain model of its own is a design decision. As a rule of thumb if an object cannot stand on its own, without reference to its parent then it is a sub-object **Typicall sub-object section format** Sub object definition must include at least its properties and may include other sections such as relationships and even lifecylce, but only if these definitions cannot be meaningfully be described by the parent object. For most sub-object types a persisted prpoperties matrix is sufficient *** ### 3 Relationships > How this object connects to other objects. #### 3.1 Entity relationships **3.1.1 Outbound Relationships** > Relationships where **this object refereces another object** * Defined by fields on this object (typically foreign keys) * Represent what the object **depends on** * Part of the object’s stored structure * Typically required for the object to be valid **3..1.2 Inbound Relationships** > Relationships where **other objects references this object** * Not stored on this object * Discovered from other domain models * Represent what **depends on this object** * Often important for lifecycle, deletion, and “in use” rules * Often determine whether the object can be changed or removed #### 3.2 Association rules > Rules that govern **how relationships behave and may change**, within the bounds of the defined entity relationships. * Operate **within existing entity relationships** (do not define new relationships) * Define **when a relationship can be created, changed, or removed** * Often depend on: * lifecycle state * “in use” status * presence of dependent records * May restrict changes after certain points (e.g. after creation, after issue, after use) *** ### 4 Lifecycle > The valid states of the object and how it transitions between them. A domain entity's lifecycle defines the various possible states it moves through in its lifespan. The lifecycle is defined from "birth to death" - it starts from non-existence and ends with deletion. The concepts of lifecycle is differentiated from the concept of a workflow which defines a user-editable flow and may involve other domain objects. The concept of lifecycle pertains only to the domain entity itself and is generally not user configurable. #### 4.1 Lifecycle matrix The lifecycle matrix is a table that defines all possible state changes, with state transition operation names in the cells where the transition is valid. The From state is listed on the Y axis and the To state is listed on the X axis. In this way all possible state transitions are listed, however not all of these combinations will be valid. For example a state cannot transition to the same state, and business rules may prevent other state transitions. #### 4.2 Lifecycle diagram This is a mermaid diagram that illustrates the lifecycle matrix in a visual way. #### 4.3 Lifecycle operations and conditions Here the state transition operations shown in the lifecycle matrix are listed in table format, with the conditions required to enable the state transition described. #### 4.4 Lifecycle guidance A less structured section that defines what the various states mean, as well as containing other information and guidance *** ### 5 Object rules and constraints > Rules that apply to the object beyond those already defined in the sections above. * Not tied to a single property * Not purely relational * Must always hold Examples: * “invoice must have at least one line” * “invoice total must equal the sum of invoice lines” * "Journal postings are immutable" #### 5.1 Object rules and conditions A listing of all object rules and conditions ### 6 Implementation Section 6 contains implementation specific details. Whereas the previous 5 sections are reasonably implementation agnostic, defining the data domain only, section 6 describes details specific to the application's implementation of the DDM. #### 6.1 Database implementation Because database object(s), fields and constraints have already been described there is no need to go down to the SQL level. This section will generally only contain the database table name. If there are particular detalis specific to the database engine being used this is a good place to list these #### 6.2 UI Implementation This is not a full description of screens, as screen layout in general terms will have alrady been defined by the applicaiton architecture document. Rather this section calls out noteworthy UI functionality or constraints. #### 6.3 Architecture implementation List any noteworthy points from an arcchitecture point of view #### 6.4 General implementation This section can define any other implementation details worth calling out *** ## Example — AR Invoice (Simplified) Below is an example of this specification in use, to show a practical implementation of this specification. A common business object - an Accounts Receivable (AR) Invoice has been used. Note that this example is illustrative only - a real world AR Invoice specification would be more complex, including for example, invoice voiding, tax definitions, partial payment, over payment and so on. *** ### AR Invoice — Domain Data Model (DDM) *** ### 1 Definitions #### 1.1 List of Definitions “In use”. An invoice is in use if it has one or more payment allocations. *** ### 2 Properties #### 2.1 Properties Matrix | Column | Type | Required | Unique | Foreign Key | Constraints and Comments | | ------------- | ------- | -------- | ------ | ----------- | ----------------------------- | | id | bigint | yes | yes | — | Primary key | | code | text | yes | yes | — | Business key (invoice number) | | company\_id | bigint | yes | no | company.id | Owning company | | customer\_id | bigint | yes | no | customer.id | Customer | | invoice\_date | date | yes | no | — | Invoice date | | due\_date | date | yes | no | — | Due date | | status | enum | yes | no | — | DRAFT, ISSUED, PAID, DELETED | | total\_amount | decimal | yes | no | — | Total invoice amount | #### 2.2 Property constraints | Property | Constraint | | -------- | -------------------------- | | code | code must begin with "AR-" | *** #### 2.3 Sub-objects **2.3.1 Invoice Lines Attribute Matrix** | Column | Type | Required | Unique | Foreign Key | Constraints and Comments | | ------------ | ------- | -------- | ------ | -------------- | ------------------------------ | | line\_id | bigint | yes | yes | — | Primary key | | invoice\_id | bigint | yes | no | ar\_invoice.id | Owning invoice | | line\_number | integer | yes | no | — | Line order | | description | text | yes | no | — | Line description | | quantity | decimal | yes | no | — | Quantity | | unit\_price | decimal | yes | no | — | Unit price | | line\_amount | decimal | yes | no | — | Line total. Quantity \* amount | **2.3.2 Invoice Line Constraints** | Property | Constraint | | ----------- | ---------------- | | quantity | must be positive | | unit\_price | must be positive | *** ### 3 Relationships #### 3.1 Outbound Entity Relationships * Invoice belongs to one Company * Invoice references one Customer * Invoice references one Currency * Invoice has one or more Invoice Lines #### **3.2 Inbound Entity Relationships** * Journal postings reference Invoice * Payments / allocations reference Invoice #### 3.3 Association Rules * Company association cannot be changed after creation * Customer cannot be changed once ISSUED * Invoice must have at least one line before ISSUED * Lines belong to exactly one invoice *** ### 4 Lifecycle #### 4.1 Lifecycle matrix | From \ To | DRAFT | ISSUED | PAID | DELETED | | -------------- | -------------- | ------------- | -------------- | ------- | | (non-existent) | Create Invoice | — | — | — | | DRAFT | — | Issue Invoice | — | Delete | | ISSUED | — | — | Record Payment | Delete | | PAID | — | — | — | — | | DELETED | — | — | — | — | #### 4.2 Lifecycle diagram ```mermaid stateDiagram-v2 [*] --> DRAFT: Create Invoice DRAFT --> ISSUED: Issue Invoice ISSUED --> PAID: Record Payment DRAFT --> DELETED: Delete ISSUED --> DELETED: Delete ``` #### 4.3 Lifecycle operations | Operation | From State | To State | Conditions / Constraints | | -------------- | ------------------- | -------- | ------------------------ | | Create Invoice | non-existent | DRAFT | | | Issue Invoice | DRAFT | ISSUED | Must have ≥ 1 line | | Record Payment | ISSUED | PAID | | | Delete | DRAFT, ISSUED, PAID | DELETED | Only if not in use | #### 4.4 Lifecycle guidance State Definitions: * DRAFT = editable, not final * ISSUED = finalised * PAID = fully settled * DELETED = soft deleted *** ### 5 Object Rules and Guidance #### 5.1 Object Rules and Guidance * total\_amount must equal sum of line\_amounts * Invoice Due Date and Currency cannot be changed once Invoice is ISSUED * DELETED invoices are not visible and cannot be used ### 6 Implementation #### 6.1 Database implementation table\_name: ar\_invoice #### 6.2 UI Implementation * As the create invoice screen has some complexity use a page view rather than a modal pop up #### 6.2 Architecture Implementation Tenant Name: accounts Module Name: ar-invoice --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://voyzu.gitbook.io/docs/customising-and-extending-voyzu/domain-data-model-specification.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.