AI Theory & Architecture for React: Contracts, Decomposition, Verification · Rubén Vega Balbás, PhD · UDIT, University of Design, Innovation and Technology

WEB ATELIER (UDIT) · Learning by doing, with theory, practice and shared reflection

AI Theory & Architecture for React: Contracts, Decomposition, Verification

Draft
By Rubén Vega Balbás, PhD 2025-01-15

URL: https://ruvebal.github.io/web-atelier-udit/lessons/en/react/ai-assisted-development-foundations/

📋 Table of Contents

“AI accelerates output. Architecture protects outcomes.”

🎯 Sprint Goal

By the end of this sprint: you can use AI as a collaborator without outsourcing understanding, by working with contracts, decomposition, and verification loops that reduce risk (bugs, security issues, accessibility regressions).

🔗 Canonical Reading (Required)

This lesson is React-focused, but it builds on the canonical methodology:

🧱 Architecture Mapping: From Classical Patterns to React

Classical idea React translation Why it matters with AI
Contracts Prop shapes, API schemas, JSDoc or types AI is “creative”; contracts limit ambiguity
Decomposition Components + hooks + modules Smaller units are easier to verify
Invariants “Always true” rules Prevents silent regressions
Observability Logs, error boundaries, devtools AI code fails in surprising ways

Minimal “Contract Stack” for Student Projects

  • Type contracts: Clear prop shapes and API response shapes (JSDoc or type checkers as needed)
  • Runtime contracts: defensive checks at boundaries (inputs, API errors)
  • Behavior contracts: tests for reducers/hooks + a few critical flows

🧪 Verification Loop (The Non-Negotiable Habit)

1) Ask AI for a plan, not code (architecture first) 2) Write or confirm contracts (types + expected behavior) 3) Generate code in small chunks 4) Run tests / lint / typecheck 5) Manual check: accessibility + edge cases 6) Document: what AI suggested and what you changed

🧠 Practical Prompts (Copy-Paste Ready)

✅ ARCHITECTURE PROMPT
"Given this feature: [describe], propose:
1) component decomposition (list components)
2) state model (UI/server/URL/shared)
3) data flow diagram (text)
4) failure modes + mitigations
Return only the plan, no code."

✅ CONTRACT PROMPT
"Write clear contracts for:
- API response shape (include error variants)
- UI state discriminated union (status + data/error)
Then list 5 invariants that must remain true."

✅ VERIFICATION PROMPT
"Review this diff for:
- security issues (XSS, token storage, unsafe HTML)
- accessibility regressions (focus, ARIA, keyboard)
- error handling gaps (loading/error/empty)
- stale closures / effect dependency issues
Return a checklist and the exact lines to inspect."

🧩 Hands-On: Apply the Method to One Feature

Pick one feature (auth, cart, search, media upload) and produce:

  • Decomposition: 5–10 components/hooks/modules (named)
  • Contracts:
    • Clear prop and API shapes (JSDoc or types as needed)
    • 3–6 invariants
  • Verification evidence:
    • at least 2 tests (hook/reducer)
    • a screenshot of your accessibility check (keyboard-only or axe)

💭 Reflection Questions (Atelier)

💭 Which part of your system is “most fragile” when AI generates code? Why?

💭 What did you verify manually that AI claimed was correct?

💭 What contract would have prevented your last bug?

🧘 Koan

“The prompt is not the program. The program is what survives contact with reality.”