Skip to content

Intranet build, deploy, and schema-sync constraints (the earned constants)

Guide

<!-- last-reviewed: do not apply expiry — knowledge entries are dated records (governance = supersession, not expiry; see knowledge-management.md §5) -->

Intranet build, deploy, and schema-sync constraints (the earned constants)

  • Date: 2026-06-01 · By: Engineering (Engineering Director / Staff Engineer / Platform Engineer)
  • Topic: intranet build/deploy/schema constraints — the named numbers and footguns
  • Status: active

Append-only, dated, one topic per entry. This is the inbox — captured first; when durable it is promoted into the corpus and this entry links to its new home (Promotion field below).

What we learned

Phase 0 (the three Engineering codebase reviews) surfaced a set of falsifiable constants and footguns that a fresh agent must know before touching intranet/. They extend docs/knowledge/2026-05-30-intranet-and-archive-automation.md with the version and deploy specifics paid for since.

  • Version is Astro 6, not Astro 5. intranet/package.json declares astro ^6.4.2 and CLAUDE.md’s Tech Stack table says Astro 6, but the agent definitions (.claude/agents/engineering-director.md lines 20, 28) still say “Astro 5”. The defs are stale; the live version is 6. (Flagged to HR — defs are HR-owned.)
  • The Vite pin is load-bearing. package.json pins vite ^7.3.3 because @tailwindcss/vite 4.x fails against the Vite 8 peer dep. The unpin condition is documented inline: npm show astro dependencies | grep vite — unpin when Astro’s internal Vite reaches 8. A blind dependency bump that pulls Vite 8 breaks the build.
  • Never run astro build / astro dev bare. The correct entry points are npm run build / npm run dev — both run npm run sync first. sync-content.mjs does rmSync(GEN, …) (line 13) every run, so src/generated/ (gitignored) is empty until synced; a bare astro build builds against nothing.
  • Slug collisions are silent. slugOf (sync-content.mjs:46) lowercases and replaces [/.] with -; two sources collapsing to the same slug overwrite via writeFileSync with no warning. There is no collision detection today.
  • Schema is dual-homed and guarded only on presence. intranet/src/lib/db.ts re-declares chatter_channels / chatter_messages so the Vercel Function bundle is self-contained; db/schema.ts (Data & Analytics-owned) is canonical. scripts/check-schema-drift.mjs guards them but compares column names only (line 25/73) — it does not catch type or nullability drift. Eyeball types.
  • Deploy budget is 100/day, brake is discipline. Vercel Hobby allows 100 deployments/day (ADR-0009). Two mechanisms reduce burn: vercel.json disables previews and sets ignoreCommand; vercel-ignore.sh skips non-production builds and production commits with no portal-relevant diff (hand-maintained path allowlist, lines 15–18). There is no machine deploy-counter — the brake is GR-7 batch-pushing.
  • Migrations use the unpooled URL. ADR-0014: DATABASE_URL (pooled) for queries, DATABASE_URL_UNPOOLED for migrations only. Crossing them is the dead end to avoid.
  • Auth is the only access control. ADR-0008: Vercel Authentication (Standard, All Deployments) gives single-user access; verify by fetching the URL unauthenticated and expecting the login interstitial, not the dashboard.

Why it matters

These are the constants Engineering operates against. Getting any one wrong has a concrete cost: a blind dep bump breaks the build (Vite pin); a bare astro build ships stale pages; a slug collision silently drops a doc; a pooled-URL migration fails; an un-batched push burns the deploy budget. Naming them once stops every future instance re-paying for them.

Next time

  • Use npm run build / npm run dev only; report the real [sync] … line + page count.
  • Before any dependency bump, check the vite-pin note and npm show astro dependencies.
  • Treat the deploy budget (100/day) as a hard ceiling; batch pushes per checkpoint (GR-7).
  • For migrations, use DATABASE_URL_UNPOOLED; for queries, the pooled DATABASE_URL.
  • After a schema change, run check-schema-drift.mjs and eyeball types/nullability.
  • (Recommended) add slug-collision detection and type-aware drift checking — see the Phase 0 reviews’ recommendations.

Promotion

  • Promoted to: the Engineering playbook (docs/units/engineering/playbook.md) draws its hard numbers and demons from this entry; the build footguns are in docs/units/engineering/job-aids/JA-056-local-dev-build-cycle.md and the deploy constants in docs/units/engineering/job-aids/JA-058-deploy-intranet-steps.md.
  • Supersedes / superseded by: extends (does not supersede) docs/knowledge/2026-05-30-intranet-and-archive-automation.md.