travismetcalf.com · patterns

Decisions,
with dates.

The rules this platform is built by — each one a real decision made once, applied everywhere, and written down with its reasoning. An undisturbed date is a decision that has held; when one changes it is superseded in place with a successor, never silently rewritten. This is the public edition: patterns as ideas. The full operating reference — hostnames, ports, runbooks, the gotchas — is tailnet-only.

All decisions reviewed & current as of 2026-08-04

Security

The edge

Pattern · edge architecture · 2026-09-06 · accepted

Private by default, and the tailnet is the login

Only what is meant to be public is public: this site and the commute app's API. They arrive through a managed CDN + WAF (Cloudflare) and an outbound-only tunnel to a reverse proxy (Caddy), so the origin has no inbound port to find. Every other app answers only to devices on the private network (Tailscale): device identity replaces a login page, and a stranger gets a 404. This replaced the layered chain below and retired its SSO stack with it — fewer moving parts, and nothing private left on the public internet. Two rules keep it honest:

  • The gate runs at the proxy, before any routing. It checks for a tailnet address and resolves the true client address of tunnelled requests, so a public request can never pass as a private one.
  • Two independent layers say no. The CDN refuses private hostnames at the edge and the proxy refuses them again at the origin, and an outside-in probe tells the two apart — losing either layer fails a check instead of passing silently.

Pattern · edge architecture · 2026-06-16 · superseded 2026-09-06 by private by default

Defense in layers, and the gate runs first

Public traffic reaches the lab through a managed CDN + WAF (AWS CloudFront), then an encrypted tunnel (Tailscale) to a reverse proxy (Caddy), with single sign-on + MFA (authentik) in front of every app. Two rules make the chain honest:

  • The CDN cannot be bypassed. The origin authenticates the CDN with a shared secret and refuses everything else — evaluated before any routing logic, fail-closed, so the WAF is load-bearing rather than decorative.
  • Public and LAN listeners are physically separate. A spoofed Host header on the public path can only ever reach the gated listener. This closed a real bypass found by testing the assumption, not trusting it.

Pattern · trust surfaces · 2026-09-06 · accepted

One name per app, one trust boundary

The home-network shortcut names went away with the SSO surface. Each app now has a single hostname that reaches the same proxy from every device on the tailnet, and the tailnet is the only trust boundary — no second, looser surface left to keep read-only.

Pattern · trust surfaces · 2026-08-04 · superseded 2026-09-06 by one name per app

LAN reads are free; writes belong to the SSO surface

Convenience surfaces on the home network are read-only by design — mutating routes answer with a redirect to the authenticated public URL. "Ungated reads" must never quietly become "ungated writes."

Operations

Every project, the same shape

Pattern · project template · 2026-07-12 · accepted · revised 2026-08-23

A new service isn't done until it can prove it's alive

Every project ships the same skeleton: a git repo with an .env.example, containerized runtime, a scheduled smoke test that exercises real behavior, a success-marker the monitoring can check, and email alerts through one shared notifier library. Every scheduled job reports a heartbeat, and a missing one raises the alarm on its own, so a job that silently stops running is caught too.

Pattern · monitoring · 2026-07-16 · accepted

Four questions, not one: alive, correct, drifted, wasteful

Liveness checks miss whole failure classes. The fleet is watched on four axes: is it running; is its output right; does the deployed state match git and the pinned images; and is a healthy service quietly burning resources. That last axis exists because a container once burned two cores for five days while every green check stayed green — measured properly, lifetime-average CPU separates "busy" from "stuck" where a snapshot is a coin flip.

Pattern · deploys · 2026-07-12 · accepted

Git is the transport; the checkout is the artifact

Edit on the laptop, push, pull on the server, restart if needed. No CI pipeline to babysit for a one-person platform — but drift checks verify the deployed state matches the remote, so the simple path stays honest. Static sites (including this one) deploy by git pull alone.

Pattern · backups · 2026-07 · accepted

Code lives on GitHub; only runtime data is backed up

Nightly snapshots of runtime data to network storage with 30-day retention — and restore tests, because a backup that's never been restored is a hope, not a backup.

AI

A force multiplier, inside guardrails

Pattern · AI leverage · 2026-08-04 · accepted · revised 2026-09-06

AI does real work here — under the same rules as everyone else

AI isn't a demo on this platform; it's on the payroll. Models score the intelligence reader's stories in production, local models handle what should never leave the house, and an AI engineering partner helps build and operate the platform itself — including this site.

The leverage is only safe because the guardrails don't care who's working: model spend sits under a hard cap set at the provider, every change lands through git and the same drift checks, and nothing AI-made skips the smoke tests. Trust the output because the system verifies it, not because the model sounded confident.

Design & frontend

One language, many runtimes

Pattern · design system · 2026-07-12 · accepted

Tokens once, adapters everywhere

Brand values live in one namespaced CSS custom-property file; each app maps them onto its own variables through a thin adapter and vendors a copy at deploy time. Plain CSS custom properties are the only layer low enough to skin a React app, server-rendered Python templates, a themed third-party app, and (via generated constants) a native iOS build from the same source. The styleguide renders from the live values, so it cannot drift.

ADR · 2026-08-04 · accepted

Frontend defaults: static first, then Next.js + TypeScript

Content and document sites are static HTML consuming the tokens — no build step, nothing to operate for a decade. Interactive app frontends default to Next.js + TypeScript + Tailwind (v4's @theme maps the custom-property tokens cleanly). Existing apps are not retrofitted: operational simplicity outranks framework uniformity, and a read-mostly dashboard doesn't need a Node build chain.

Copied