Terminal 1 (Backend)

Project 33: “The Full Stack Scaffolder” — Rapid Prototyping

Attribute	Value
File	`KIRO_CLI_LEARNING_PROJECTS.md`
Main Programming Language	React / Node.js
Coolness Level	Level 3: Genuinely Clever
Difficulty	Level 2: Intermediate
Knowledge Area	Rapid Prototyping

What you’ll build: From empty directory to working full stack app in one session.

Why it teaches Agency: The planner and executor must collaborate.

Success criteria:

App runs locally with a working UI and API.

Real World Outcome

You’ll have a Kiro workflow that transforms a high-level specification into a working full-stack application with:

Backend API (Express/Fastify with TypeScript)
Frontend UI (React/Next.js with Tailwind CSS)
Database (PostgreSQL with Prisma ORM)
Authentication (JWT or session-based)
Development tooling (ESLint, Prettier, TypeScript, tests)
Deployment readiness (Dockerfiles, environment configs)

Example Session:

$ mkdir task-manager-app && cd task-manager-app

$ kiro "Build a full-stack task manager app with user authentication, task CRUD, and tagging. Use React, Node.js, PostgreSQL."

🏗️ Full Stack Scaffolder - Planning Phase
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Requirements Analysis:
├─ Frontend: React with TypeScript
├─ Backend: Node.js + Express + TypeScript
├─ Database: PostgreSQL + Prisma ORM
├─ Features: Auth, Task CRUD, Tags
└─ Estimated files: ~45 files

📐 Architecture Plan:

task-manager-app/
├── backend/
│   ├── src/
│   │   ├── routes/        (auth.ts, tasks.ts, tags.ts)
│   │   ├── middleware/    (auth.ts, validation.ts, error.ts)
│   │   ├── services/      (AuthService.ts, TaskService.ts)
│   │   ├── models/        (Prisma client)
│   │   └── server.ts
│   ├── prisma/
│   │   └── schema.prisma
│   ├── tests/
│   └── package.json
│
└── frontend/
    ├── src/
    │   ├── components/    (TaskList, TaskForm, LoginForm)
    │   ├── pages/         (Dashboard, Login, Register)
    │   ├── hooks/         (useAuth, useTasks)
    │   ├── api/           (client.ts)
    │   └── App.tsx
    ├── public/
    └── package.json

🔄 Executing Build Plan...

[1/8] Setting up backend structure...
✅ Created backend/ directory
✅ Initialized package.json with dependencies
✅ Created tsconfig.json
✅ Set up folder structure

[2/8] Installing backend dependencies...
✅ express, cors, dotenv, jsonwebtoken
✅ prisma, @prisma/client, bcrypt
✅ TypeScript, @types/* packages
✅ jest, supertest (dev dependencies)

[3/8] Configuring Prisma schema...
✅ Created prisma/schema.prisma with User, Task, Tag models
✅ Generated Prisma Client
✅ Created initial migration

model User {
  id        String   @id @default(uuid())
  email     String   @unique
  password  String
  tasks     Task[]
  createdAt DateTime @default(now())
}

model Task {
  id          String   @id @default(uuid())
  title       String
  description String?
  status      TaskStatus @default(TODO)
  userId      String
  user        User     @relation(fields: [userId], references: [id])
  tags        Tag[]
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

[4/8] Building backend API routes...
✅ POST   /api/auth/register
✅ POST   /api/auth/login
✅ GET    /api/tasks (protected)
✅ POST   /api/tasks (protected)
✅ PUT    /api/tasks/:id (protected)
✅ DELETE /api/tasks/:id (protected)
✅ GET    /api/tags (protected)

[5/8] Setting up frontend structure...
✅ Created React app with TypeScript
✅ Installed Tailwind CSS
✅ Created component structure
✅ Set up React Router

[6/8] Building frontend components...
✅ LoginForm component (email, password, validation)
✅ TaskList component (fetch, display, delete)
✅ TaskForm component (create/edit tasks)
✅ TaskCard component (status badge, tags, actions)
✅ ProtectedRoute wrapper (auth check)

[7/8] Connecting frontend to backend...
✅ API client with JWT interceptor
✅ useAuth hook (login, register, logout, token refresh)
✅ useTasks hook (CRUD operations)
✅ Environment variables (.env.local)

[8/8] Final setup...
✅ Created README.md with setup instructions
✅ Created .gitignore
✅ Created Docker Compose file (Postgres + app)
✅ Created example.env files
✅ Added npm scripts (dev, build, test)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Full Stack App Generated Successfully!

📦 Files created: 47 files
📏 Total lines of code: ~3,200 LOC

🚀 Quick Start:

# Terminal 1 (Backend)
cd backend
cp example.env .env    # Then edit DATABASE_URL
npm install
npm run db:migrate
npm run dev            # Runs on http://localhost:3001

# Terminal 2 (Frontend)
cd frontend
cp example.env .env.local
npm install
npm run dev            # Runs on http://localhost:3000

# Terminal 3 (Database)
docker-compose up postgres

🎯 Try it out:
1. Open http://localhost:3000
2. Register a new account
3. Create a task with tags
4. See it persist in PostgreSQL!

What You See:

Working full-stack app generated from a single prompt
Backend API with authentication, authorization, and CRUD endpoints
Frontend UI with login, task list, task creation, and tag filtering
Database schema with relationships (User → Tasks → Tags)
Complete development environment (hot reload, TypeScript, linting)
Production-ready patterns (error handling, validation, logging)

The Core Question You’re Answering

“How can AI coordinate multiple sub-agents to plan, architect, and implement a cohesive full-stack application without human intervention?”

This project explores multi-agent collaboration: Kiro must act as both architect (planning) and builder (executing). The planner agent creates a dependency graph (database → backend → frontend), while executor agents implement each layer. Success requires maintaining architectural coherence across all layers.

Concepts You Must Understand First

Stop and research these before coding:

Full-Stack Architecture Patterns
- What is the separation between presentation, business logic, and data layers?
- How do you design REST APIs that are easy to evolve?
- What is the role of an ORM (Prisma, TypeORM, Sequelize)?
- Book Reference: “Patterns of Enterprise Application Architecture” by Martin Fowler - Ch. 1-3
Dependency Management and Build Order
- Why must the database schema be defined before the backend?
- Why must the API routes be defined before the frontend?
- How do you handle circular dependencies (frontend ↔ backend during dev)?
- Book Reference: “Building Microservices” by Sam Newman - Ch. 4 (Integration)
Code Generation Quality
- How do you generate code that is readable, not just functional?
- What conventions should generated code follow (naming, file structure)?
- How do you avoid generating brittle code that breaks on changes?
- Book Reference: “Clean Code” by Robert C. Martin - Ch. 2-3
Testing Full-Stack Applications
- What is the difference between unit tests, integration tests, and E2E tests?
- How do you test API endpoints (mocking vs real database)?
- How do you test frontend components (React Testing Library)?
- Book Reference: “Test-Driven Development” by Kent Beck - Ch. 1-5

Questions to Guide Your Design

Before implementing, think through these:

Planning Strategy
- How will you decompose the high-level spec into tasks?
- How will you determine the build order (database → backend → frontend)?
- How will you handle missing requirements (e.g., “should we use sessions or JWT?”)?
- How will you validate the plan before executing?
Agent Coordination
- How will you split work across sub-agents (one per layer vs one per feature)?
- How will agents communicate shared context (API contracts, types)?
- How will you handle failures mid-build (rollback vs partial completion)?
- How will you parallelize independent tasks (frontend UI + backend routes)?
Code Quality
- How will you ensure generated code follows best practices?
- How will you avoid hardcoding secrets (database passwords, API keys)?
- How will you generate meaningful variable/function names (not foo, bar)?
- How will you add comments explaining non-obvious logic?
Development Experience
- How will you set up hot reload for frontend and backend?
- How will you generate helpful README with setup instructions?
- How will you create example .env files with placeholder values?
- How will you add npm scripts for common tasks (dev, test, build, deploy)?

Thinking Exercise

Exercise: Design the Build Order for a Blog Platform

Given the spec: “Build a blog platform with posts, comments, authors, and markdown rendering”

Plan the Dependency Graph:

1. Database Schema (Prisma)
   ├─ User (authors)
   ├─ Post (belongs to User)
   └─ Comment (belongs to Post and User)

2. Backend API Routes
   ├─ POST /api/auth/register
   ├─ POST /api/auth/login
   ├─ GET  /api/posts (public)
   ├─ POST /api/posts (protected, authors only)
   ├─ GET  /api/posts/:id (public)
   └─ POST /api/posts/:id/comments (protected)

3. Frontend Components
   ├─ PostList (fetches from GET /api/posts)
   ├─ PostDetail (fetches from GET /api/posts/:id, renders markdown)
   ├─ CommentSection (fetches comments, posts new comment)
   └─ AuthorDashboard (fetches user's posts, creates new post)

Questions to answer:

Which layer must be built first, and why?
Can frontend and backend be built in parallel? What’s needed for that?
How would you generate TypeScript types shared between frontend and backend?
What testing strategy would you use (unit, integration, E2E)?
How would you handle markdown rendering (server-side vs client-side)?
What security considerations exist (XSS in markdown, auth on comments)?

The Interview Questions They’ll Ask

“How would you design a multi-agent system where one agent plans and others execute? How do they communicate?”
“Explain the trade-offs between generating a monorepo vs separate repositories for frontend and backend.”
“How would you ensure generated code follows the user’s preferred conventions (tabs vs spaces, naming style)?”
“What strategies would you use to validate the generated app actually works (automated testing vs manual verification)?”
“How would you handle evolving requirements (user asks to add a feature to the generated app)?”
“Explain how you’d generate a database schema that supports future migrations without breaking existing data.”

Hints in Layers

Hint 1: Task Decomposition Strategy Break the spec into layers and features:

Infrastructure: Database, environment config, Docker
Backend Foundation: Express server, middleware, error handling
Database Models: Prisma schema, migrations
Backend Features: Auth routes → Task routes → Tag routes
Frontend Foundation: React app, routing, API client
Frontend Features: Login page → Dashboard → Task components

Hint 2: Sub-Agent Workflow Use Kiro’s subagent system:

# Planning agent
kiro plan "Generate full-stack task manager app"

# Execution agents (parallel)
kiro task "Set up backend Express server with TypeScript"
kiro task "Create Prisma schema with User, Task, Tag models"
kiro task "Build frontend React app with Tailwind"

Hint 3: Shared Type Generation Generate TypeScript types that both frontend and backend use:

// backend/src/types/api.ts
export interface Task {
  id: string;
  title: string;
  status: 'TODO' | 'IN_PROGRESS' | 'DONE';
  tags: Tag[];
}

// frontend/src/types/api.ts (copy or import from backend)
import type { Task } from '../../backend/src/types/api';

Better: Use a shared types/ package or generate from Prisma schema.

Hint 4: Validation Before Execution Before generating 47 files, validate the plan:

Show the directory structure to the user
Ask: "Should I proceed with this architecture?"
If approved → execute
If not → refine plan based on feedback

Hint 5: Incremental Verification After each layer, validate it works:

Generate database schema → Run `prisma generate` → Check for errors
Generate backend routes → Run `npm run build` → Check TypeScript errors
Generate frontend → Run `npm run build` → Check for compilation errors
Start servers → Run `curl http://localhost:3001/health` → Verify 200 OK

Books That Will Help

Topic	Book	Chapter
Full-stack architecture	“Patterns of Enterprise Application Architecture” by Martin Fowler	Ch. 1-3 (Layering)
REST API design	“RESTful Web APIs” by Leonard Richardson	Ch. 3-5 (Resource Design)
React patterns	“React Design Patterns and Best Practices” by Michele Bertoli	Ch. 1-4
TypeScript best practices	“Effective TypeScript” by Dan Vanderkam	Ch. 1-3 (Types)
Testing strategies	“Test-Driven Development” by Kent Beck	Ch. 1-5
Multi-agent systems	“Building Microservices” by Sam Newman	Ch. 4 (Integration)

Common Pitfalls & Debugging

Problem 1: “Generated frontend tries to call backend API before backend is running”

Why: Frontend hardcodes API URL without checking if backend is reachable
Fix: Add health check endpoint and retry logic in API client
Quick test: curl http://localhost:3001/health should return 200 OK

Problem 2: “Prisma migration fails with ‘relation does not exist’“

Why: Running migrations before database is created
Fix: Ensure Docker Compose starts Postgres before running prisma migrate
Quick test: docker ps shows postgres container, then npm run db:migrate

Problem 3: “Frontend builds but shows blank page (no errors in console)”

Why: React Router routes not configured correctly, or missing index.html
Fix: Check App.tsx has <BrowserRouter> and routes defined
Quick test: Open browser console, check for 404s or router errors

Problem 4: “Generated code has inconsistent formatting (mix of tabs and spaces)”

Why: Different code generators use different formatting
Fix: Run Prettier on all generated files: npx prettier --write "**/*.{ts,tsx}"
Quick test: git diff should show consistent indentation

Problem 5: “Backend API returns 401 Unauthorized for all protected routes”

Why: JWT secret not set in .env, or frontend not sending token
Fix: Check .env has JWT_SECRET, check frontend sets Authorization: Bearer <token>
Quick test: curl -H "Authorization: Bearer <token>" http://localhost:3001/api/tasks

Problem 6: “Generated app works locally but environment variables are committed to git”

Why: .env file was committed instead of example.env
Fix: Add .env to .gitignore, commit example.env with placeholders
Security: Never commit real secrets; use example.env with CHANGE_ME values