POA External Sync Workflow
Summary
External sync is where POA changes outside systems. It renders and dispatches commands for QuickBooks Online, Spectrum, SharePoint routing, and related provider effects only after POA state is eligible.
The concept page POA External Sync explains the primitive. This thread focuses on sync as a workflow boundary with preview, eligibility, dispatch, retry, diagnostics, and manual handling.
Reader Question
How does POA keep outbound provider side effects explicit, auditable, and repairable after document state has been accepted?
Surface Or Workflow
Operators see external sync through command previews, command diagnostics, enqueue/retry actions, manual-handled actions, Spectrum sync status, and history detail. Engineers enter through command catalog, eligibility, rendering, payloads, live executor, worker, QBO mapping, Spectrum sync services, and thin job entrypoints.
Lifecycle
Validated workflow state renders an external command or sync batch. Eligibility checks decide whether prerequisites are satisfied. A dispatcher claims commands, executes them through the appropriate provider boundary, records results, and updates case status. Failures become command diagnostics and repairable issues.
Spectrum sync follows the same architectural idea: a greenfield-owned service drives the batch workflow, the job remains a thin entrypoint, and operator state records whether synchronization finished, failed, or needs attention.
Child Threads
- POA Operator Repair: owns command failure repair and manual-handled paths.
- Integrations And Workflow: explains provider boundary discipline.
- External Command Outbox: explains the reusable side-effect pattern.
Implementation Boundaries
services/poa/commands owns command catalogs, eligibility, rendering, validation, worker execution, dependency checks, and QBO payloads. services/poa/jobs/command_dispatch.py and jobs/poa/dispatch_external_commands/run.py own repeatable dispatch. services/poa/jobs/spectrum_sync.py and jobs/poa/sync_to_spectrum/run.py own the Spectrum sync path.
Tradeoffs
Making external sync asynchronous and diagnostic-heavy can feel slower than calling providers inline from a repair action. The payoff is that provider state changes become observable, retryable, and separable from the operator's browser request.
Visual
The current visual is a graph neighborhood. The intended visual is a command timeline from accepted case state to preview, eligibility, enqueue, dispatch, provider result, diagnostics, retry, or manual handling.
Source Evidence
docs/engineering/concepts/poa-external-sync.mdservices/poa/commandsservices/poa/commands/qboservices/poa/jobs/command_dispatch.pyservices/poa/jobs/spectrum_sync.pyjobs/poa/dispatch_external_commands/run.pyjobs/poa/sync_to_spectrum/run.pytests/poa/test_poa_command_workflows.pytests/poa/test_poa_job_workflows.py