The engineering behind proofoftech.org
This page documents the technical decisions that make this site fast, secure, and maintainable — from the framework down to the CSP hash that protects this page.
The technology that powers the site.
The site is built with Astro 7 as the static-site generator, deployed on Cloudflare Workers via the @astrojs/cloudflare adapter. Every page is prerendered at build time, including blog posts and tag archives. Only the API endpoints run on the Worker at request time.
Field Notes live in version-controlled MDX files and compile with the site. A secure, access-controlled database stores contact and subscription records, while session state stays separate from editorial content. An automated abuse-prevention check protects the contact and newsletter forms. Confirmations and receipts route through a dedicated transactional email service.
Styling is Tailwind 4 with a custom design-token system (ink/paper surfaces, rule colors, signal alerts) defined in CSS custom properties. All TypeScript is checked with TypeScript at strict settings. Code quality is enforced by Biome (formatting and linting) and remark (content linting for Markdown correctness and link integrity).
Lighthouse budget, Core Web Vitals, and preload strategy.
The site ships with a Lighthouse CI budget enforced in CI — any change that degrades performance below the threshold blocks the deploy. The target is LCP under 2.5 seconds on mobile throttled connections, with all Core Web Vitals passing the "good" threshold.
The body font's Latin subset is preloaded with <link rel="preload"> so it downloads in parallel with the stylesheet instead of waiting for the @font-face rule to be discovered — the largest text on the page renders in its final font sooner. The monospace font — used only in code blocks and interface labels below the fold — is registered after first paint through the CSS Font Loading API, so its subset never competes with the critical render. Fonts are self-hosted, subset to the character ranges the site uses, and served with font-display: swap to prevent invisible-text shifts.
View the live PageSpeed Insights report for proofoftech.org →
Content-Security Policy, security headers, and anti-spam.
Every prerendered page is served with a strict Content-Security Policy. A build integration computes SHA-256 hashes for executable inline scripts after minification, then injects the unified hash allowlist into every page so it remains valid across soft navigation. The script-src directive allows neither 'unsafe-inline' nor 'unsafe-eval'.
Prerendered pages and static files include strict security headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: strict-origin-when-cross-origin, and Strict-Transport-Security with a one-year max-age and preload. On-demand API responses receive X-Content-Type-Options: nosniff through Worker middleware.
The contact and newsletter forms combine an automated abuse-prevention check with a honeypot field that catches basic automated submissions without user friction. Honeypot submissions are silently discarded; a failed automated check returns a verification error so the visitor can retry.
How field notes are researched, written, and verified.
The Field Notes section is powered by an AI-assisted research pipeline — detailed in full at /field-notes-methodology/. Each post is researched, drafted, reviewed, and checked against source material in a process designed for accuracy and traceability.
The current corpus: 115 published posts. The research notes are distilled from 374 arXiv papers and technical sources, with 374 out of 374 arXiv citations verified against their source documents — every citation links to its source so readers can validate claims directly. Build notes — first-party engineering write-ups of features shipped on this site — are verified differently: by the measured numbers they publish and the running system they describe.
The pipeline is not a black box — the methodology page documents the specific models, prompts, and verification steps used in production.
Hybrid BM25 and dense vector search on Workers AI.
The Ask Field Notes feature lets visitors query the entire post corpus in natural language. It uses a hybrid search combining BM25 (keyword) and dense vector (semantic) retrieval — both running on Workers AI with embeddings stored in Cloudflare Vectorize.
The BM25 index rebuilds automatically on every site build. The dense index is populated on demand via a seed:vectors script that embeds each post through Workers AI and upserts the vectors into Vectorize. Retrieved passages are ranked by a reciprocal-rank fusion (RRF) scorer before being passed to the generation model.
The same dialog has a turn-based voice mode: a recorded question is transcribed by Whisper on Workers AI, the transcript runs through the identical grounded-answer path, and the streamed answer is split into sentences and spoken back through Deepgram Aura — the text answer and its citation cards keep rendering while the audio plays, so the grounding stays inspectable. Turn-based means what it says: the reply starts a few seconds after you stop talking; it is not an interruptible full-duplex agent. Audio is transcribed in memory and never stored — only the text of the question is processed, the same posture as a typed query.
Per-post Markdown and RSS endpoints.
Every blog post is available as a plain-text Markdown file at /blog/<slug>.md, served with Content-Type: text/markdown. These are linked from each post's <head> via rel="alternate" so readers and tooling can pull the source directly.
The full post index is available as an RSS feed at /rss.xml, generated at build time from the content collection. Each entry includes the post summary, publication date, and tags.
How this page is built.
This page is statically rendered at build time. There is no client-side JavaScript framework — every interactive element on the site (the contact sheet, the mobile menu, the subscribe form) is a hand-written TypeScript island attached to the relevant DOM element via astro:page-load. No React, no Vue, no Svelte — just Astro + vanilla TypeScript.
OG share cards are generated at build time as static JPEG files by Satori and Sharp. Posts and named pages use content-specific overlays; pages without a dedicated card use the shared site card. Nothing renders these images at request time.
Bring us a hard problem. We'll show you what we'd build.
The first call is a free 30 minutes. You'll leave with the first cut of the build/no-build path, the riskiest assumption, and the eval we'd use to test it.