factory-deployment

Factory deployment

Most of this skill is Recipe — deployment is where stack-specific decisions are the substance, not the surface. The few load-bearing principles (one service per entry point, migrations in CI, boot-time assertions, single-tenant customer-cloud as the commercial wedge) lead their sections; the rest are marked Recipe only.

Web — Vercel + Neon

Recipe only — stack pick.

Aspect	Choice
Hosting	Vercel
Database	Neon (Postgres) — dev branches for PRs, prod for main
Migrations	drizzle-kit migrate in GitHub Actions, against ephemeral Neon branch
Env vars	Vercel project + t3-oss/env-nextjs Zod validation
Preview safety	Boot-time assertion: VERCEL_ENV=preview MUST NOT use prod DATABASE_URL

Boot-time assertions for configuration safety

Principle. Configuration mistakes that could cause data loss or cross-environment writes fail loud at boot.

Why. A misconfigured preview deployment that connects to prod is the silent kind of incident — preview writes look like real writes, no error fires, the data contaminates for days. A boot-time assertion that compares VERCEL_ENV against DATABASE_URL makes the misconfiguration instant and visible. Three lines of code; one prevented incident pays for them many times over.

Recipe.

// src/db/index.ts — boot-time assertion
const isPreview = process.env.VERCEL_ENV === 'preview';
if (isPreview && process.env.DATABASE_URL === process.env.PROD_DATABASE_URL) {
  throw new Error('Preview deployment cannot use prod DATABASE_URL');
}

One Cloud Run service per Python entry point

Principle. Each Python entry-point variant (CLI, API, Pub/Sub) gets its own Cloud Run service with its own Dockerfile.

Why. Sharing a service across entry points means the startup command is conditional — if mode == 'api' run uvicorn; else run pubsub-handler — which makes the service definition impossible to validate at deploy time. Separate services have separate Dockerfiles, separate startup commands, separate scaling configurations. The cost is more Cloud Run services; the benefit is each one is independently deployable, scalable, and debuggable.