ADR 0003: Background Work and Domain Events Policy

Context

BooksPlus 3 will have work that benefits from background execution, including imports, report generation, document processing, backup or export work, close checks, notifications, and longer-running recalculations.

At the same time, accounting posting, reversal, close, reopen, waiver, protected setup changes, and similar consequential actions must remain deterministic, traceable, and easy to reason about.

Background work and events are useful, but careless use can hide business flow, weaken auditability, and create timing risks in accounting operations.

Decision

BooksPlus 3 will use background work and domain events conservatively.

The governing rules are:

Core accounting state transitions remain explicit and synchronous by default.
Background work may be used for clearly asynchronous work.
Domain events may signal meaningful completed business facts.
Event fan-out must not hide the primary accounting workflow.
Financially material posting logic must not depend on eventual consistency unless a later accepted decision explicitly allows and controls it.

Rationale

Accounting users and reviewers need to know what happened, when it happened, and whether a consequential action completed.

Explicit application flows make posting, close, reopen, waiver, reversal, and protected setup changes easier to test, audit, and explain.

Consequences

Positive consequences:

Accounting-critical behavior remains deterministic.
Background execution remains available for appropriate workloads.
Domain events can improve decoupling without becoming hidden business logic.

Negative consequences:

Some workflows will be more explicit and less automatic.
Developers must decide carefully what can be deferred.
Long-running work needs visible status, retry, and audit behavior.

Implementation guidance

Use application services or commands for posting, reversal, close, reopen, waiver, and protected setup changes.
Use background work for imports, document processing, report generation, backup/export work, notifications, and non-authoritative recalculations.
Name domain events as completed business facts, not vague technical hooks.
Preserve auditability, retry discipline, correlation identifiers, and visible status for background work.
Do not let Avalonia view models trigger hidden accounting side effects through event fan-out.

../../contracts/kernel.contract.md
../../accounting/posting-and-reversal.md
../../accounting/close.md
../../contracts/security/audit-event-contract.md