Skip to content

ADR 0004: Canonical Accounting Model Is Source of Truth

Context

BooksPlus 3 must embody a coherent accounting model rather than being shaped primarily by screens, persistence tables, imported file formats, framework convenience, or integration payloads.

Without a canonical accounting model, the product would drift toward whatever representation is easiest in the current implementation. That would weaken posting consistency, auditability, reporting, close behavior, and future integrations.

Decision

The canonical accounting model is the source of truth for BooksPlus 3.

Truth pages and contracts define BooksPlus accounting meaning. Avalonia views, view models, PostgreSQL tables, DTOs, APIs, imports, exports, and integrations must map to the canonical model rather than redefine it.

Rationale

BooksPlus needs stable accounting concepts that survive implementation details.

Canonical meaning lets the product preserve accounting truth while changing presentation, persistence, import, export, or integration mechanisms over time.

Consequences

Positive consequences:

  • Accounting behavior remains consistent across the product.
  • Mappings from external systems and files become explicit.
  • Reporting, auditability, and close behavior have a stable foundation.
  • UI and database convenience cannot silently redefine accounting meaning.

Negative consequences:

  • Implementation shortcuts may be rejected when they distort the model.
  • Mapping layers may require more work than direct persistence or UI binding.
  • Canonical concepts must be maintained carefully as the product grows.

Implementation guidance

  • Treat domain concepts and truth contracts as the governing source for accounting behavior.
  • Treat persistence models, view models, DTOs, APIs, import rows, and export rows as representations.
  • When an external source conflicts with BooksPlus meaning, create a mapping rather than changing the canonical model to match the source.
  • Keep reporting and close logic based on canonical accounting semantics.
  • Update truth pages and contracts before derived developer or user documentation redefines behavior.
  • ../../vision-and-product-principles.md
  • ../../contracts/kernel.contract.md
  • ../../accounting/journal-entries.md
  • ../../accounting/posting-and-reversal.md
  • ../../accounting/financial-periods.md