Convergence & reconciliation flow

Convergence drives a business toward its desired state across all systems, idempotently. It is event-in / sync-out: an external change (e.g. a Directus edit) nudges the workflow, which re-converges and syncs outward.

sequenceDiagram
    participant DI as Directus
    participant API as scheduler-api (webhook)
    participant T as Temporal (businessConvergence)
    participant Sys as WorkOS / Stripe / Vendure
    participant R as Redis (SSE bridge)
    participant Portal as portal

    DI->>API: webhook (shared secret)
    API->>T: nudge convergence (business.id)
    T->>T: resolve desired vs actual
    T->>Sys: converge-forward (idempotent)
    T->>R: publish progress
    R-->>Portal: SSE progress (stoken)

Layering: backfills write, the scanner reads

A frequent misconception is that the daily reconciliation scanner and the backfills are redundant. They are not — they are layered:

flowchart LR
    BF["Backfills<br/>(one-shot scripts)"] -->|WRITE + prune| MC[(Mirror caches)]
    SC["Daily scanner<br/>(reconciliation)"] -->|READ| MC
    SC -->|drift detected| T["Convergence workflow"]

Backfills write/prune the mirror caches; the scanner reads them to detect drift. Don’t retire the backfills. See docs/plans/2026-06-11-business-convergence-workflow.md.