$ cat ARCHITECTURE.md

How this site works.

This page is served by the architecture it documents. The resume is a Next.js 16 App Router app on Vercel — TypeScript, Tailwind CSS 4, one content file driving every section — that recently grew its first server surface: a model-routed AI chat and a durable calendar-booking agent. Everything below is the deliberate version of how that was done.

Rendering: static shell, streamed holes

cacheComponents: truemakes Partial Prerendering the default. The resume page prerenders to a static shell served from Vercel's edge CDN — LCP is a static asset — while anything dynamic must sit behind a Suspense boundary and stream at request time. The framework enforces the split at build time instead of leaving it to convention.

The interactive surfaces are client-component islands inside a React Server Components shell. The chat console loads via next/dynamicbelow the fold, so its bundle never taxes first paint. This page's gateway-catalog block below is a 'use cache' function with cacheLife('hours'): cached in the static shell, revalidated in the background.

The chat: AI SDK v7 + AI Gateway model routing

POST /api/chat is a route handler using streamText with plain creator/modelstrings — the AI SDK's default provider is Vercel AI Gateway, so there are no provider SDKs and no provider API keys in this codebase. In production the function authenticates to the gateway with its Vercel OIDC identity.

Every message is first classified by a tiny fast-lane call, then routed: anthropic/claude-haiku-4.5 for short factual queries, anthropic/claude-sonnet-4.6 for technical depth, with cross-provider fallbacks (providerOptions.gateway.models) if a provider degrades. The gateway reports back which model and provider actually served each response, why, token usage, and cost — that telemetry streams to the MODEL ROUTER panel beside the chat as per-message metadata. Zero markup on tokens; the routing is the product.

The functions run on Fluid Compute, which matters for AI endpoints: most of their wall-clock is waiting on model tokens, and Active CPU pricing means waiting is nearly free while instances stay warm and share concurrency.

The booking agent: durable by construction

Typing book hands the console to a backend agent built with eve, mounted into this same project with withEve. Sessions persist through Vercel Workflows — refresh the page mid-booking and the session resumes where it stopped. The agent has exactly two tools: get_slots (rule-legal candidates minus real Google Calendar free/busy) and book_call (creates the event with a Google Meet link and emails the invite).

The model's word is never trusted: book_callre-validates the slot against the business rules and re-checks free/busy immediately before inserting, then re-checks for overlaps immediately after — a double-booking race loses cleanly and the visitor gets fresh times. Credentials never reach the model: tools exchange a server-held token for Google access inside the runtime. Every session, turn, tool call and token count is inspectable in Vercel's Agent Runs observability.

Security & abuse control

The AI endpoints are the attack surface, so they get layers: BotID (invisible bot detection, no CAPTCHAs) gates /api/chat and the token mint; the eve channel requires a short-lived HS256 token from that mint, so bots never open a session; per-IP rate limits and output-token caps bound cost; and a config-store kill switch can disable chat or booking in seconds without a redeploy. Security headers (nosniff, HSTS, frame-deny) ship on every response. Secrets live in environment variables and OIDC — the repo contains none.

Delivery & observability

Git-based CI/CD with a preview deployment per branch; production is promoted only after the preview passes verification — including a real booking on the live calendar and Lighthouse accessibility/SEO at 100 in both themes, which this site treats as a hard gate. Web Analytics and Speed Insights report real-user metrics; AI Gateway's dashboard logs every model request with latency and spend; Agent Runs traces the booking sessions.