Technical documentation
Architecture & decisions
Which Cloudflare primitive powers each demo on this site, where, how, and why. Every demo is a real, working proof-of-concept on the actual platform, running on Cloudflare Pages + Pages Functions.
Per-demo architecture charts live on How it works; the long-form under-the-hood detail and hard-question answers are in the demo deep-dive (PDF).
| # | Feature | Demo | Cloudflare primitive(s) |
|---|---|---|---|
| 1 | Turnstile: invisible human check | The Toll Collector | Turnstile + Pages Functions |
| 2 | AI-crawler control | The Rustler | Workers (edge logic) |
| 3 | Geo-residency | The Two-Faced Drifter | Workers + D1 ×2 (location-pinned) |
| 4 | Grounded trust assistant | Snake-Oil Sam | AI Search (AutoRAG) + R2 + Workers AI |
| 5 | Rate limiting | The Stampede | Rate Limiting (D1 fallback on Pages) |
| 6 | Edge caching | The Slowpoke | Cache API / CDN |
| 7 | Atomic inventory | The Hoarder | D1 (atomic UPDATE) |
| 8 | Consent-gated dispatch | The Midnight Caller | D1 (consent ledger + audit) + Pages Functions |
| 9 | Campfire joke bot | site-wide | Workers AI + TTS → pre-baked static |
| 10 | Defend the Edge leaderboard | /range game | D1 (+ hashed-IP rate limit) |
Hosting and runtime for everything: Cloudflare Pages + Pages Functions. Free tier; AI Search, Vectorize, R2, and Workers AI sit within free allowances. The Campfire voice is a paid partner TTS model, but it is pre-baked once to static audio, so there is no per-use spend.
1. Turnstile: invisible human verification
- What
- Cloudflare Turnstile (a CAPTCHA replacement) plus a Pages Function doing server-side siteverify.
- How
- The client widget issues a token; the server POSTs the token and secret to Cloudflare’s siteverify endpoint and gets back the verdict. A mode toggle uses Cloudflare’s documented test keys to force a blocked-bot failure on demand.
- Why
- Removes CAPTCHA friction and a privacy/accessibility liability. The SE point: a widget without the server-side check is security theater; the verify call is the boundary.
2. AI-crawler control
- What
- A Worker that fingerprints AI crawlers by User-Agent and applies an allow / license (402) / block (403) policy.
- How
- A registry of crawler signatures (GPTBot, ClaudeBot, CCBot, PerplexityBot, and more), with an override to simulate and an enforce flag that returns the real 402/403.
- Why
- Turns an uncontrolled content leak into an edge policy decision, mirroring Cloudflare’s pay-per-crawl direction. In production, lean on verified bot signals rather than User-Agent alone.
3. Geo-residency
- What
- Two D1 databases with real location hints (EU and US); a Worker routes each write to the caller’s jurisdiction.
- How
- The Worker reads request.cf.country (free, at the edge, no geo-IP service), maps EEA to the EU store and everything else to the US store, then does an atomic INSERT. A country override drives the demo.
- Why
- Makes "EU data stays in the EU" provable and enforceable at write time, not an honor-system promise. Plays to the GDPR/compliance story.
4. Trust assistant
- What
- Grounded compliance Q&A over a fictional company’s docs via AI Search (AutoRAG).
- How
- aiSearch() returns an answer with citations; the endpoint flags a refusal when retrieval is empty or weak, or when the model emits the configured "not in our documentation" phrase.
- Why
- Turns the stale-PDF trust center into a live, cited, self-serve asset, and the refusal is the AI-governance money shot: it declines rather than hallucinating. One gotcha: the similarity cache must stay off, or a cache hit reads as a false refusal.
5. Consent-gated dispatch
- What
- An emergency-notification dispatcher that enforces consent and quiet-hours at send time, with an append-only D1 audit trail.
- How
- For each recipient, a Pages Function checks the consent ledger and the recipient’s local quiet hours, suppresses anything non-compliant, and writes one immutable audit row per decision.
- Why
- Mirrors the regulated-comms problem (TCPA consent, quiet hours, regulator evidence). Compliance is enforced in the code path, not asserted in a policy doc.
6. Defend the Edge leaderboard
- What
- A D1-backed leaderboard for the shooting game at /range.
- How
- Each submit is one atomic INSERT (no read-modify-write race); GET returns the top scores; a per-IP rate limit throttles flooding with the IP hashed, never stored raw.
- Why
- D1’s atomic inserts eliminate the lost-update race; rate-limit and clamping stop flooding and absurd values. Honest scope: this is not server-authoritative anti-cheat, which would be overkill for a toy.
Cross-cutting
- Hosting: Cloudflare Pages (static Astro build) plus Pages Functions for everything live. Scale-to-zero; idle costs nothing. The only recurring cost is the domain.
- Secrets: anything sensitive is a runtime binding read on the server, never a client-exposed build variable. Health checks report presence and length, never the value.
- Local vs deployed: wrangler pages dev runs the Functions; plain astro dev serves the static site only, so the API routes 404 there (expected).
- Cost: no Workers Paid plan required. The one paid line (Aura-2 TTS) is pre-baked to $0 recurring. The same primitives that make this cheap make a real product cheap to scale.