Architecture Overview

Request and delivery path

1. Developer calls Gateway API with Bearer key.
2. Gateway authenticates, validates payload, writes notification row, and enqueues message.
3. Delivery Worker consumes queue entries.
4. Delivery Worker resolves tg_chat_id and asks DO rate limiter to send to Telegram.
5. Delivery results are written back to D1.

Rate controls

• Global pacing enforced in Durable Object.
• Per-chat cooldown enforced at 1 second.
• Queue retries handle transient failures (429, 5xx, network errors).

Storage responsibilities

• users: tenant/user chat mapping + phone verification status.
• api_keys: auth and key lifecycle metadata.
• notifications: delivery status surface for /v1/status/:tracking_id.
• notification_attempts: granular attempt logs.
• KV token stores: short-lived onboarding session state.