# daily-review-sync

**Trigger:** scheduled tick from the swarm runtime.
**Cadence:** every 10 minutes for active paid locations. Every 60 minutes for trial locations. Every 24 hours for paused / churned locations whose history we still hold (to support reactivation without a backfill).
**Agents (in order):** queen-coordinator -> review-aggregator (per platform, parallel up to 4).
**Output:** new rows in the `reviews` table. Each new review emits a downstream event picked up by the escalation-cycle workflow.
**SLA:** 10 minutes from a review posting publicly on a platform to it landing in D1.

## How it runs

1. Queen-coordinator gets the tick. It enumerates locations due for sync (last sync timestamp + cadence). It batches by brand so review-aggregator instances share a brand-style cache.
2. For each location, queen routes to review-aggregator with the location id + platform list. Review-aggregator fans out per platform (Google, Yelp, Tripadvisor, Facebook) up to a max of 4 in parallel to respect per-platform rate limits.
3. Each platform call uses the cursor saved from the prior sync (Google: `pageToken`; Yelp: `offset`; Facebook: `since`; Tripadvisor: `last_updated_after`).
4. Review-aggregator scrubs PII and writes rows. Duplicate detection is by composite key `(platform, platform_review_id)`.
5. Each new row triggers an `escalation-cycle` event in the queue.

## Failure modes

- **Platform 429 (rate limit):** back off exponentially per the platform's `Retry-After`, max 4 retries. After 4, surface a "platform sync paused for N minutes" status on the location's settings page.
- **Platform 401 (token expired):** mark the location's platform as `needs_reconnect`, fire a sendgrid alert to the GM/owner, skip that platform until reconnected.
- **Empty page:** advance the cursor, no error.
- **Malformed payload:** log to D1's `agent_errors` table; do not advance the cursor; alert the on-call engineer (just Brian for now) via SendGrid.

## Why 10 minutes

Most platforms cache for 30 to 90 seconds before propagating. Polling more aggressively just burns API budget without changing the operator experience. Brian named 10 minutes as the brand promise on the hero page; that drives this cadence.

## Cost

Haiku 4.5 at the typical token volume for a sync tick is sub-cent per location per day. At 1,000 locations the daily review-sync compute is under $10 / month.