Skip to content

ADR 0032: QBO-First Controlled Cutover

Context

BP3 already has provider-agnostic file intake, candidate identity and replay, workflow routing, staged chart import, opening-balance review, protected central posting, period controls, audit, PostgreSQL recovery, and company backup. Provider-specific automation should not duplicate those controls.

ADR 0020 places external adapters last and defers broad migration entries, operational receivable and payable detail, item and perpetual-inventory detail, and the fixed-asset lifecycle. The current release plan nevertheless groups Dolibarr REST delivery, direct IRIS transmission, provider mappings, and QuickBooks conversion into one final step. That bundle has several independent deployment and verification boundaries.

BooksPlus needs a deliberately bounded conversion path before it attempts live provider connectivity or promises historical reconstruction.

Decision

QuickBooks Online should be the first conversion source. The initial mode should be a controlled cutover into BooksPlus-supported accounting state, not a full historical conversion or recurring synchronization.

This decision applies only to the replacement scenario: a company is replacing an existing QBO accounting instance with BooksPlus. A startup scenario has no existing accounting system to replace and follows ordinary BooksPlus company setup. It does not create a CompanyConversionRun, connect to QBO, or satisfy QBO conversion evidence and reconciliation controls.

Both scenarios may use canonical chart, period, permission, and supported opening-balance services. Sharing those downstream owners does not turn startup setup into a conversion.

A conversion imports source facts through explicit, reviewable mappings; it does not silently recreate QuickBooks behavior inside BooksPlus.

Initial cutover boundary

The first QBO conversion should support:

  • explicit source-company selection and source accounting settings used for validation;
  • a versioned QBO profile and immutable or faithful source evidence;
  • staged, reviewable chart-of-accounts mapping and import;
  • one company-currency opening trial balance at an explicit cutover date;
  • control schedules and source evidence for receivables, payables, inventory, bank and credit-card balances, outstanding instruments, tax and payroll liabilities, retained earnings, and record counts when applicable; and
  • a durable reconciliation and approval result linking source facts, mappings, dispositions, and resulting BooksPlus records.

Control schedules support the cutover and opening balances. They do not create customer, vendor, item, receivable, payable, banking, payroll, fixed-asset, or perpetual-inventory subledgers that current canonical truth does not define. Detailed source objects may be retained for review or later conversion, but must remain non-posting until an accepted BooksPlus workflow contract owns their meaning.

The first cutover therefore excludes:

  • full-detail conversion of the current fiscal year or preceding years;
  • creation of general customer, vendor, item, class, location, project, job, fixed-asset, or operational transaction masters not already canonical;
  • foreign-currency conversion, remeasurement, or posting;
  • silent posting to closed periods or mutation of posted history; and
  • recurring or bidirectional QuickBooks synchronization.

A later read-only archive of QBO exports and reports may preserve historical reference without recreating every historical transaction in BooksPlus.

Existing BooksPlus ownership

QBO source payloads must feed the existing AccountingImportRun, AccountingImportIdentityDecision, AccountingImportIdentifiedCandidate, and AccountingImportAcceptedCandidateIdentity boundaries. Candidate identity, exact replay, conflict and duplicate review, workflow routing, Source Document evidence, chart maintenance, opening-balance setup, authorization, audit, period eligibility, and central posting remain owned by their existing BooksPlus services and contracts.

No adapter, profile, mapping, reconciliation result, or import candidate may post a journal entry directly. Approved accounting effects use the owning workflow and the protected central posting path. Mapping changes are versioned and must not rewrite a previously approved or posted result.

Before posting, the conversion control result must reconcile every applicable control: trial balance and equal debits and credits; balance sheet; receivable, payable, inventory, bank, and credit-card controls; included outstanding instruments; tax and payroll liabilities; retained earnings and prior-period income; counts and amounts by supported type; and every unmapped, rejected, duplicate, conflicting, transformed, or adjusted item. Every material difference requires an explicit disposition or the conversion remains blocked.

The conversion must preserve deterministic replay, idempotent resume and retry, duplicate-posting prevention, company isolation, source evidence, reviewed mapping versions, approval attribution, period controls, append-only audit, and recovery consistent with the canonical company backup boundary.

Company conversion aggregate

CompanyConversionRun is the separate company-scoped aggregate that controls one attempted transition into BooksPlus. It links one or more immutable AccountingImportRun records and coordinates existing chart, Source Document, opening-balance, authorization, period, audit, and posting services without absorbing or bypassing their ownership.

The initial controlled-cutover mode permits multiple durable review, failed, abandoned, superseded, or interrupted runs, but at most one run may be successfully applied for a BooksPlus company. An interrupted application resumes the same approved run and must not create duplicate chart or journal results. A required source or mapping change after approval creates a new run that explicitly supersedes the prior run.

The aggregate preserves source-company identity, conversion profile and mapping versions, cutover date and currency, linked import runs, control results and dispositions, approval identity and fingerprint, application attempts, resulting BooksPlus record identities, status history, and audit evidence. Applied runs and their approved inputs are immutable. Subsequent accounting changes use ordinary BooksPlus maintenance or correction workflows, not another application of the conversion.

The canonical Company Conversion Run Contract defines its lifecycle, authorization, replay, persistence, and backup expectations.

Adapter and deployment boundary

bp3-wiki owns product truth, contracts, security requirements, and the roadmap. bp3 owns the application, canonical ingestion, reconciliation, workflow, authorization, and posting behavior. The initial QBO profile and adapter should remain a bounded bp3 component when it shares the desktop deployment boundary; a broad interchange repository is not justified. bp3-doli retains Dolibarr provisioning, source-specific capture and mapping, outbox, delivery, and adapter-side evidence responsibilities; it is unchanged and is not a dependency of the QBO conversion path.

REST is not required between components in the same process. A versioned in-process application contract or integrity-protected transfer package may carry the same conceptual import boundary. REST is appropriate only at a real process or deployment boundary.

Live QBO connectivity follows fixture-based profile qualification and controlled-cutover proof. It must use explicit company selection, secure OAuth and token handling, restartable extraction, stable checkpoints, and the same BooksPlus import path. A desktop executable must not contain a permanent provider client secret. If authorization requires a hosted callback, a later decision should define only that narrow service and must not move accounting ownership out of bp3.

Deferred integrations and professional interchange

The BP3 initial release should defer automated Dolibarr REST delivery and its production payload mappings. This does not change the separately deployable Dolibarr operational package or make its provider vocabulary canonical.

Direct IRIS A2A transmission remains deferred under ADR 0025; the reviewed IRIS Taxpayer Portal handoff remains the initial transport. A2A provider payload mapping is therefore not Step 14 launch work.

QuickBooks Desktop, direct reading of proprietary QuickBooks company or backup files, tax-product adapters, full-history conversion, and recurring QuickBooks synchronization remain deferred. Any later Desktop adapter should use the supported Intuit Desktop SDK/qbXML boundary rather than read proprietary files.

Professional workpaper packages, least-privilege read-only professional access, and proposed adjustment batches remain separate later workstreams. They are not QBO adapter responsibilities or prerequisites for controlled cutover. Support access remains separately and explicitly deferred; professional access must not be implemented by repurposing support access.

Acceptance record

Accepted on 2026-08-01 with CompanyConversionRun as a separate company-scoped aggregate rather than an extension of AccountingImportRun. The aggregate is one-time at successful application, not one-record-only: review, failed, abandoned, superseded, interrupted, and recovery attempts remain durable and explainable. ADR 0020 is amended to distinguish this bounded controlled cutover from still-deferred broad migration-entry workflows.

Consequences

  • Startup-scenario companies can begin through ordinary Setup & Onboarding without QBO, a source import, or a conversion aggregate.
  • QBO conversion can begin without waiting for Dolibarr or IRIS automation.
  • The first release gains a bounded cutover path without promising operational subledgers or historical reconstruction it does not own.
  • Provider compatibility remains replaceable and outside canonical accounting meaning.
  • Live OAuth and any hosted callback remain independently reviewable later deployment work.
  • Professional interchange remains visible without expanding the conversion adapter into an access, workpaper, or adjustment product.
  • ../accepted/0007-provider-agnostic-import-boundaries.md
  • ../accepted/0020-initial-release-scope-and-financial-workflow-taxonomy.md
  • ../accepted/0022-reviewable-accounting-file-intake.md
  • ../accepted/0025-contractor-classification-and-information-return-filing.md
  • ../accepted/0026-initial-release-single-currency-boundary.md
  • ../../contracts/accounting-import-run.contract.md
  • ../../contracts/accounting-import-candidate.contract.md
  • ../../contracts/company-conversion-run.contract.md
  • ../../contracts/chart-import.contract.md
  • ../../contracts/journal-entry.contract.md
  • ../../contracts/financial-period.contract.md
  • ../../contracts/source-document.contract.md
  • ../../contracts/security/audit-event-contract.md
  • ../../contracts/security/company-backup-snapshot.contract.md
  • ../accepted/0016-support-access-is-temporary-and-logged.md