nextjs-postgresql-single-app

Imported from nordeim/personalized-tutor-app (skills/nextjs-postgresql-single-app/SKILL.md). Install upstream with npx skills add nordeim/personalized-tutor-app --skill nextjs-postgresql-single-app. Copyright stays with the author.

home-financing (ModFii) — Production Web App Skill

Refer to the codebase in https://github.com/nordeim/home-financing.git as the foundation/example to scaffold other projects using similar tech stacks.

Reusable distillation for any Next.js 16 App Router + React 19 + TypeScript 5.9 strict + Tailwind CSS v4 CSS-first @theme + Drizzle ORM 0.45 + PostgreSQL 17 + pg Pool singleton + Vitest 4.1 + Playwright 1.63 project. Generalizes beyond mortgages to any content-driven marketing + transactional funnel app (editorial guides, calculators, lead capture, lender/product matching). What it teaches: 20-section production reference distilled via Six-Phase Archaeology — Project Identity & Design Philosophy (editorial + brutalist restraint, forest/cream/amber tokens), Tech Stack & Versions (pinned), Bootstrapping & Config (tsconfig strict, next.config redirects/images.unoptimized, eslint flat, drizzle.config dual, docker-compose PG17 + pgcrypto/pg_trgm), Design System (verbatim @theme + radii/shadow/ease + typography), 5-Layer Architecture (file corpus → catalog → ensureSeeded projection → Pool singleton → RSC/force-dynamic → redirects), Component Map (Server Components by default, 6 use-client islands), Hooks (inlined useId/adjust-during-render/passive: true/body-lock), Content Ingestion (file-backed JSON → ensureSeeded count>0 + onConflictDoNothing → PG, 152 sitemap locs), A11y (WCAG AAA contrast/focus/prefers-reduced-motion/axe critical: []), 14 Anti-Patterns + Debugging Guide (H4/OOM server kill, second Pool EMFILE, .env leak d572d73, missing hero images, setState-in-effect, tailwind.config drift), Pre-Ship Gate (db:setup → lint 0/0 → typecheck → test 41/41 → build 43/43 (35+8) → e2e 121/121), Lessons/Pitfalls/Best Practices, 6 Copy-Paste Patterns (canonical funnel rateLimit→json→validate→seed→match→persist, health probe, idempotent projection, PMI 0.0065 + 1.15×, sitemap), Responsive/Z-Index/Color (hex-exact) & 8-domain TypeScript Interfaces.

Discoverability: Matches nextjs16, react19, app-router, rsc, tailwind4, drizzle, postgres17, vitest, playwright, server-components, drizzle-kit, pg-pool, next-font, lucide-react. Use to scaffold, debug, onboard, or ship any similar full-stack marketing/funnel app without repeating 2026-09-11 incidents.

Companion Documents: Project_Architecture_Document.md v1.0 (blueprint) · CLAUDE.md (agent spec, ~600 lines) · AGENTS.md (cheat-sheet) · README.md (operator guide) · docs/REMEDIATION_PLAN_pass4.md (pass-4 evidence) Last Updated: 2026-09-15 (v1.8 — pass 9 drift alignment D-01→D-07: STATIC_PATHS 40→39, build 36+7/42+8→35+8, E2E 61/82→121, radii 1.25/1.5→0.625/0.75/1.0, MORE 4→2, blur-md→lg; validation docs/VALIDATION_REPORT_SKILL_2026-09-15.md 11 drifts patched. Pass 8: audit remediation .env hygiene + vitest 4.1.11; pass 7: live-source parity; pass 6: audit) Project State: 41 Vitest (11+13+9+8, incl. H4/OOM regression) + 121 Playwright per project (121/121 with DB, 120/121 DB-less — 103 declarations + data-driven loops: smoke 8 + seo 16 + funnel 5 + assets 19 + parity 73) · 43/43 Next build · PG 17 8/40/50/23/59/5 seeded · lint 0/0 · typecheck pass Audience: AI Coding Agents, Senior Engineers, Tech Leads, DevOps, Onboarding Engineers Rule: Every rule in this document traces to a specific file, test, or live probe. Nothing is here "because it's popular."

How to use this document

• New agent / engineer → Read §1 (Identity) → §2 (Stack) → §3 (Bootstrap) → §5 (Architecture + Golden Rule) → §11 (Pre-Ship) then run npm run db:setup && npm run lint && npm run typecheck && npm run test && npm run build && npm run e2e.
• Fixing a bug → Jump to §9 (Anti-Patterns) → §10 (Debugging Guide) → §12 (Lessons). Every anti-pattern has a test that prevents recurrence.
• Adding a feature → §5 (Layer Model + Component Map) → §7 (Content) → §15 (Patterns) → §20 (Interfaces). Don't bypass the layer.
• Shipping → §11 (Pre-Ship Checklist) is the gate. No any, no second Pool, no tailwind.config.*, no DB hand-edit must survive it.
• Onboarding a team → Distribute this file + PAD + AGENTS.md. PAD is the topology/ADR authority; this SKILL is the negative space — what not to do, how to debug, how to avoid repeating 2026-09-11 incidents.

Table of Contents

1. Project Identity & Design Philosophy
2. Tech Stack & Environment
3. Bootstrapping & Configuration
4. The Design System (Code-First)
5. Component Architecture & Patterns
6. Custom Hooks Deep Dive
7. Content Management & Data Ingestion
8. Accessibility (WCAG AAA) Implementation
9. Anti-Patterns & Common Bugs
10. Debugging Guide
11. Pre-Ship Checklist
12. Lessons Learnt & How to Avoid Them
13. Pitfalls to Avoid
14. Best Practices
15. Coding Patterns
16. Coding Anti-Patterns
17. Responsive Breakpoint Reference
18. Z-Index Layer Map
19. Color Reference (Complete)
20. The Complete TypeScript Interface Reference

• Appendix A: Architecture Decision Records
• Appendix B: Pipeline Costs
• Appendix C: Audit History
• Appendix D: Live-Site Validation & Quick Reference Card
• Appendix E: The Meticulous Approach (6-Phase Workflow)

1. Project Identity & Design Philosophy

One-sentence identity: ModFii (home-financing, legacy nextjs-postgresql-template) is a content + transaction hybrid for prefab homebuyers — SEO-driven editorial (23 articles, 50 state guides, 40 manufacturers) plus a single 13-field pre-qual funnel (12 required + optional manufacturerSlug) (/get-started → validateApplication → matchLenders → applications + top-4 application_matches) that closes the loop on modular/manufactured/ADU/tiny-home financing where traditional lenders fail.

Design thesis — Editorial + Brutalist Restraint (Luxury-Dark Cinematic without purple slop):

Non-negotiable rules:

1. File corpus is the source of truth — edit src/data/*.json + src/lib/lenders.ts, never PG rows. DB is a projection (ensureSeeded).
2. Single Pool — globalThis.__arenaNextJsPostgresqlPool only. Never new Pool() inline.
3. Token-driven styling — @theme only. No tailwind.config.*, no text-[13px] arbitrary.
4. RSC by default — "use client" only for site-header, prequal-form, calculator-app. Never import Server → Client.
5. Prefinancing accuracy — PMI_ANNUAL_RATE 0.0065 and site-built 1.15× are auditable constants (see §15).

CTA hierarchy: Primary (forest) for actions, secondary for hero first CTA, onPrimary (transparent white border) for hero second CTA over dark forest, accent (amber) only for GuideView sidebar closing CTA. No other amber CTA in header.

Does this prevent generic Bootstrap? Yes — the @theme lock, PageHero centered photo contract, forest/cream token discipline, and Container rhythm make generic components visually fail before build does.

2. Tech Stack & Environment

Pinned from package.json (package-lock.json is the lockfile, not pnpm) + docker-compose.yml + drizzle.config.*. No ranges.

3. Bootstrapping & Configuration

3.1 Scaffolding (what was, what to repeat)

This project was not create-next-app scaffolded in its current form — it evolved from nextjs-postgresql-template. To reproduce cleanly:

# If scaffolding a fresh sibling for comparison:
# npx create-next-app@16.3 home-financing-new --ts --eslint --tailwind --app --src-dir --import-alias "@/*"
# Then transplant: src/app/globals.css (@theme), src/db/*, src/lib/*, src/data/*.json, drizzle/*, next.config.ts redirects

For this repo, start from clone — scaffolding is already done. Don't run create-next-app here.

3.2 Dependency Install

npm install   # package-lock.json, not pnpm — single app, no workspace

Runtime: next, react, react-dom, drizzle-orm, pg, lucide-react, dotenv · Dev: typescript, @types/*, eslint, eslint-config-next, tailwindcss, @tailwindcss/postcss, postcss, drizzle-kit, tsx, vitest, @playwright/test, @axe-core/playwright.

3.3 Critical Configuration Files

3.4 Environment Variables

.env is .gitignored (ec11541 untracked it after d572d73 leak). Never git add -f .env. docs/bak.env / env.tgz / ssh-key.txt also ignored — don't reintroduce.

3.5 Local Setup (Minimal → Full)

# 1 — Clone & install
git clone <repo-url> home-financing && cd home-financing
npm install

# 2 — Env (copy then fill required — DATABASE_URL already canonical for Docker)
cp .env.example .env
# Generate if you rotate:
#   openssl rand -base64 32   # BETTER_AUTH_SECRET
#   openssl rand -hex 16      # CRON_SECRET

# 3 — DB (Docker simplest; 5434 intentional — 3000 is taken by scandihaven on this host)
docker compose up -d
docker compose logs -f postgres   # expect pgcrypto: t / pg_trgm: t

# 3b — One-shot init (idempotent, local-guarded)
npm run db:setup   # → [db] migrations applied (0000+0001) + [db] seed complete (8/40/50/23/59/5)
# Granular: npm run db:generate / db:migrate / db:seed / db:reset

# 4 — Run
npm run dev                    # http://localhost:3000 (if free)
# or
npx next dev --port 3002       # http://localhost:3002 (E2E default)
npm run build && npm start     # prod preview

# 5 — Verify
curl -s http://localhost:3002/api/health | jq                    # { ok:true, status:ok, db:true }
curl -s http://localhost:3002/sitemap.xml | grep -o "<loc>" |wc -l  # 152
npm run lint && npm run typecheck && npm run test && npm run build && npm run e2e

Alternative PG17 (no Docker): DATABASE_URL=postgresql://user:pass@localhost:5432/home_financing_dev npm run dev.

4. The Design System (Code-First)

Single source: src/app/globals.css — never add tailwind.config.*. Every token traced to @theme.

4.1 The @theme Block (Verbatim Evidence)

/* src/app/globals.css — verified against the 1,140-line Project_Architecture_Document.md; home-financing_SKILL.md is this file */
@import "tailwindcss";
@theme {
  --font-sans: var(--font-dm-sans), ui-sans-serif, system-ui, sans-serif;
  --font-display: var(--font-outfit), ui-sans-serif, system-ui, sans-serif;

  --color-background: hsl(40 33% 99%);        /* warm cream */
  --color-foreground: hsl(155 30% 12%);       /* forest text */
  --color-card: hsl(40 25% 97%);
  --color-card-foreground: hsl(155 30% 12%);
  --color-primary: hsl(155 45% 28%);          /* primary forest */
  --color-primary-foreground: hsl(40 33% 99%);
  --color-primary-600: hsl(155 50% 22%);      /* hover */
  --color-secondary: hsl(150 20% 92%);
  --color-secondary-foreground: hsl(155 30% 12%);
  --color-muted: hsl(150 15% 93%);
  --color-muted-foreground: hsl(155 10% 45%);
  --color-accent: hsl(38 92% 50%);            /* amber CTA */
  --color-accent-foreground: hsl(38 95% 12%);
  --color-destructive: hsl(0 72% 51%);
  --color-border: hsl(150 15% 88%);
  --color-input: hsl(150 15% 88%);
  --color-ring: hsl(155 45% 28%);
  --color-cream: hsl(40 40% 96%);             /* section wash */
  --color-forest: hsl(155 42% 16%);           /* deep forest — header/hero */
  --color-moss: hsl(150 22% 34%);             /* muted label */

  --radius-sm: 0.5rem; --radius-md: 0.625rem; --radius-lg: 0.75rem; --radius-xl: 0.75rem; --radius-2xl: 1rem;  /* pass-7 probe: rounded-md 10px / xl 12px / 2xl 16px (sm 8px) */
  --shadow-lift: 0 18px 40px -24px hsl(155 30% 12% / 0.35);
  --ease-brand: cubic-bezier(0.22,1,0.36,1);
}
@layer base { *{border-color:var(--color-border)} html{scroll-behavior:smooth}
  body{background:var(--color-background);color:var(--color-foreground);font-family:var(--font-sans);-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility}
  h1,h2,h3,h4,.font-display{font-family:var(--font-display);letter-spacing:-0.03em}
  :focus-visible{outline:2px solid var(--color-ring);outline-offset:3px}
  ::selection{background:hsl(38 92% 50% / 0.28);color:hsl(155 30% 12%)}
}
@layer utilities { .grain{position:relative}.grain::after{content:"";position:absolute;inset:0;opacity:.08;mix-blend-mode:multiply;background-image:url("data:image/svg+xml;utf8,<svg ...><feTurbulence baseFrequency='0.85' numOctaves='2'/></svg>")} .hero-grid{background-image:linear-gradient(40deg/0.04) 48px} }
@media(prefers-reduced-motion:reduce){html{scroll-behavior:auto}*,*::before,*::after{animation-duration:.01ms!important;transition-duration:.01ms!important}}

If this block drifts, every assets.spec.ts + PageHero test conceptually fails — brand token authority is the lint.

4.2 Typography Hierarchy

4.3 Border Radii & Shadows

4.4 Utilities

5. Component Architecture & Patterns

5.1 The 5-Layer Model + Golden Rule

Layer 0: File Corpus — Authoring. Rule: Edit src/data/*.json + src/lib/lenders.ts. Never hand-edit PG.
Layer 1: Catalog — Typing. Rule: src/lib/catalog.ts re-exports JSON as Manufacturer/StateGuide/Article/GlossaryTerm; UI imports only from @/lib/catalog and @/lib/guides.
Layer 2: Projection — Seeding. Rule: src/lib/ensure-seeded.ts is the only write path; __modfiiSeedPromise + count(lenders)>0 + onConflictDoNothing; called in /api/health + /api/applications.
Layer 3: Persistence — Storage. Rule: src/db/index.ts Pool singleton __arenaNextJsPostgresqlPool; never new Pool() inline; db is drizzle(pool).
Layer 4: Application — Rendering. Rule: Server Components by default; "use client" only for site-header, prequal-form, calculator-app; never Server→Client; force-dynamic only where DB touched.
Layer 5: Edge — Routing. Rule: Redirects live in next.config.ts:redirects(); add aliases there only; build validates, e2e/assets pins.

Import boundary: src/components/ui.tsx (cn, Button/ButtonLink/Container/Badge) may be imported anywhere. src/lib/catalog.ts may be imported in RSC or Route Handlers. src/db/index.ts may only be imported server-side. No leaf component imports @/db from a "use client" file — build would throw RSC boundary.

5.2 Directory Map (with Counts)

src/app/** (43 pages: 35 static + 8 dynamic — _not-found, robots, sitemap + 3 ƒ API routes [health,applications,calculator] + 5 ƒ pages [authors/[authorSlug], learn/[slug], manufacturers/[slug], states/[state], debug-error-probe] + 35 static content pages)
├── layout.tsx (fonts + metadataBase + SiteHeader/Footer)
├── globals.css (@theme sole source)
├── page.tsx (~500 lines, editorial homepage)
├── sitemap.ts / robots.ts / not-found.tsx
├── api/{health,applications,calculator}/route.ts (3× force-dynamic)
├── get-started/page.tsx + calculator/page.tsx
├── modular-home-financing/** (cost, rates, down-payment, with-land/without-land, loan-options/{fha,va,usda,construction-loan}, manufacturers, states, ...)
├── compare/{fha-vs-conventional-prefab, prefab-vs-site-built-costs, modular-vs-manufactured-financing}
├── construction-loans/{fha,va,usda} + learn/[slug] + authors/[authorSlug] + glossary + resources + financing/mortgage/adu-financing/tiny-home-financing

src/components/ (9 files, 5 client leaves + error boundary = 6 use-client)
├── ui.tsx (primitives — allowed everywhere)
├── site-header.tsx ("use client") ← fixed h-16 md:h-20 always-light frosted bar bg-background/80 backdrop-blur-lg border-border/50 (pass 3 removed transparent hero, pass-7 md:h-20 + md:flex gap-8), NAV 4 + MORE 2
├── site-footer.tsx (LinkedInIcon local SVG)
├── page-shell.tsx (Breadcrumbs + PageHero + GuideView — interior heroes must use this)
├── prequal-form.tsx ("use client") ← 13-field funnel
├── learn-explorer.tsx ("use client") ← learn hub search/filter/featured/tools/newsletter
├── reveal.tsx ("use client") ← home intro scroll-reveal
├── calculator-app.tsx ("use client")
└── guide-screen.tsx (renderer via guides.ts + markdown.tsx)

src/data/ (4 JSON → 152 sitemap locs after projection)
├── articles.json (553 lines, 23 articles)
├── manufacturers.json (912 lines, 40)
├── states.json (1069 lines, 50)
└── glossary.json (237 lines, 59)

src/db/ (2 files)
├── schema.ts (8 pgTables, ~130 lines)
└── index.ts (~20 lines, singleton)

src/lib/ (7 domains + 3 co-located *.test.ts)
├── catalog.ts (180 lines) ← typed JSON re-export
├── lenders.ts (120 lines) ← LENDER_SEEDS 8 + LOAN_PRODUCT_SEEDS 5
├── ensure-seeded.ts (80 lines) ← idempotent projection
├── calculator.ts (90 lines) ← PMI 0.65% + 1.15×
├── matching.ts (130 lines) ← scoring + validation
├── rate-limit.ts (25 lines) ← Map buckets
├── guides.ts + markdown.tsx
├── calculator.test.ts (11 tests)
├── matching.test.ts (13 tests)
├── rate-limit.test.ts (9 tests)
└── markdown.test.ts (8 tests)

src/scripts/ (3 lifecycle, all local-guarded)
├── local-db.ts (isLocalDatabaseUrl / assertLocalDatabase)
├── migrate.ts (drizzle-orm migrator, ./drizzle)
├── seed.ts (ensureSeeded wrapper)
└── reset.ts (DROP SCHEMA public,drizzle CASCADE + extensions)

drizzle/ (0000_amusing_thena.sql ~200 lines, 0001_sharp_stick.sql 1 line, meta/_journal.json idx 0,1)
e2e/ (121 per project — 103 declarations + data-driven loops — --list 122→121, `parity.spec.ts` pins H4/OOM + parity + pass-5/7 live-source pins + pass-4 source-exact hero/guide-hero pins)
├── smoke.spec.ts (8) — home/nav/footer, get-started, calculator, health, 404, axe critical, security headers
├── seo.spec.ts (16) — sitemap + robots + title/OG + 11 source title-pattern pins
├── funnel.spec.ts (5) — POST 400/200, x-forwarded-for isolation, burst 429, DB-outage 500
├── assets.spec.ts (19 runtime — 14 image × 200 + 3 broken-img + 2 alias)
└── parity.spec.ts (73 — H4/OOM regression + visual-parity pins + pass-3/4/5/7 live-source pins)

Counts proven: grep -r "'use client'" src --include="*.tsx" | wc -l → 6 islands (site-header, prequal-form, calculator-app, learn-explorer, reveal, error.tsx). find src/components -name "*.tsx" | wc -l → 9. find src -name "*.test.ts" | wc -l → 4 (calculator 11 + matching 13 + rate-limit 9 + markdown 8 = 41). npx playwright test --list --project=chromium → 121 per project (--list shows 122 listed but 121 executed; 103 decl). wc -l src/data/* → 2771.

5.3 Client vs. Server Component Decision Tree

Need useState / useEffect / onClick / browser API ?
├── Yes → "use client" leaf (site-header, prequal-form, calculator-app only). 
│         Never import a Server Component into it — extract shared UI to a leaf.
│         Example: site-header.tsx useId + useEffect(scroll passive) + useEffect(body overflow) + useState(prevPathname) pattern.
└── No  → Server Component (default). Direct db / ensureSeeded() / catalog reads allowed.
         Example: page.tsx, modular-home-financing/page.tsx, page-shell.tsx:PageHero, guide-screen.tsx, layout.tsx.

Need DB ? → Route Handler with export const dynamic = "force-dynamic" (applications, health, calculator).
           Never add export const revalidate to a seeded page without understanding — it would stale ensureSeeded().

5.4 CTA & Layout Primitives

6. Custom Hooks Deep Dive

There is no src/hooks/ folder in this repo. That's intentional. Hooks live inlined in the two "use client" components that need them. This section documents those inlined patterns so you don't extract them prematurely or miss cleanup.

6.1 Header Scroll + Drawer (src/components/site-header.tsx)

// src/components/site-header.tsx — Patterns: useId (a11y), adjust-during-render (no effect), passive scroll, body-lock cleanup

"use client";
import { useEffect, useId, useState } from "react";
import { usePathname } from "next/navigation";

export function SiteHeader() {
  const pathname = usePathname();
  const [open, setOpen] = useState(false);
  const [moreOpen, setMoreOpen] = useState(false);
  const [scrolled, setScrolled] = useState(false);
  const menuId = useId(); // a11y: aria-controls={menuId} on mobile button → div#menuId

  // 1) Transparent over dark hero only on "/" until scroll>12px (modfii.com parity)
  const overDarkHero = pathname === "/" && !scrolled;

  // 2) Close menus on client-side navigation WITHOUT setState-in-effect lint
  //    React's "adjust state during render" pattern — NOT useEffect(() => setOpen(false), [pathname])
  const [prevPathname, setPrevPathname] = useState(pathname);
  if (prevPathname !== pathname) {
    setPrevPathname(pathname);
    setOpen(false);
    setMoreOpen(false);
  }

  // 3) Passive scroll listener — never block main thread
  useEffect(() => {
    const onScroll = () => setScrolled(window.scrollY > 12);
    onScroll();
    window.addEventListener("scroll", onScroll, { passive: true }); // passive:true — WHY: scrolling must stay 60fps
    return () => window.removeEventListener("scroll", onScroll);
  }, []);

  // 4) Body overflow lock — must cleanup or page stays locked after HMR/unmount
  useEffect(() => {
    document.body.style.overflow = open ? "hidden" : "";
    return () => { document.body.style.overflow = ""; };
  }, [open]);

  // ... header renders with fixed inset-x-0 top-0 z-50 backdrop-blur-lg
}

Why each detail matters:

• passive:true — prevents scroll blocking; Chrome will warn if omitted. Don't add { passive:false } here.
• adjust-during-render (not useEffect) — eslint-plugin-react-hooks/exhaustive-deps + setState-in-effect would otherwise trigger cascading-renders lint (101aec3 fixed this exact lint error via this pattern — see §12).
• useId() — stable aria-controls for mobile id={menuId}; don't use Math.random().
• body overflow cleanup — returning "" in cleanup prevents the drawer from leaving overflow:hidden after open toggles or component unmounts (test manually or via Playwright moreOpen click).

SSR safety: All window access is inside useEffect (never during render). Don't move window.scrollY to render scope — it would SSR-break.

6.2 Link vs. Button Navigation

site-header.tsx uses <Link href={item.href}> for nav and ButtonLink (which is <Link>) for Get Started. Don't use <a href> — it bypasses Next App Router client nav. Don't use router.push for static nav links.

6.3 When to Extract a Hook

Only extract when a third consumer appears. If you add a useScrollY(threshold) or useBodyLock(open) hook, it must preserve passive:true and the "" cleanup contract. Until then, keep them inlined — premature abstraction hides the 12px threshold.

7. Content Management & Data Ingestion

7.1 Where Content Lives (Source of Truth)

Counts proven: python3 -c "len(json.load(open(...)))" + psql count(*) after db:seed → 8/40/50/23/59/5 (see PAD §4.2). articles.slug is varchar(160) for long editorial slugs; manufacturers.founded migrated 8→32 in 0001_sharp_stick.sql.

7.2 The Ingestion Pipeline (Projection, Not CMS)

src/data/*.json  ─┐
                  ├─► src/lib/catalog.ts (typed re-export, priceFloor/categorize, authors/AUTHOR_BIOS, authorSlug())
src/lib/lenders.ts┘         │
                            ▼
               src/lib/ensure-seeded.ts (global promise + count(lenders)>0 + onConflictDoNothing per slug/term)
                            │ idempotent, auto-runs in GET /api/health + POST /api/applications
                            ▼
               PostgreSQL 17 (drizzle pgTable, 8 tables, drizzle(pool) via __arenaNextJsPostgresqlPool)
                            │ onConflictDoNothing per unique slug/term
                            ▼
               src/app/** RSC + Route Handlers (read via catalog helpers: getManufacturer/getState/getArticle + drizzle(eq))

Why not import.meta.glob? Next.js App Router doesn't need Vite glob — catalog.ts is a typed import ... from "@/data/*.json" (with tsconfig resolveJsonModule:true) + computed category/letter. Glob would hide the priceFloor/categorize logic and break sitemap.ts's articles.map(article → /learn/${article.slug}) derivation.

7.3 How to Add Content (Procedure)

Add a manufacturer:

1. Edit src/data/manufacturers.json — append { slug, name, description, headquarters, founded, priceRange, homeTypes, features } (slug varchar(80) unique, no /).
2. Run npm run db:seed (idempotent) — manufacturers onConflictDoNothing({ target: slug }) will insert only the new row.
3. If manufacturing has been made more intricate, vary the articles and the glossary to directly mirror crafted / spelled.

Add a state / article / glossary term: Same — edit the JSON, npm run db:seed. Articles require authorName/authorRole → catalog.ts auto-derives authors + authorSlug; add to AUTHOR_BIOS if you want a custom bio (else generic).

Add a lender: Edit src/lib/lenders.ts LENDER_SEEDS, then npm run db:seed. LENDER_SEEDS 8 becomes 9 — E2E still expects lenders 8 in psql count(*) guard? No — assets.spec.ts doesn't pin lender count; only psql count(*) in PAD probes does. Update the probe expectation if you add.

Add a loan product: Same lenders.ts:LOAN_PRODUCT_SEEDS.

Rename a slug: You must add a redirect in next.config.ts:redirects() (see §3.3) and pin it in e2e/assets.spec.ts — build validates redirects but won't catch missing ones.

7.4 Locked Arrays & Regression Guards

8. Accessibility (WCAG AAA) Implementation

Contrast table — all pairs AAA except muted secondary (AA large-text only):

Focus ring (AAA):

/* src/app/globals.css @layer base — do not touch */
:focus-visible { outline: 2px solid var(--color-ring); outline-offset: 3px; }

ring is primary 155 45% 28% (dark forest), visible on background and card (both cream). Never override per-component.

Skip-to-content: Not yet implemented — add <a href="#main" class="sr-only focus:not-sr-only">Skip to content</a> at layout.tsx top and main id="main" when you touch the layout. Current e2e axe-core runs include("main") — it would still pass without the link but keyboard users need it.

prefers-reduced-motion:

@media(prefers-reduced-motion:reduce){
  html{scroll-behavior:auto}
  *,*::before,*::after{animation-duration:.01ms!important;transition-duration:.01ms!important}
}

Verified via globals.css — every transition-colors duration-300 (header) collapses to 0.01ms when user prefers reduced motion.

Touch targets: Mobile site-header button h-10 w-10 (40px), NAV links px-3 py-3 on mobile (≥44px height). Don't shrink.

ARIA per component:

Axe proof: e2e/smoke.spec.ts: AxeBuilder(include:"main").analyze().filter(impact==="critical") → [] — critical violations blocked on main.

9. Anti-Patterns & Common Bugs

Each entry: Symptom → Root cause → Fix → How to prevent recurrence (test/guard). Severity: CRITICAL (data loss/auth bypass) / HIGH (prod 404/500) / MEDIUM ( UX / contract) / LOW (tech debt).

#01 — Missing Hero Images (404, photo-less homepage) [HIGH]

• Symptom: / renders without photos; green band shows raw alt text. Six images 404.
• Root: public/images/{hero-prefab,green-home,interior-living,adu-backyard,tiny-home}.jpg + brand/og-image.jpg were not committed; src/app/page.tsx + page-shell.tsx:PageHero referenced them.
• Fix: c74dd7e committed 6 images + og-image.jpg; adopted modfii-logo-icon.svg canonical.
• Guard: e2e/assets.spec.ts — 14 request.get(src) → 200 (heroes/OG + 5 public/brand/wordmarks/*.png + 3 public/images/avatars/*.jpg) + no broken <img> (naturalWidth===0) on /, /adu-financing, /tiny-home-financing; build would not catch it (images are static).

#02 — Source-Parity Compare Aliases 404 [HIGH]

• Symptom: modfii.com footer links /compare/fha-vs-conventional + /compare/prefab-vs-site-built 404'd; clone only shipped -prefab / -costs variants.
• Root: next.config.ts:redirects() missing 2 entries.
• Fix: Added permanent:true aliases: fha-vs-conventional → fha-vs-conventional-prefab, prefab-vs-site-built → prefab-vs-site-built-costs.
• Guard: e2e/assets.spec.ts request.get(alias,{maxRedirects:5}) → 200; build validates redirect syntax.

#03 — Second Pool → HMR EMFILE / Auth Leak [CRITICAL]

• Symptom: EMFILE: too many open files in dev HMR; or two Pool configs diverge (one 5434, one 5432 legacy).
• Root: new Pool() outside src/db/index.ts.
• Fix: Singleton via globalThis.__arenaNextJsPostgresqlPool in src/db/index.ts; rg "new Pool" must return single hit.
• Guard: Grep guard + drizzle.config.* both 5434; local-db.ts refuses non-local.

#04 — setState in Effect Lints react-hooks/set-state-in-effect [MEDIUM]

• Symptom: npm run lint failed 101aec3-era: header menus were reset via useEffect(() => setOpen(false), [pathname]) → cascading renders.
• Root: ESLint core-web-vitals flags it.
• Fix: 4d1e6ad — adjust state during render: if(prevPathname!==pathname){ setPrevPathname(pathname); setOpen(false); setMoreOpen(false); } in site-header.tsx.
• Guard: npm run lint 0/0; lint error would block PR.

#05 — .env Committed with Real Secrets (d572d73) [CRITICAL]

• Symptom: BETTER_AUTH_SECRET + CRON_SECRET visible via git show d572d73:.env.
• Root: .env was tracked before .gitignore rule; ec11541 later untracked it (git rm --cached .env).
• Fix: Rotate secrets on deploy; current dev .env has fresh ec16d809a08c91d24dbfdab7e7be4a99 (CRON_SECRET).
• Guard: .gitignore now covers .env, bak.env, env.tgz, ssh-key.txt; git log --all -p -- .env would resurrect old value — run filter-repo/BFG to scrub if deploy used it as prod.

#06 — Direct PG Hand-Edit Clobbered on Fresh Seed [MEDIUM]

• Symptom: Hand-edited lenders row via psql UPDATE vanished after docker compose down -v && db:setup.
• Root: DB is projection; file corpus is source of truth.
• Fix: Edit src/data/*.json + src/lib/lenders.ts, then npm run db:seed.
• Guard: Documented in AGENTS.md + CLAUDE.md + this SKILL §5 Layer 0; ensureSeeded overwrites on empty, not on populated (so non-empty is safe, but fresh volume resets).

#07 — tailwind.config.* Drift (v3 vs v4 CSS-First) [MEDIUM]

• Symptom: Arbitrary text-[13px] + tailwind.config.js reintroduced tokens in two places.
• Root: Copy-paste from v3 templates.
• Fix: Delete tailwind.config.*; extend only @theme in globals.css.
• Guard: ls tailwind.config* must be empty; PR review rejects arbitrary values.

#08 — as any / @ts-ignore Erases Strict Guards [MEDIUM]

• Symptom: tsc passes but runtime breaks on ApplicationInput shape.
• Root: as any to silence parseBody union.
• Fix: unknown + asString(record.field) + typeof === "string" narrowing; as const on LOAN_PRODUCT_SEEDS.
• Guard: typecheck + PR rule as any → Never; grep -rn "as any" src must be 0.

#09 — Server→Client Import Boundary Violation [HIGH]

• Symptom: next build throws Cannot import Server Component into Client Component.
• Root: import { PageHero } from "@/components/page-shell" from "use client" file (or import { db } from "@/db" in client).
• Fix: Extract shared UI to a leaf with no server import; keep util: cn etc. in ui.tsx which stays boundary-clean.
• Guard: build is the gate — it fails fast.

#10 — In-Memory Rate Limiter Under-Limits on Multi-Instance [HIGH]

• Symptom: Burst not throttled after horizontal scale (each instance has its own Map).
• Root: src/lib/rate-limit.ts is in-memory by design for single deploy.
• Fix: Migrate to Redis/Upstash before scaling; document ENV FEATURE_RATELIMIT=redis when introduced.
• Guard: funnel.spec.ts uses x-forwarded-for: burst-* isolation; test would flip to 2-instance Redis test when scaling.

#11 — Broken <img> Without <Image> Priority [LOW]

• Symptom: LCP image (hero-prefab.jpg) lazy-loaded, poor Web Vitals.
• Root: <img> tag instead of next/image.
• Fix: Use next/image even with unoptimized:true — still gives priority, sizes, alt enforcement.
• Guard: assets.spec.ts naturalWidth===0 check on key pages.

#12 — N+1 Lender Lookup at Scale [LOW]

• Symptom: POST /api/applications fetches lender by eq(slug) in a loop (4× today). If match count grew, N+1.
• Root: Loop pattern fine at 4, wasteful at 40.
• Fix: Batch via whereIn(lenders.slug, matchSlugs) when fanout grows; current 4 is explicitly acceptable per CLAUDE.md.
• Guard: Code comment in §15 pattern notes the scaling point.

#13 — DISABLE_IMAGE_OPTIMIZER Without turbo.json [LOW]

• Symptom: Sandbox doc claims must stay in turbo.json:globalEnv but turbo.json doesn't exist.
• Root: Monorepo scandihaven pattern copied into single-app doc.
• Fix: Either add turbo.json when Turborepo introduced or drop the claim.
• Guard: Verify at PAD update time.

#14 — Manual src/lib/catalog.ts Drift (Stale authorSlug / letter) [MEDIUM]

• Symptom: New articles.json entry with authorName: "Jane Doe" creates authorSlug: jane-doe but glossaryTerms.letter still hardcoded letter: "J" vs derived term.charAt(0) mismatch.
• Root: ensure-seeded.ts derives letter but older manual DB edit wrote literal.
• Fix: Never hand-edit PG; trust letter: item.term.charAt(0).toUpperCase() in ensure-seeded.ts.
• Guard: psql select distinct letter from glossary_terms must equal term[0] upper.

10. Debugging Guide

Symptom → Root → Fix. Every entry was encountered in this repo's history (see §12/§C).

Triage flow (when unknown):

docker compose logs -f postgres      # init extension notices + health
curl -s http://localhost:3002/api/health | jq  # readiness + ensureSeeded probe
npm run typecheck                     # fastest regression signal
npm run build 2>&1 | tail -n 100      # RSC boundary + redirect validation
sudo docker exec home_financing_postgres psql -U home_financing_user -d home_financing_dev -c "select count(*) from lenders;"

11. Pre-Ship Checklist

Run in order — earlier gates catch cheaper failures. Every push must pass. Documented in AGENTS.md, CLAUDE.md, README.md gate table.

# 1 — DB is the projection, not the authoring store. One-shot, idempotent, local-guarded.
npm run db:setup
# → [db] migrations applied (0000+0001) + [db] seed complete (8/40/50/23/59/5)
# Granular: npm run db:generate / db:migrate / db:seed / db:reset

# 2 — Lint (flat config, core-web-vitals, skills+infrastructure excluded)
npm run lint
# → 0 errors / 0 warnings
npm run lint:fix   # auto-fix when dirty

# 3 — Type (strict, skills excluded — z-ai-web-dev-sdk not installed)
npm run typecheck
# → 0 errors — no any, no ts-ignore

# 4 — Unit (pure domains only; DB paths stay under Playwright)
npm run test
# → 41/41 vitest (calculator 11 + matching 13 + rate-limit 9 + markdown 8 — incl. H4/OOM regression)
npm run test:watch      # watch
npm run test:coverage   # when wired

# 5 — Build (validates redirects, RSC boundaries, skills excluded)
npm run build
# → ✓ Compiled successfully in ~538ms
# → ✓ Generating static pages using 3 workers (43/43) in ~957ms
# → Routes: ○ 35 static + ƒ 8 dynamic

# 6 — E2E (prod next start on 3002, reuseExistingServer, chromium; valid-payload needs DB)
npm run e2e             # chromium 121/121 per project (103 declarations + data-driven loops — --list 122→121; 120/121 DB-less)
npm run e2e:all         # chromium + webkit

# 7 — Readiness + content surfaces
curl -s http://localhost:3002/api/health | jq
# → { "ok": true, "status": "ok", "db": true }

curl -s http://localhost:3002/sitemap.xml | grep -o "<loc>" | wc -l
# → 152  (39 STATIC + 23 learn + 50 states + 40 manufacturers)

# 8 — Manual asset/alias probe (what assets.spec.ts does automatically)
for p in /images/hero-prefab.jpg /images/green-home.jpg /images/interior-living.jpg /images/adu-backyard.jpg /images/tiny-home.jpg /brand/og-image.jpg; do echo "$p $(curl -s -o /dev/null -w "%{http_code}" http://localhost:3002$p)"; done
# → 6× 200
curl -I http://localhost:3002/compare/fha-vs-conventional       # 308 → /compare/fha-vs-conventional-prefab
curl -I http://localhost:3002/compare/prefab-vs-site-built      # 308 → /compare/prefab-vs-site-built-costs

Additional gates (run mentally or via script):

• Every new route has loading.tsx/error.tsx or an ADR explaining why not
• Rename of any slug has a next.config.ts:redirects() entry (permanent) + assets.spec.ts pin
• NEXT_PUBLIC_SITE_URL + BETTER_AUTH_URL on deploy = https://modfii.jesspete.shop
• grep -rn "as any" src → empty; grep -rn "new Pool" src → single hit in src/db/index.ts
• ls tailwind.config* → absent; ls public/images/*.jpg → 5 + brand/og-image.jpg present
• BETTER_AUTH_SECRET/CRON_SECRET not committed (git log --all -p -- .env should not show fresh values)
• Lighthouse/CWV + keyboard focus-visible + aria-label on icon buttons don't regress (axe critical: [] on main)

12. Lessons Learnt & How to Avoid Them

Each lesson traces to a specific code change or test. Numbered LL-01…

Sprint 1 — Bootstrap

LL-01. File-backed projection beats DB-as-source for editorial.
Content diffed in src/data/*.json survives docker compose down -v and PR review. ensureSeeded() idempotent via globalThis.__modfiiSeedPromise + count>0 + onConflictDoNothing. Avoided: hand-editing PG rows that vanish on fresh volume. Ref: src/lib/ensure-seeded.ts, AGENTS.md never-do #2.

LL-02. Pool singleton must be globalThis or HMR leaks Pool.
globalThis.__arenaNextJsPostgresqlPool prevents EMFILE on HMR. Never new Pool() inline — single import from @/db only. Fix: src/db/index.ts singleton + rg guard. Test: build would throw if second Pool leaked handles.

LL-03. CSP/HSTS/DENY were not optional — auth later.
Initial probe showed curl -v /api/health emitting content-security-policy, strict-transport-security, x-frame-options DENY. Don't weaken them when adding Stripe/Cloudflare scripts — extend connect-src / script-src narrowly. Ref: src/app/layout.tsx inherits Next's defaults + proxy headers.

LL-04. Keep drizzle.config.ts + .json in sync.
drizzle-kit generate writes via whichever config is resolved; mismatched 5434 vs 5432 once gave ECONNREFUSED :5432. Runtime DATABASE_URL still wins, but keep both 5434/home_financing_dev. Lesson: diff both after db:generate.

Sprint 2 — Security Remediation (2026-09-11 Incidents)

LL-05. .env with real secrets was tracked (d572d73).
BETTER_AUTH_SECRET + CRON_SECRET were committed before .gitignore added .env. ec11541 untracked (git rm --cached .env). Rotate both — they remain in git show d572d73:.env. Don't git add -f .env ever. Guard: grep "git show" .git/logs.

LL-06. skills/** must be excluded from typecheck/lint/build.
Operator-managed skills/ vendored JS br

Truncated - read the full file at https://github.com/nordeim/personalized-tutor-app/blob/ff8c5bdf5ab5c82bc84f41bba79731461824fbcd/skills/nextjs-postgresql-single-app/SKILL.md.