Skip to content

Source truth: - Vision - Kernel Contract

Architecture Overview

This page summarizes the key architectural goals for BooksPlus 3.

  • Support durable accounting records.
  • Separate canonical truth from derived documentation.
  • Preserve auditability and period controls.
  • Keep domain behavior independent of Avalonia views, view models, persistence models, and platform services.
  • Use a distributed kernel: canonical behavior belongs to the domain area that owns the business meaning, not to a catch-all core package.
  • Route all ledger effects through the accounting posting path.
  • Route posting-date eligibility through financial period control.
  • Treat close, reopen, waiver, reversal, posting, evidence changes, protected security actions, backup restore, and sensitive exports as consequential actions that require authorization and audit evidence.

Layers

BooksPlus 3 should keep these responsibilities separate:

Layer Responsibility
Domain Accounting meaning, invariants, value objects, policies, and state transitions
Application Commands, queries, workflows, transactions, and coordination between domain areas
Infrastructure Persistence, files, encryption, backup, operating-system integration, and external adapters
Presentation Avalonia views, view models, navigation, validation display, and user interaction

Domain rules should not depend on Avalonia, storage details, or platform services. Presentation code should ask application services to perform work rather than mutating accounting state directly.

Kernel ownership

Kernel behavior is distributed across domain areas:

  • Financial periods own period identity, boundaries, hierarchy, and status.
  • Close owns close runs, close checks, waivers, approvals, and reopen workflows.
  • Accounting owns journal entries, ledger truth, posting, reversal, and posting policy enforcement.
  • Source documents own evidence identity, references, and supersession.
  • Security owns protected actions, authorization, and step-up confirmation.
  • Audit owns append-only evidence of consequential actions.
  • Shared primitives stay narrow and contain only concepts that are genuinely cross-domain.

Namespace boundaries

BooksPlus 3 uses namespace boundaries, not separate .NET projects, for the current architecture. Keep domain areas visible through names such as BooksPlus.Domain.Accounting, BooksPlus.Domain.FinancialPeriods, BooksPlus.Domain.Closing, BooksPlus.Domain.SourceDocuments, BooksPlus.Domain.Reporting, BooksPlus.Domain.Security, BooksPlus.Domain.Audit, and BooksPlus.Domain.Shared.

Use Namespace Boundaries when placing new code.