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

Completion Means Working, Not Compiling

Before marking ANY phase complete, verify:

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

The Lesson

• ✅ 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

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

When to Use Multi-Agent

✅ Good for parallel work:

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

• 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.

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

• [ ] 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.

Phase 2: Backend Implementation (SEQUENTIAL or CAREFUL PARALLEL)

Option A: Single Backend Agent (Recommended)

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

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

• Test CRUD operations — Create, read, update, delete
• Verify queries return data — Not empty arrays
• Check mutations persist — Data survives refresh
• Test auth guards — Protected functions reject unauthorized
• 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:

• Interactive states work — Buttons trigger onClick
• Form components submit — Not just styled divs
• Loading/error states exist
• Accessibility basics — Labels, ARIA, keyboard nav
• 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.

• Read schema, types, contracts — don't modify
• Use existing components — don't recreate
• Write to assigned directories only

• [ ] 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

• // 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)

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

Auth Flow:

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

• [ ] 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