Skip to content

Source truth: - Kernel Contract - Financial Period Contract - Posting and Reversal - Close - Source Documents - Security Protected Action Contract - Audit Event Contract

Namespace Boundaries

BooksPlus 3 uses namespace boundaries, not separate .NET projects, for the current architecture. A later project split would require an explicit architecture decision.

The initial structure should keep business meaning visible through C# namespaces while preserving the current solution shape.

Rule

Use namespaces to express domain ownership:

  • domain behavior lives under BooksPlus.Domain.<Area>;
  • application workflows and queries should use BooksPlus.Application.<Area> when an application layer is added;
  • infrastructure adapters should use BooksPlus.Infrastructure.<Area> when infrastructure is separated;
  • Avalonia presentation code should stay in BooksPlus.App and call application services rather than mutating domain state directly.

Do not create a catch-all Kernel namespace. Kernel behavior is distributed to the area that owns the business meaning.

Initial Namespace Map

Area Initial namespace Owns
Accounting BooksPlus.Domain.Accounting accounts, journal entries, posting, reversal, ledger truth, posting policy
Financial periods BooksPlus.Domain.FinancialPeriods fiscal calendar profiles, fiscal years, fiscal quarters, fiscal months, period lookup, period status
Closing BooksPlus.Domain.Closing close runs, close checks, waivers, approvals, close finalization, reopen workflows
Source documents BooksPlus.Domain.SourceDocuments source-document identity, evidence references, document links, supersession
Reporting BooksPlus.Domain.Reporting report definitions, report runs, report snapshots, statement query contracts
Security BooksPlus.Domain.Security actors, roles, permissions, protected actions, step-up confirmation
Audit BooksPlus.Domain.Audit append-only audit events, audit artifacts, verification records
Shared primitives BooksPlus.Domain.Shared money, date ranges, identifiers, small result contracts

Financial Period Shape

Financial-period code must follow the period-driven fiscal calendar rule.

For generated standard calendars:

  • fiscal months are generated first;
  • fiscal quarters are derived from groups of fiscal months;
  • fiscal months and fiscal quarters are direct children of the fiscal year;
  • months are not nested under quarters.

Code and documentation ported from older BooksPlus versions must be corrected when it assumes a year -> quarter -> month hierarchy.

Cross-Boundary Rules

  • Posting-capable workflows prepare posting requests; Accounting decides whether they post.
  • Close coordinates period review, approval, waivers, and finalization; it does not write ledger effects directly.
  • Source Documents owns file identity, evidence references, and supersession; Accounting and Close consume evidence facts.
  • Audit records consequential facts through explicit services or contracts; Audit is not a hidden workflow bus.
  • Security authorization uses business actions, not generic CRUD permission names.
  • Shared primitives must stay narrow and must not collect workflow logic.

Application Layer Guidance

When a workflow crosses domain areas, create an application command, query, or service instead of making one domain object reach into another area's repository.

Examples:

  • BooksPlus.Application.Accounting.PostJournalEntryCommand
  • BooksPlus.Application.FinancialPeriods.GenerateFiscalCalendarCommand
  • BooksPlus.Application.Closing.RunCloseChecksCommand
  • BooksPlus.Application.SourceDocuments.LinkSourceDocumentCommand
  • BooksPlus.Application.Reporting.CaptureReportRunCommand

These names are guidance, not a required class list.

Infrastructure Guidance

Persistence models, SQL repositories, file storage, mailbox adapters, and external-source adapters are infrastructure details. They should map to canonical domain/application contracts and should not define business meaning.

What To Avoid

  • separate .NET projects for current domain areas without an explicit architecture decision;
  • BooksPlus.Domain.Kernel or BooksPlus.Domain.Core as a dumping ground;
  • direct ledger writes outside Accounting;
  • direct period-state mutation outside period/close workflows;
  • direct source-file storage rules inside Accounting or Closing;
  • controller or view-model authorization checks that bypass protected-action policy.