Live Sync Data Freshness
Technical architecture of the data freshness engine and sync status monitoring
The Live Sync Data Freshness engine tracks the latency and operational state of external integrations (such as Toast POS and 7shifts schedule synchronizations) to ensure managers make decisions based on fresh data.
Architecture Overview
External sync jobs (orchestrated by Dagster and data-sync packages) write high-watermark timestamps and status records to the sync_state table. The Freshness Engine (features/operations-health/data-freshness.ts) evaluates these timestamps against per-source SLAs via resolveSyncSla() to determine each source's freshness tone.
┌──────────────────────┐
│ Dagster / Sync Jobs │
└──────────┬───────────┘
│ writes sync_state
▼
┌──────────────────────┐
│ sync_state Record │
└──────────┬───────────┘
│ reads timestamps & health
▼
┌──────────────────────┐
│ Freshness Engine │
└──────────┬───────────┘
│ calculates SLA age & tone
▼
┌──────────────────────┐
│ DataFreshnessBanner │ (UI alert if stale/critical)
└──────────────────────┘Freshness Tones and SLA Evaluation
The engine categorizes sync status into one of four Freshness Tones:
| Tone | Description | Typical Threshold | UI Rail |
|---|---|---|---|
fresh | Data is recently synchronized and within SLA. | < Expected SLA | Green |
stale | Sync is delayed past normal SLA window. | > SLA, < Grace Limit | Amber |
critical | Sync has failed repeatedly or circuit breaker is open. | > Grace Limit | Crimson |
unknown | No sync record exists yet for the location. | N/A | Gray |
If the underlying sync source enters an open circuit-breaker state (3 consecutive failures), the engine sets the tone to critical with an alert message.
UI Component Integration
The DataFreshnessBanner is a React Server Component (RSC) rendered at the top of pages that rely on synchronized external data (e.g. Schedule Viewer, Line-Up Card, and Sales Goals).
Performance Optimization
- The banner's server read is isolated inside a Suspense boundary, so it does not block the surrounding app shell or page navigation.
- Updates are delivered client-side using non-blocking fetch intervals that query status indicators without full route revalidations.
- Includes human-readable age formats (e.g., "Synced 4m ago") and sync source indicators (e.g., "Toast API").