> 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/r-and-d/domain-knowledge-objects.md).

# Domain Knowledge Objects

## NOT IN USE

In the end this "One specification to rule them all" idea became too unwieldy. This idea morphed into Domain Data Models (DDM). Still, there are some interesting ideas here so retaining

***

## Concept

A Domain Knowledge Object (DKO) is a structured description of a particular domain. It is not an object in the software sense, rather it is a bounded context that represents something that exists in reality. DKOs are useful for producing documentation and informing coding decisions.

## Structure

DKOs are markdown documents and always follow the same high level structure. The document is broken into seven secitons, with each section answering a question, as follows:

* What is it?
* What characteristics does it have?
* What constraints is it subject to?
* What can it do?
* What can you do with it?
* How does it relate to other objects?
* How does it evolve?

An example that further explains these questions is below. Note that answers here are not comprehensive - they serve to explain the concept - a real world DKO would be far more comprehensive.

| Section                    | Question                             | Snail                                                                     | AR Invoice                                                                            |
| -------------------------- | ------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Definition and purpose** | What is it?                          | <p>• A gastropod mollusc<br>• Soft-bodied animal usually with a shell</p> | <p>• A document requesting payment from a customer<br>• Represents an amount owed</p> |
| **Properties**             | What characteristics does it have?   | <p>• Coiled shell<br>• Tentacles and muscular foot</p>                    | <p>• Invoice number, dates, currency<br>• Line items and totals</p>                   |
| **Constraints**            | What constraints is it subject to?   | <p>• Requires moisture<br>• Limited speed/mobility</p>                    | <p>• Must have at least one line<br>• Totals must balance</p>                         |
| **Capabilities**           | What can it do?                      | <p>• Move using mucus<br>• Retract into shell for protection</p>          | <p>• Calculate totals and tax<br>• Represent a receivable</p>                         |
| **Operations**             | What can you do with it?             | <p>• Observe or study it<br>• Eat it (e.g. escargot)</p>                  | <p>• Issue it to request payment<br>• Record payments against it</p>                  |
| **Relationships**          | How does it relate to other objects? | <p>• Eats plants/algae<br>• Prey for birds and mammals</p>                | <p>• Issued to a customer<br>• Contains invoice lines</p>                             |
| **Lifecycle**              | How does it evolve?                  | <p>• Egg → juvenile → adult<br>• Species evolve over generations</p>      | <p>• Draft → Issued → Paid<br>• Can be cancelled</p>                                  |

## Sections

Each section should be comprehensive and detailed. Below is guidance on the structure and format of each section. An Accounts Receivable Invoice has been used for the examples. This object has been simplified for the sake of brevity.

### **Definition and purpose**

An **Accounts Receivable (AR) Invoice** is a document within the system used to request payment from a customer for goods or services that have been supplied. It records the details of what is being billed, including the customer, invoice date, line items, applicable taxes, and the total amount due. The invoice represents the system’s record of a specific amount owed by a customer.

Within the system, the invoice acts as the central record for managing customer receivables. Once created and issued, it establishes the customer’s outstanding balance and can be used to track payments applied against it. The invoice also supports the system’s financial processes by contributing to receivables reporting and, where applicable, generating accounting entries that recognise revenue and record the amount owed by the customer.

### **Properties**

| field name      | type    | required | unique | constraints                            | notes                      |
| --------------- | ------- | -------- | ------ | -------------------------------------- | -------------------------- |
| id              | bigint  | yes      | yes    | Primary key                            | System identifier          |
| invoice\_number | text    | yes      | yes    | Must be unique per company             | Human-readable reference   |
| customer\_id    | bigint  | yes      | no     | Must reference customer                | Customer being billed      |
| invoice\_date   | date    | yes      | no     | Cannot be in the future (typical rule) | Date invoice is issued     |
| total\_amount   | numeric | yes      | no     | Must equal sum of line totals + tax    | Stored total for reporting |
| status          | enum    | yes      | no     | `DRAFT`, `ISSUED`, `PAID`, `CANCELLED` | Lifecycle state            |

**Derived Values**

| field name          | type    | derived by                             |
| ------------------- | ------- | -------------------------------------- |
| amount\_paid        | numeric | Sum of payments applied to the invoice |
| amount\_outstanding | numeric | `total_amount − amount_paid`           |

### **Constraints**

| constraint name                     | type            | applies to                     | description                                                               |
| ----------------------------------- | --------------- | ------------------------------ | ------------------------------------------------------------------------- |
| Primary Key – Invoice ID            | key             | `id`                           | Each invoice must have a unique system identifier.                        |
| Unique Invoice Number per Company   | uniqueness      | `invoice_number`, `company_id` | Invoice number must be unique within the issuing company.                 |
| Valid Company Reference             | foreign key     | `company_id`                   | Invoice must belong to an existing company in the system.                 |
| Valid Customer Reference            | foreign key     | `customer_id`                  | Customer must reference an existing customer record.                      |
| Invoice Must Have At Least One Line | business rule   | invoice                        | An invoice cannot be issued unless it contains at least one invoice line. |
| Invoice Total Must Match Lines      | business rule   | `total_amount`                 | Stored total must equal the sum of line totals and tax.                   |
| Status Must Be Valid                | enum constraint | `status`                       | Status must be one of `DRAFT`, `ISSUED`, `PAID`, `CANCELLED`.             |

### **Capabilities**

| capability name              | description                                                                                                          | notes                                                                                                                                                                                                                |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Display Invoice Totals       | Calculates and displays the total amount payable by summing invoice line amounts and applicable taxes.               | Recalculated whenever invoice lines or tax codes change.                                                                                                                                                             |
| Represent Customer Liability | Represents an amount owed by a customer within the system’s receivables.                                             | Used as the system record of the customer’s obligation to pay.                                                                                                                                                       |
| Track Payment Status         | Reflects whether the invoice is unpaid, partially paid, or fully paid based on payments applied.                     | Status may update automatically as payments are recorded.                                                                                                                                                            |
| Display Receivable Balance   | Contributes to the calculation and display of the customer’s outstanding receivable balance within the system.       | Used in receivables summaries and ageing views.                                                                                                                                                                      |
| Accounting Integration       | Integrates with the system’s accounting module to create the financial postings associated with issuing the invoice. | When an invoice is issued, the system records a debit to the customer’s accounts receivable control account and credits the appropriate revenue and tax liability accounts based on the invoice lines and tax codes. |

### **Operations**

| operation name              | description                                                                                      | notes                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| Create Invoice              | Create a new invoice record for a customer with basic details such as invoice date and currency. | Initial status is typically `DRAFT`.                                         |
| Edit Invoice                | Modify invoice details or line items while the invoice is in draft.                              | Editing is restricted once the invoice is issued.                            |
| Add or Remove Invoice Lines | Add, update, or remove line items that describe the goods or services being billed.              | Changes trigger recalculation of totals.                                     |
| Issue Invoice               | Finalise the invoice and make it an official request for payment.                                | Changes status from `DRAFT` to `ISSUED` and triggers accounting integration. |
| Record Payment              | Apply a payment to the invoice to reduce the outstanding balance.                                | May update invoice status to `PARTIALLY PAID` or `PAID`.                     |
| Cancel Invoice              | Void an invoice that should no longer be payable.                                                | Typically allowed only before the invoice has been fully settled.            |

### **Relationships**

| relationship name         | related object    | relationship type | description                                                                                | notes                                                 |
| ------------------------- | ----------------- | ----------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| Issued To Customer        | `customer`        | reference         | The customer who is responsible for paying the invoice.                                    | Referenced by `customer_id`.                          |
| Belongs To Company        | `company`         | reference         | The company issuing the invoice.                                                           | Referenced by `company_id`.                           |
| Contains Invoice Lines    | `ar_invoice_line` | composition       | The invoice is composed of one or more line items describing the goods or services billed. | Lines exist only as part of an invoice.               |
| References Tax Codes      | `tax_code`        | reference         | Invoice lines reference tax codes used to calculate applicable tax.                        | Used in tax calculation and accounting posting.       |
| Linked To Payments        | `payment`         | association       | Payments may be applied to the invoice to reduce the outstanding balance.                  | Multiple payments may be applied to a single invoice. |
| Generates Journal Entries | `journal_entry`   | association       | Issuing the invoice results in accounting postings recorded as journal entries.            | Created through accounting integration.               |

### **Lifecycle**

| From \ To           | DRAFT | ISSUED        | PARTIALLY\_PAID | PAID           | CANCELLED      |
| ------------------- | ----- | ------------- | --------------- | -------------- | -------------- |
| **DRAFT**           | —     | Issue Invoice | —               | —              | Cancel Invoice |
| **ISSUED**          | —     | —             | Record Payment  | Record Payment | Cancel Invoice |
| **PARTIALLY\_PAID** | —     | —             | —               | Record Payment | —              |
| **PAID**            | —     | —             | —               | —              | —              |
| **CANCELLED**       | —     | —             | —               | —              | —              |

```mermaid

 stateDiagram-v2

    [*] --> DRAFT : Create Invoice

    DRAFT --> ISSUED : Issue Invoice
    DRAFT --> CANCELLED : Cancel Invoice

    ISSUED --> PARTIALLY_PAID : Record Payment
    ISSUED --> PAID : Record Payment
    ISSUED --> CANCELLED : Cancel Invoice

    PARTIALLY_PAID --> PAID : Record Payment
```

## Sub Domain Knowledge Objects

Some DKOs will have sub objects. For example a Journal will consist of a Journal header and one or more Journal Lines. These sub objects should also be documented, using the same format as the top level object, i.e. the above sections. Naturally some sections may not be fully applicable for a sub object. For example whereas a Journal has a Lifecycle, Journal Lines could not be said to have a Lifecycle of their own.


---

# 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/r-and-d/domain-knowledge-objects.md?ask=<question>&goal=<endgoal>
```

`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.