Skip to content
nowyourlink Docs

Architecture

nowyourlink is a B2B daily auction platform that sells “The Spotlight” — a single ad position on nowyourlink.com — via a sealed-bid auction that closes at 00:00 UTC each day. The architecture runs entirely on Cloudflare’s edge: Workers, Durable Objects, D1, R2, Queues, KV, Workflows, and Pages.

The binding source of truth is docs/superpowers/specs/2026-05-23-nowyourlink-master-design.md. This page is the narrative on-ramp — the Decisions Log carries the D1–D40 history that pins each choice below, and the Specs Index lists every sub-system spec.

High-level topology

Section titled “High-level topology”

The platform splits into seven Workers (one Astro front-end and six Hono APIs per ADR-0001), backed by Cloudflare’s storage primitives. The docs site itself is a separate Cloudflare Pages project (spec 11 §7).

Visitors and operators use public, API and admin Workers at the Cloudflare edge. Durable Objects own auctions and real-time updates, D1 stores account and payment data, and R2 stores creatives. Payment Workflows connect Stripe, email and the auction state, while Workers report to Sentry.Visitors and operators use public, API and admin Workers at the Cloudflare edge. Durable Objects own auctions and real-time updates, D1 stores account and payment data, and R2 stores creatives. Payment Workflows connect Stripe, email and the auction state, while Workers report to Sentry.

Single-zone deployment (nowyourlink.com) with one Worker route per subdomain — nowyourlink.com (Astro web), api., admin., webhook. (Workers), docs. (Pages). The *.preview.nowyourlink.com mirror exists for the preview environment per spec 13 §8. Terraform owns the routes, DNS, queues, KV namespaces, D1 databases, R2 buckets, and Pages project — see infra/terraform/.

Sub-system map

Section titled “Sub-system map”
NNSub-systemWhat it owns
01Foundation & InfraTerraform, CI/CD, environments, secrets
02Identity & OnboardingOAuth (Google · GitHub), Stripe Identity, first-bid SetupIntent
03Ad ModerationCreative upload, AI pre-classification, human queue
04Auction EngineAuctionDO per YYYY-MM-DD, bid placement, anti-snipe, close & reveal
05Payment SagaStripe Workflows saga, cascade to runner-up on failure
06Real-Time HubHibernatable WebSockets, 1Hz batched fanout, per-bid top-3
07Public Site & ArchiveDay pages, OG cards, click tracking
08Advertiser DashboardCampaign reports, conversion pixel
09Engagement FeaturesPush notifications, share artifacts
10Admin ConsoleManual refund, moderation decisions, KYC queue
11Docs SiteThis site — Starlight + auto-sync
12Legal & ComplianceDPA, sub-processors, data-rights flow, invoice retention
13Quality & ReleaseTDD, coverage, CODEOWNERS, branch protection

Cross-cutting flows

Section titled “Cross-cutting flows”

Three diagrams capture the load-bearing interactions across sub-systems. Each links to the source-of-truth process page under docs/superpowers/processes/; the call-by-call text lives there so this overview stays scannable.

Bid placement — apps/api → AuctionDO → WS hub

Section titled “Bid placement — apps/api → AuctionDO → WS hub”

A bidder submits an amount; apps/api validates and forwards to the daily AuctionDO, which atomically writes the bid, recomputes rank, and broadcasts a bid.placed event via the real-time hub for the live leaderboard. Anti-snipe extends closes_at_actual when a bid lands inside the configured window.

A bidder sends a bid to the API, which delegates validation, storage and ranking to AuctionDO. Bids in the anti-snipe window may extend closing time. The API returns the rank and the WebSocket hub broadcasts the leaderboard update.A bidder sends a bid to the API, which delegates validation, storage and ranking to AuctionDO. Bids in the anti-snipe window may extend closing time. The API returns the rank and the WebSocket hub broadcasts the leaderboard update.

Full process — validation order, idempotency contract, top-3 position event: 04 — Bid Placement.

Payment saga — happy path

Section titled “Payment saga — happy path”

After auction close, the Workflows-backed saga charges the winner via Stripe, generates the invoice, and persists the audit trail. Failure paths cascade to the runner-up — see 05 — Payment Saga Cascade.

AuctionDO starts the payment workflow. Stripe payment confirmation resumes the workflow, invoice details are stored in D1, email is sent and the auction receives settlement confirmation.AuctionDO starts the payment workflow. Stripe payment confirmation resumes the workflow, invoice details are stored in D1, email is sent and the auction receives settlement confirmation.

Full process — saga state machine, webhook signalling, idempotency keys: 05 — Payment Saga Happy Path.

Day page render — archive + OG card

Section titled “Day page render — archive + OG card”

Each settled auction publishes a day page on nowyourlink.com/d/YYYY-MM-DD with the winning ad, click-through tracking, and an OpenGraph card generated on demand.

A visitor requests a day page. The web Worker gets the winning advertisement and creative information through the API, renders the page, and sends advertisement clicks through a logged redirect.A visitor requests a day page. The web Worker gets the winning advertisement and creative information through the API, renders the page, and sends advertisement clicks through a logged redirect.

Full process — OG generation, click-token signing, redirect logging: 07 — Day Page Render · 07 — Click Tracking Redirect.

Reference

Section titled “Reference”