Toast Sync Pipeline
Technical architecture of the Toast POS sync pipeline, sales metrics, and schedule variance
The Toast Sync Pipeline ingests sales transactions, labor timecards, order discounts, and menu items from Toast POS into PostgreSQL staging tables and canonical analytics fact tables.
Architecture & Runtime (ADR-0081 & Dagster)
Orchestration is owned by Dagster assets (dagster/canvas_forge/), which execute partition-native extracts, transforms, and data-quality checks on scheduled cadences:
| Layer | Component | Responsibility |
|---|---|---|
| Adapter | @repo/toast/client | Toast API client, OAuth authentication, HTTP retries |
| Data Platform | dagster/ assets | Partition-native extraction into stg_toast_*, transformation to analytics.f_* marts |
| State Management | sync_state table | High-watermark timestamps, run duration, and circuit breaker state |
| Freshness & SLA | @repo/operations | Per-source SLA evaluation and dashboard data freshness indicator |
Authoritative Specification: For complete active writer assignments, database tables, and partition topologies, see
docs/architecture/sync-pipeline-architecture.md.
Circuit Breakers & Resilience
Sync operations are protected by database-backed circuit breakers defined in @repo/data-sync/circuit-breaker:
- Failure Threshold: Tripped after 3 consecutive failures.
- Cooldown Period: 5 minutes cooldown before attempting a half-open retry.
- Persistence: State is stored in the
sync_statetable per(source, locationId).
Pipeline Capabilities
1. Order & Sales Ingestion
- Extract: Ingests completed checks, line items, service charges, and payments.
- Classification: Classifies discounts, comps, and category allocations.
- Storage: Persists to
stg_toast_ordersand populatesanalytics.f_order_item_fact.
2. Labor & Timecard Synchronization
- Ingests employee time entries (shifts, breaks, clock-in/out timestamps).
- Resolves job codes to canonical internal roles (
@repo/schedules). - Feeds labor variance metrics comparing actual clock-in times against published rosters.
3. Data Quality & Freshness
- Dagster DQ assets assert schema invariants and referential completeness.
- Shift Console displays data freshness badges based on evaluated sync SLAs.