Fullstack validation

Fullstack Validation

Scope

Multi-layer validation for apps that ship a frontend AND backend together (Next.js, Astro + API routes, Rails + Turbo, Django + HTMX, Remix, SvelteKit, Phoenix + LiveView, etc.). Orchestrates api-validation + web-validation in strict bottom-up order.

The Iron Law: Bottom-Up

Database / Infra (FIRST)  ← pg_isready, migrations current, seed data present
    ↓
Business Logic            ← no direct gates; surfaces via API layer
    ↓
API Endpoints             ← api-validation patterns
    ↓
Frontend UI (LAST)        ← web-validation patterns

Why: If the DB is broken, every API test fails with misleading errors. If an endpoint is broken, the frontend is untestable. Start at the foundation.

Preflight

• Data layer: DB up, migrations current, seed data loaded
• API layer: server listening on port, /health returns 2xx
• Frontend layer: dev server responding, root route returns HTML with expected marker

Execution Pattern

Every fullstack gate validates ALL THREE layers in one gate (or chains three single-layer gates with a phase_gate at the end):

# Layer 1: Data
psql "$DATABASE_URL" -c "SELECT COUNT(*) FROM items" > e2e-evidence/vgN-db-count.txt

# Layer 2: API
curl -s http://localhost:3000/api/items \
  | tee e2e-evidence/vgN-api.json | jq .

# Layer 3: Frontend
agent-browser open http://localhost:5173/items
agent-browser screenshot e2e-evidence/vgN-items-page.png

PASS Criteria Patterns

Single gate covering all layers:

• "DB has exactly 10 items seeded (count == 10)"
• "API returns array of length 10 with every item having id + title"
• "Frontend renders 10 item cards with matching titles (screenshot + DOM check)"

Verdict is PASS only if ALL three layers cite evidence.

Gate Template

<validation_gate id="VG-N" blocking="true" platform="fullstack"
                 protocol="functional-validation"
                 platform_skill="fullstack-validation"
                 verdict_by="gate-validation-discipline">
  <preflight skill="preflight">
    pg_isready && curl -sf /health && curl -sf /
  </preflight>
  <execute>
    [Layer 1: psql]
    [Layer 2: curl]
    [Layer 3: agent-browser]
  </execute>
  <capture>
    [per-layer files to e2e-evidence/vgN-*-db.txt, -api.json, -ui.png]
  </capture>
  <pass_criteria>
    DB count matches seed | API length matches DB | UI card count matches API
  </pass_criteria>
  <review>
    jq -e on API | Read tool on screenshot | cross-check counts across layers
  </review>
  <verdict>
    PASS → next | FAIL → diagnose which layer failed → fix root, re-run from DB
  </verdict>
  <mock_guard skill="no-mocking-validation-gates">
    Real DB, real API, real browser. No MSW, no supertest, no jest.mock.
  </mock_guard>
</validation_gate>

Diagnosis Matrix (when a fullstack gate fails)

Fails at	Likely root cause	Fix
DB layer	Seed didn't run; migration regression	Re-run migrations; reseed; verify schema
API layer (DB PASS)	Route handler bug; auth middleware; serialization	Check API logs; test route directly with curl
UI layer (API PASS)	State mismatch; hydration; route auth gate	Check browser console + network; check auth cookie
All layers (intermittent)	Race condition or flakiness	Add condition-based-waiting; don't sleep, poll

Phase Hierarchy Integration

When phase hierarchy is used, dedicate one phase per layer:

Phase 01: data-layer      (gates: DB schema + RLS + seed)
Phase 02: api-layer       (gates: endpoints + auth + errors)
Phase 03: frontend        (gates: route + form + responsive + a11y)

Each phase gate runs regression against all prior layers — verification-before-completion + gate-validation-discipline.

Rules

1. Always bottom-up — DB first, UI last
2. Always validate each layer independently BEFORE the integration gate
3. Always cite evidence from all three layers in a cross-layer PASS verdict
4. Always run preflight on all three layers — not just the layer you're testing

Security Policy

Fullstack evidence combines DB dumps, API responses, and screenshots. All may contain PII. Store in e2e-evidence/ (gitignored).