web-architecture

name	web-architecture
description	Multi-agent orchestration for complex TypeScript/Next.js/Convex projects. Phased builds, functional verification, the full playbook for delegating to sub-agents without chaos.

Web Architecture

Multi-agent development workflow for TypeScript/Next.js/Convex projects.

Born from: 29 agents, 50K lines, 212 errors, 1 hard lesson

---

⚠️ SUB-AGENT POLICY (READ FIRST)

No Timeouts

Sub-agents MUST run without timeout limits. A 10-minute timeout that cuts off an agent mid-implementation leaves broken, partial code. Let agents finish.

Completion Means Working, Not Compiling

"Build passes" is necessary but NOT sufficient.

Before marking ANY phase complete, verify:

1. Functions actually work — Call them, verify data flows
2. UI actually renders data — Not just loading spinners forever
3. User flows complete end-to-end — Click through, verify state changes persist
4. Error states are handled — Not just happy path

The Lesson

An agent produced 15K lines of "working" code that:

• ✅ Compiled with zero TypeScript errors
• ✅ Passed bun run build
• ❌ Had ZERO actual functionality
• ❌ All data was mocked or hardcoded
• ❌ Every button was a no-op

Self-grade: 5/10 — A prototype, not a product.

---

The Core Lesson

Single agent with full context > Many agents with partial context

29 parallel agents wrote 50K lines of code that didn't compile. Why?

• No schema coordination → duplicate table definitions
• No type contracts → frontend expected user.role, backend returned profile.plan
• No initialization → npx convex dev never ran, no generated types
• No integration checkpoints → errors discovered only at the end

The fix: One agent with full context rewrote the entire Convex backend in 11 minutes.

---

When to Use Multi-Agent

✅ Good for parallel work:

• Marketing pages (after design system exists)
• Documentation files (independent)
• Isolated features with clear contracts

❌ Bad for parallel work:

• Schema design (needs single owner)
• Core type definitions (must be shared)
• Interconnected backend functions
• Component library (needs consistency)

---

The Workflow

Phase 0: Bootstrap (SEQUENTIAL — One Agent)

Must complete before spawning ANY other agents.

1. Initialize project structure
2. Initialize Convex: npx convex dev --once
3. Create complete schema.ts (ALL tables)
4. Run npx convex dev to generate types
5. Create CONTRACTS.md (all data shapes)
6. Create shared types in lib/types.ts
7. Verify: bun run build passes

Deliverables:

• convex/schema.ts — Complete, no TODOs
• convex/_generated/ — Types generated
• CONTRACTS.md — API shapes documented
• lib/types.ts — Shared frontend types
• bun run build — Passes with 0 errors

---

Phase 1: Foundation Documents (CAN BE PARALLEL)

Only spawn AFTER Phase 0 completes.

Agent	Output	Dependencies
Tech Requirements	TECH-REQ.md	None
Compliance	COMPLIANCE.md	None
Design Principles	DESIGN.md	None
Coding Standards	STANDARDS.md	None

Rule: These agents READ the schema. They do NOT modify it.

---

Phase 2: Backend Implementation (SEQUENTIAL or CAREFUL PARALLEL)

Option A: Single Backend Agent (Recommended)

• One agent implements all Convex functions
• Consistent patterns, no conflicts

Option B: Parallel with File Locks

• Each agent owns specific files
• NO shared file writes
• Must reference CONTRACTS.md

Functional Requirements:

1. Test CRUD operations — Create, read, update, delete
2. Verify queries return data — Not empty arrays
3. Check mutations persist — Data survives refresh
4. Test auth guards — Protected functions reject unauthorized
5. Verify indexes work — Queries return correct filtered data

---

Phase 3: Component Library (SEQUENTIAL)

Single agent builds the component library.

Why? Components reference each other. Parallel work creates duplicate components with different APIs.

Functional Requirements:

1. Interactive states work — Buttons trigger onClick
2. Form components submit — Not just styled divs
3. Loading/error states exist
4. Accessibility basics — Labels, ARIA, keyboard nav
5. Consistent API — All components follow same patterns

---

Phase 4: Features & Pages (CAN BE PARALLEL)

Now safe to parallelize because schema is locked, types exist, components exist.

Agent	Scope	Can Modify
Admin Suite	/app/(admin)/**	Own files only
Support Portal	/app/(support)/**	Own files only
Marketing Pages	/app/(marketing)/**	Own files only
User Flows	/app/(app)/**	Own files only

Rules:

1. Read schema, types, contracts — don't modify
2. Use existing components — don't recreate
3. Write to assigned directories only

Functional Requirements:

• Page loads without console errors
• Data appears (not mock/placeholder)
• Forms submit and persist data
• Can complete full user flow (create → view → edit → delete)
• Refresh preserves state

Red flags (NOT complete):

• // TODO comments in business logic
• Hardcoded arrays instead of useQuery
• onClick handlers that console.log instead of mutate
• "Coming soon" placeholders in core features

---

Phase 5: Integration & QA (SEQUENTIAL)

1. bun run build (must pass)
2. npx convex dev --once (must pass)
3. Generate sitemap from routes
4. Route crawl & 404 check
5. Browser smoke test (all routes return 200)
6. End-to-end flow verification

E2E Verification Checklist:

Auth Flow:

• Sign up creates user in database
• Sign in authenticates and redirects
• Protected routes redirect to sign-in

Core CRUD Flow:

• Create: Form submits → record appears
• Read: List shows real data
• Update: Edit form saves → changes persist
• Delete: Remove action → record gone

---

Directory Structure

project/
├── convex/
│   ├── schema.ts            # 🔒 Phase 0 only
│   ├── _generated/          # 🔒 Auto-generated
│   └── [domain].ts
├── lib/
│   ├── types.ts             # 🔒 Phase 0 only
│   └── utils.ts
├── components/
│   ├── ui/                  # Component library agent
│   └── [domain]/            # Feature agents
├── app/
│   ├── (admin)/             # Admin agent
│   ├── (app)/               # App agent
│   └── (marketing)/         # Marketing agents
└── CONTRACTS.md             # 🔒 Phase 0 only

🔒 = Locked after Phase 0. Agents read, don't modify.

---

Agent Spawn Order

1. Bootstrap Agent (MUST COMPLETE FIRST)
   └── schema.ts, types, contracts
   
2. Doc Agents (parallel)
   ├── TECH-REQ.md
   ├── COMPLIANCE.md
   └── DESIGN.md
   
3. Backend Agent (single)
   └── All convex/*.ts functions
   
4. Component Agent (single)
   └── All components/ui/*
   
5. Feature Agents (parallel, isolated directories)
   ├── Admin Suite
   ├── Support Portal
   ├── Marketing Pages
   └── User Flows
   
6. Integration Agent (single)
   └── Final build, fixes, QA

---

Anti-Patterns

❌ Spawn all agents at once — No coordination, duplicate work

❌ Let agents invent types — Use CONTRACTS.md, not imagination

❌ Skip Phase 0 — "We'll figure out the schema later" = disaster

❌ Parallel schema writes — One owner only

❌ Frontend before backend types — Generates type mismatches

❌ No build checkpoints — Errors compound

---

Related Files

• TECH-REQ.md — Full stack specification
• CODING-STANDARDS.md — TypeScript/React/Convex patterns
• CONTRACTS-TEMPLATE.md — API contracts template