QuickBooks Online Provider Boundary

Summary

QuickBooks Online is a useful provider-boundary example because the same external system can be both a source of accounting facts and a destination for sync work. The reusable lesson is target context: integration code must know which company, realm, and environment it is reading or writing before any workflow treats the result as operational truth.

Reader Question

How should a platform integrate with an accounting provider when reads, writes, sandbox targets, production targets, and company-specific context all share the same provider API shape?

Boundary Pattern

The provider edge owns authentication, realm/company context, API shape, retry behavior, and provider-specific errors. Ingestion code can read provider facts into the lakehouse. Sync services can prepare outbound accounting actions, but they should carry explicit target context and durable operation state before calling the provider.

The important design rule is to fail closed when target context is ambiguous. A job should not infer a realm, environment, or company implicitly from a global configuration value. That context belongs in the operation contract, audit record, or sync target record.

Reusable Lessons

  • Treat provider target context as data, not ambient configuration.
  • Separate provider reads from provider writes even when they use the same API.
  • Use durable sync links and operation records to make retries idempotent.
  • Normalize accounting facts inward before exposing them to UI or workflow services.
  • Keep provider errors at the edge, then convert actionable ambiguity into reviewable state.

Source Evidence

  • integrations/ext_quickbooks_online
  • pipelines/lakehouse/ingest/quickbooks_online
  • services/data_sync/jobs/quickbooks_online
  • docs/domains/data_sync.md