Finance And AR Surfaces

Summary

Finance and accounts receivable coverage in the platform is currently centered on operational sync, invoice candidates, accounting context, duplicate diagnostics, and QBO/Spectrum/ServiceTitan boundaries. It is less UI-heavy than POA or Precon, but it still has workflow shape: source accounting facts are loaded, mapped, synchronized, diagnosed, and repaired through explicit jobs and runbooks.

Module At A Glance

Primary surface: finance and AR sync diagnostics, runbooks, lakehouse repositories, accounting jobs, and future AR review surfaces.
Main state machine: Finance And AR State Machine.
Key workflow: Finance Accounting Sync Workflow.
Provider boundaries: QuickBooks Online Provider Boundary and Spectrum Provider Boundary.

Reader Question

How does finance data move across ServiceTitan, Spectrum, QuickBooks Online, and internal serving models without letting provider semantics leak into every workflow?

Surface Or Workflow

The current surface is mostly operational: data-sync jobs, diagnostics, runbooks, lakehouse repositories, and tests. The existing Accounts Receivable Surface concept is the reader entry point for AR-oriented product questions.

Architecture Rationale

Finance sync should not own business truth. Internal services decide whether state is reconciled and actionable; integrations adapt provider semantics; the workflow exposes mismatches and exceptions before accounting side effects.

Lifecycle

Accounting evidence is loaded from ServiceTitan, Spectrum, and QuickBooks Online through integration and lakehouse seams. Sync services map invoices, payments, accounting elements, vendors, customers, and locations into internal contracts. Jobs run the repeatable synchronization paths. Diagnostics and runbooks handle duplicate or mismatched accounting state.

Child Threads

Finance Accounting Sync Workflow: Spectrum, ServiceTitan, QBO, invoice candidates, and accounting sync jobs.
Finance And AR State Machine: the system-level lifecycle from source refresh through reconciliation, review, command eligibility, sync, exception, and audit.
Accounts Receivable Surface: the current AR surface orientation.
QuickBooks Online Integration: QBO provider boundary.
Spectrum Integration: Spectrum provider boundary.

Implementation Boundaries

Accounting sync behavior lives under services/data_sync/jobs/sync_accounting and services/data_sync/jobs/quickbooks_online; thin entrypoints live under jobs/data_sync; lakehouse repositories live under services/lkci_lakehouse/repos; provider models live under services/lkci_lakehouse/models/sources; tests live under tests/jobs, tests/data_sync, tests/integrations, and tests/pipelines.

Tradeoffs

Finance workflows currently have more backend operational surface than UI surface. The site should document that honestly: the important architecture is the sync boundary, mapping discipline, diagnostics, and provider isolation, while future UI can attach to those primitives.

Visual

The current visual is a graph neighborhood. The intended visual is an accounting sync lineage map from providers to lakehouse repositories, sync services, jobs, diagnostics, and future AR-facing views.

Source Evidence

docs/engineering/concepts/accounts-receivable-surface.md
docs/runbooks/data-sync-spectrum-accounting-duplicates.md
services/data_sync/jobs/sync_accounting
services/data_sync/jobs/quickbooks_online
jobs/data_sync/spectrum/sync_accounting/run.py
jobs/data_sync/qbo/sync_accounting_qbo/run.py
jobs/data_sync/spectrum/accounting_duplicate_diagnostic/run.py
services/lkci_lakehouse/repos/servicetitan/sync/accounting_repo
services/lkci_lakehouse/repos/quickbooks_online/sync/accounting_repo.py
tests/jobs/test_sync_accounting_qbo_service.py
tests/data_sync/test_st_accounting_invoice_candidates.py