Finance Accounting Sync Workflow
Summary
Finance accounting sync is the repeatable backend workflow that moves accounting data across provider systems and internal models. It handles invoice candidates, accounting elements, payments, vendors, customers, locations, diagnostics, and duplicate detection.
Reader Question
How does accounting sync stay repeatable and diagnosable across Spectrum, ServiceTitan, and QuickBooks Online?
Surface Or Workflow
Engineers enter through data-sync jobs and diagnostics. Operators or support users currently enter through runbooks and job evidence rather than a dedicated finance UI.
Lifecycle
The workflow loads provider context, maps accounting records into internal contracts, executes sync phases, tracks element history, records diagnostics, and exposes duplicate or mismatched state through runbooks and tests. QBO sync has its own accounting service and job entrypoint, while Spectrum sync owns the CSV and mapping paths needed for its side of the workflow.
Child Threads
- Finance And AR Surfaces: first-level finance orientation.
- Integration Provider Boundaries: provider isolation pattern.
- Data Product Boundaries: lakehouse and serving responsibilities.
Implementation Boundaries
Service behavior lives under services/data_sync/jobs/sync_accounting and services/data_sync/jobs/quickbooks_online/accounting. Entry points live under jobs/data_sync/spectrum and jobs/data_sync/qbo. Shared accounting contracts live under libs/data_sync. Tests under tests/jobs and tests/data_sync cover phase behavior, QBO service behavior, CSV maps, and invoice candidates.
Tradeoffs
The accounting workflow is intentionally backend-first. That keeps provider mapping and duplicate diagnostics explicit before a broader finance UI grows on top of it.
Visual
The current visual is a graph neighborhood. The intended visual is a sync phase timeline with provider load, mapping, execution, element history, diagnostics, and duplicate runbook handoff.
Source Evidence
services/data_sync/jobs/sync_accountingservices/data_sync/jobs/quickbooks_online/accountingjobs/data_sync/spectrum/sync_accounting/run.pyjobs/data_sync/qbo/sync_accounting_qbo/run.pyjobs/data_sync/spectrum/accounting_duplicate_diagnostic/run.pylibs/data_sync/accountinglibs/data_sync/adapters/accounting.pydocs/runbooks/data-sync-spectrum-accounting-duplicates.mdtests/jobs/test_sync_accounting_contracts.pytests/jobs/test_sync_accounting_qbo_service.py