Skip to content

ADR 0007: Provider-Agnostic Import Boundaries

Context

BooksPlus will need to accept facts from external systems and files without letting those systems define BooksPlus accounting truth.

Older BooksPlus v2 architecture notes separated transport payloads, source-specific adapters, normalized import contracts, evidence linkage, audit outcomes, and Accounting posting. That separation remains useful for BooksPlus 3 even though the implementation toolset is different.

Decision

BooksPlus should use provider-agnostic import boundaries.

A source-specific transport payload must be mapped into a BooksPlus import contract before domain workflows, posting, close checks, reporting, or evidence linkage consume it.

The standard import envelope should preserve:

  • source system identity;
  • external event identity;
  • idempotency key;
  • source-world event time;
  • BooksPlus acceptance time;
  • optional external reference;
  • optional source-document reference;
  • explicit change type such as original, correction, or reversal.

BooksPlus should stamp acceptance time at the application boundary. External systems may supply source-world timestamps, but they should not be the authority for BooksPlus acceptance time.

Rules

  • Imports are workflow-oriented, not table CRUD.
  • Import contracts use BooksPlus business language, not provider-specific vocabulary.
  • Source identity and idempotency are required for machine or file intake that can affect accounting workflows.
  • A replay with the same source identity and idempotency key may be treated as idempotent only when the normalized meaning matches.
  • Conflicting reuse of an idempotency key must be rejected or held for review.
  • Corrections and reversals must be explicit; silent overwrite is not allowed.
  • Raw payload evidence may be retained when useful for audit, duplicate review, or troubleshooting.
  • Business evidence belongs to Source Documents.
  • Adapters may submit facts and requests, but they must not post ledger effects directly.
  • Any resulting accounting effect must go through the central Accounting posting path.

Initial Workflow Families

Initial provider-agnostic import families may include:

  • payable events;
  • receivable events;
  • cash events;
  • source-document submissions.

Additional workflow families should add their own contracts only after the related truth page or proposed ADR defines the business meaning.

Consequences

  • Source-specific adapters remain replaceable.
  • BooksPlus avoids leaking provider vocabulary into core accounting behavior.
  • Duplicate and correction handling can be tested centrally.
  • Posting remains protected by Accounting and period controls.
  • File intake and future machine interfaces can share the same normalization and processing path.