Rosie runs as one Worker,
three Durable Object namespaces,
and zero cron jobs.

flowchart TD
  GUEST["Guest / owner phone
WhatsApp"]
  BROWSER["Owner browser
React SPA"]

  subgraph PROV["PROVIDERS"]
    BIRD["Bird Channels API
WhatsApp + SMS"]
    TG["Telegram Bot API"]
    RESEND["Resend
mail + inbound"]
  end

  subgraph WK["CLOUDFLARE WORKER — rosie"]
    ROUTER["fetch handler · Sentry-wrapped
Effect at the boundary
one wide event per request"]
    AUTHN["better-auth
/api/auth/*"]
    APIR["API route groups
connections · group · reviews"]
    INGRESS["/api/messengers/*
webhook ingress controller"]
    EPS["WorkerEntrypoints ×4
ReviewFetcher · ReplyDrafter
NewReviewNotifier
ReviewReplyPublisher"]
    ASSETS["ASSETS
SPA fallback"]
  end

  subgraph DOS["DURABLE OBJECTS"]
    RGDO["RestaurantGroupDO
idFromName is the groupId
auth-less · SQLite · alarm scheduler"]
    AGENT["RosieAgent : Think
per-org host
per-guest facet sessions"]
  end

  subgraph ST["STORES"]
    HD["Hyperdrive"]
    PG[("PlanetScale Postgres
identity · auth · connections")]
    KV[("RATE_LIMIT_KV
rate limits + OAuth tokens")]
  end

  subgraph MDL["MODELS"]
    AIGW["AI Gateway
custom-together"]
    TOG["Together
Kimi K2.6"]
    CBR["Cerebras
front-ack"]
  end

  GBP["Google Business Profile
reviews + replies"]

  GUEST --> BIRD
  BROWSER --> ROUTER
  BIRD -->|signed webhook| INGRESS
  TG --> INGRESS
  RESEND --> INGRESS

  ROUTER --> AUTHN
  ROUTER --> APIR
  ROUTER --> INGRESS
  ROUTER --> ASSETS

  INGRESS -->|phone lookup| HD
  INGRESS -->|route to org agent| AGENT
  APIR -->|RPC| RGDO
  APIR -->|publish reply| EPS
  AUTHN --> HD
  AUTHN --> KV
  HD --> PG

  AGENT --> AIGW
  AGENT -->|workspace snapshot| RGDO
  AGENT -->|connections read| HD
  AGENT -->|reply bubbles| BIRD
  AGENT -.->|instant ack| CBR
  AIGW --> TOG

  RGDO ==>|alarm fires callback| EPS
  EPS -->|token from KV| GBP
  EPS -->|draft reply| AIGW
  EPS -->|new-review ping| BIRD

  classDef ingressC fill:#b4530933,stroke:#b45309,stroke-width:2px
  classDef workerC  fill:#0369a133,stroke:#0369a1,stroke-width:2px
  classDef doC      fill:#0f766e33,stroke:#0f766e,stroke-width:2px
  classDef storeC   fill:#04785733,stroke:#047857,stroke-width:2px
  classDef extC     fill:#9f123933,stroke:#9f1239,stroke-width:2px
  classDef modelC   fill:#a1620733,stroke:#a16207,stroke-width:2px
  classDef clientC  fill:#5b718922,stroke:#5b7189,stroke-width:1.5px

  class GUEST,BROWSER clientC
  class BIRD,TG,RESEND,GBP extC
  class ROUTER,AUTHN,APIR,EPS,ASSETS workerC
  class INGRESS ingressC
  class RGDO,AGENT doC
  class HD,PG,KV storeC
  class AIGW,TOG,CBR modelC
    

sequenceDiagram
  autonumber
  participant G as Guest phone
  participant B as Bird
  participant W as Worker ingress
  participant P as Postgres via Hyperdrive
  participant H as RosieAgent host DO
  participant F as Guest facet DO
  participant M as Together via AI Gateway

  G->>B: WhatsApp message
  B->>W: POST /api/messengers/whatsapp/webhook
  W->>W: Verify Bird HMAC signature, else 401
  W->>W: Classify event, ignore anything but inbound text
  W->>P: Look up verified sender by phone, 2s timeout, 2 retries
  P-->>W: orgId and groupStatus

  alt Unknown sender
    W->>B: Signup link button, text fallback, never routed
  else Group still setting up
    W-->>B: 200 ack, deliberately no reply
  else Matched sender
    W->>H: agent.fetch with received-at and match headers
    H->>H: Adapter re-verifies the same signature
    H->>B: Front-ack bubble via Cerebras, awaited before the 200
    H->>H: chat.processMessage, turn is fire and forget
    Note over H,F: SDK resolves the per-guest facet downstream
    F->>M: Model turn with 30s-cached workspace snapshot
    M-->>F: Reply text
    F->>B: Delivered as up to 4 split bubbles
    B->>G: Delivered
  end
    

flowchart TD
  ALARM["alarm() fires"] --> PICK["Oldest job by createdAt where status is
pending or running — due check done in JS,
not SQL, to dodge timestamp quirks"]
  PICK -->|none due| WAIT["Return early — the finally block
still re-arms for pacing/backoff"]
  PICK -->|job| MARK["Mark running BEFORE the fetch
a crash leaves it resumable"]
  MARK --> FETCH["REVIEW_FETCHER.fetch
the Worker holds the OAuth token"]
  FETCH --> RES{"Result"}

  RES -->|429| BACK["Exponential backoff, capped at 30s
then up to 250ms jitter · keep the job"]
  RES -->|transient| TR["Separate counter, terminal on the 5th
429s are excluded from this cap"]
  RES -->|other error| FAIL["Terminal: failed"]
  RES -->|page| UP["Upsert reviews idempotently
advance pageToken"]

  UP --> MORE{"Walk state"}
  MORE -->|more pages| PACE["nextRunAt = now + 250ms"]
  MORE -->|backfill done| SEED["Seed the perpetual sync job
first tick at now + 60s"]
  MORE -->|sync hit watermark| PIPE["CLAIM → DRAFT this batch →
NOTIFY → DRAFT the backlog"]

  PIPE --> REARM["Re-arm: pending, cursor reset
nextRunAt = now + 60s"]

  BACK --> SCHED
  TR --> SCHED
  FAIL --> SCHED
  PACE --> SCHED
  SEED --> SCHED
  REARM --> SCHED
  WAIT --> SCHED
  SCHED["finally: scheduleNextAlarm
a throw can never strand the loop"]
  SCHED -->|zero non-terminal jobs left| IDLE["No alarm set — DO goes idle
deliberately, not a bug"]

  classDef startC fill:#0369a133,stroke:#0369a1,stroke-width:2px
  classDef okC    fill:#04785733,stroke:#047857,stroke-width:2px
  classDef badC   fill:#9f123933,stroke:#9f1239,stroke-width:2px
  classDef warnC  fill:#b4530933,stroke:#b45309,stroke-width:2px
  classDef keyC   fill:#0f766e44,stroke:#0f766e,stroke-width:2.5px

  class ALARM,PICK,MARK,FETCH startC
  class UP,PACE,SEED,PIPE,REARM okC
  class FAIL,TR badC
  class BACK,WAIT,IDLE warnC
  class SCHED keyC