Project 34: Full-Stack Application Generator
Project 34: Full-Stack Application Generator
Build a comprehensive agent that generates entire full-stack applications from natural language specifications - database schema, API endpoints, frontend components, tests, and deployment configuration - all orchestrated through Kiro CLI.
Quick Reference
| Attribute | Value |
|---|---|
| Difficulty | Master (Level 5) |
| Time Estimate | 1 month+ |
| Primary Language | TypeScript |
| Alternative Languages | Python, Go |
| Prerequisites | Projects 1-20, deep understanding of full-stack architecture |
| Key Topics | Domain-driven design, code generation, API design, schema design, orchestration |
| Kiro CLI Concepts | Custom agents, PostgreSQL MCP, Docker MCP, hooks, subagents, steering |
| Main Book Reference | “Domain-Driven Design” by Eric Evans |
1. Learning Objectives
By completing this project, you will:
- Master natural language specification parsing: Extract entities, relationships, and business rules from prose descriptions
- Implement domain-driven design with AI: Use AI to identify bounded contexts, aggregates, and domain events
- Build sophisticated code generation pipelines: Create consistent, maintainable code across all layers of the stack
- Orchestrate multi-layer application scaffolding: Coordinate database, API, and frontend generation with proper dependencies
- Integrate real-world deployment infrastructure: Generate Docker, CI/CD, and infrastructure-as-code configurations
2. Deep Theoretical Foundation
2.1 The Challenge of Specification Interpretation
Generating applications from natural language requires bridging the gap between human intent and machine-executable code:
THE SPECIFICATION INTERPRETATION CHALLENGE
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ NATURAL LANGUAGE INPUT │
│ ───────────────────── │
│ │
│ "Build a project management app where teams can create projects, │
│ assign tasks to members, track progress with status updates, │
│ and attach files to tasks. Teams should have owners and members │
│ with different permissions." │
│ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ INTERPRETATION LAYERS │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ LAYER 1: Entity Extraction │ │
│ │ ─────────────────────────── │ │
│ │ Entities: Team, Project, Task, Member, StatusUpdate, File │ │
│ │ Actors: Owner, Member │ │
│ │ │ │
│ │ LAYER 2: Relationship Mapping │ │
│ │ ──────────────────────────── │ │
│ │ Team 1:N Projects │ │
│ │ Project 1:N Tasks │ │
│ │ Task N:1 Member (assignee) │ │
│ │ Task 1:N StatusUpdates │ │
│ │ Task 1:N Files │ │
│ │ Team N:M Members (through TeamMembership) │ │
│ │ │ │
│ │ LAYER 3: Business Rules │ │
│ │ ───────────────────────── │ │
│ │ • Only team owners can delete projects │ │
│ │ • Members can only be assigned tasks in their teams │ │
│ │ • Status updates are append-only (audit trail) │ │
│ │ │ │
│ │ LAYER 4: Implicit Requirements │ │
│ │ ────────────────────────────── │ │
│ │ • Authentication required (implied by "permissions") │ │
│ │ • File storage needed (implied by "attach files") │ │
│ │ • Timestamps on all records (implied by "track progress") │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.2 Domain-Driven Design with AI
Eric Evans’ DDD provides the conceptual framework for understanding complex domains. AI can accelerate this process:
DDD CONCEPTS FOR CODE GENERATION
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ BOUNDED CONTEXTS │
│ ──────────────── │
│ │
│ A large application should be divided into bounded contexts, │
│ each with its own ubiquitous language and models. │
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ TEAM CONTEXT │ │ PROJECT CONTEXT │ │
│ │ │ │ │ │
│ │ • Team │ │ • Project │ │
│ │ • Member │ │ • Task │ │
│ │ • TeamMembership │ │ • StatusUpdate │ │
│ │ • Permission │ │ • Attachment │ │
│ │ │ │ │ │
│ │ Language: │ │ Language: │ │
│ │ "invite", "role" │ │ "assign", "status" │ │
│ │ "owner", "member" │ │ "progress", "due" │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ AGGREGATES │
│ ────────── │
│ │
│ An aggregate is a cluster of entities treated as a unit. │
│ Changes to the aggregate go through the aggregate root. │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ TASK AGGREGATE │ │
│ │ │ │
│ │ ┌──────────┐ │ │
│ │ │ Task │ ◀─── Aggregate Root │ │
│ │ │ (root) │ │ │
│ │ └────┬─────┘ │ │
│ │ │ │ │
│ │ ┌─────┴─────┐ │ │
│ │ │ │ │ │
│ │ ▼ ▼ │ │
│ │ ┌────────┐ ┌────────┐ │ │
│ │ │ Status │ │ File │ │ │
│ │ │ Update │ │ │ │ │
│ │ └────────┘ └────────┘ │ │
│ │ │ │
│ │ Operations: │ │
│ │ • task.addStatusUpdate(status, author) │ │
│ │ • task.attachFile(file) │ │
│ │ • task.assignTo(member) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ DOMAIN EVENTS │
│ ───────────── │
│ │
│ Events represent something that happened in the domain. │
│ They enable loose coupling and event sourcing. │
│ │
│ TaskCreated { taskId, projectId, title, createdBy } │
│ TaskAssigned { taskId, assigneeId, assignedBy } │
│ TaskStatusChanged { taskId, oldStatus, newStatus, changedBy } │
│ FileAttached { taskId, fileId, fileName } │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.3 The Generation Pipeline Architecture
Full-stack generation requires a coordinated pipeline:
FULL-STACK GENERATION PIPELINE
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ PHASE 1: DOMAIN MODELING │
│ ──────────────────────── │
│ │
│ Input: Natural language specification │
│ Output: Domain model (entities, relationships, rules) │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ AI Analysis │ │
│ │ • Extract entities and their properties │ │
│ │ • Identify relationships (1:1, 1:N, N:M) │ │
│ │ • Infer business rules from context │ │
│ │ • Determine authentication/authorization needs │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ PHASE 2: SCHEMA GENERATION │
│ ────────────────────────── │
│ │
│ Input: Domain model │
│ Output: Database schema (SQL migrations) │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ [PostgreSQL MCP] │ │
│ │ • Generate CREATE TABLE statements │ │
│ │ • Add proper indexes for relationships │ │
│ │ • Create migration files │ │
│ │ • Generate seed data for development │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ PHASE 3: API GENERATION │
│ ─────────────────────── │
│ │
│ Input: Domain model + schema │
│ Output: REST/GraphQL endpoints │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ [API Subagent] │ │
│ │ • Generate route handlers (CRUD) │ │
│ │ • Add validation schemas (Zod) │ │
│ │ • Implement authentication middleware │ │
│ │ • Create authorization checks │ │
│ │ • Generate OpenAPI spec │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ PHASE 4: FRONTEND GENERATION │
│ ──────────────────────────── │
│ │
│ Input: API spec + domain model │
│ Output: React/Vue components │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ [Frontend Subagent] │ │
│ │ • Generate page components │ │
│ │ • Create form components with validation │ │
│ │ • Add data fetching hooks │ │
│ │ • Implement routing │ │
│ │ • Apply styling (Tailwind) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ PHASE 5: TESTING GENERATION │
│ ─────────────────────────── │
│ │
│ Input: Generated code │
│ Output: Test files │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ [Test Subagent] │ │
│ │ • Generate unit tests for services │ │
│ │ • Create integration tests for API │ │
│ │ • Add component tests for frontend │ │
│ │ • Generate E2E tests for critical flows │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ PHASE 6: DEPLOYMENT GENERATION │
│ ────────────────────────────── │
│ │
│ Input: Application structure │
│ Output: Docker, CI/CD, infrastructure config │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ [DevOps Subagent] │ │
│ │ • Create Dockerfile and docker-compose.yml │ │
│ │ • Generate GitHub Actions workflows │ │
│ │ • Add environment configuration │ │
│ │ • Create deployment scripts │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.4 Code Generation Patterns
Consistent code generation requires well-defined patterns:
CODE GENERATION PATTERNS
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ TEMPLATE-BASED GENERATION │
│ ───────────────────────── │
│ │
│ Templates provide consistent structure while AI fills in specifics. │
│ │
│ Template: api/routes/[entity].ts │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ import { Router } from 'express'; │ │
│ │ import { {{Entity}}Service } from '../services/{{entity}}'; │ │
│ │ import { validate{{Entity}} } from '../validators/{{entity}}'; │ │
│ │ │ │
│ │ const router = Router(); │ │
│ │ │ │
│ │ router.get('/', async (req, res) => { │ │
│ │ const items = await {{Entity}}Service.findAll(req.query); │ │
│ │ res.json(items); │ │
│ │ }); │ │
│ │ │ │
│ │ router.post('/', validate{{Entity}}, async (req, res) => { │ │
│ │ const item = await {{Entity}}Service.create(req.body); │ │
│ │ res.status(201).json(item); │ │
│ │ }); │ │
│ │ │ │
│ │ // ... more CRUD operations │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ AI-AUGMENTED GENERATION │
│ ─────────────────────── │
│ │
│ AI adds domain-specific logic that templates can't capture. │
│ │
│ Entity: Task with status transitions │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ // AI-generated business logic │ │
│ │ class TaskService { │ │
│ │ async updateStatus(taskId: string, newStatus: Status) { │ │
│ │ const task = await this.findById(taskId); │ │
│ │ │ │
│ │ // AI understands valid state transitions │ │
│ │ const validTransitions = { │ │
│ │ 'todo': ['in_progress'], │ │
│ │ 'in_progress': ['review', 'blocked'], │ │
│ │ 'review': ['done', 'in_progress'], │ │
│ │ 'blocked': ['in_progress'], │ │
│ │ 'done': [] // Terminal state │ │
│ │ }; │ │
│ │ │ │
│ │ if (!validTransitions[task.status].includes(newStatus)) { │ │
│ │ throw new InvalidTransitionError(task.status, newStatus);│ │
│ │ } │ │
│ │ │ │
│ │ return this.update(taskId, { status: newStatus }); │ │
│ │ } │ │
│ │ } │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ COMPOSITION PATTERNS │
│ ──────────────────── │
│ │
│ Generated code should follow composition patterns for maintainability.│
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Controller Layer │ │
│ │ └── Handles HTTP request/response │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Service Layer │ │
│ │ └── Business logic, validation │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Repository Layer │ │
│ │ └── Data access, queries │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Database │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.5 The 80/20 Rule of Code Generation
AI can generate 80% of boilerplate, but 20% requires human refinement:
THE 80/20 GENERATION BOUNDARY
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ AI CAN GENERATE (80%) HUMANS MUST REFINE (20%) │
│ ───────────────────── ──────────────────────── │
│ │
│ ✓ CRUD operations ✗ Complex business rules │
│ ✓ Basic validations ✗ Edge case handling │
│ ✓ Standard UI components ✗ Custom UI interactions │
│ ✓ Database schema ✗ Performance optimization │
│ ✓ Authentication boilerplate ✗ Security hardening │
│ ✓ Basic test structure ✗ Meaningful test assertions │
│ ✓ Docker configuration ✗ Production tuning │
│ ✓ API routing ✗ API design decisions │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ THE REFINEMENT WORKFLOW │
│ ─────────────────────── │
│ │
│ 1. AI generates initial scaffolding │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Generated: src/services/TaskService.ts │ │
│ │ Status: SCAFFOLD - needs review │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ 2. Human reviews and identifies gaps │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ TODO: Add concurrent update handling │ │
│ │ TODO: Implement soft delete │ │
│ │ TODO: Add audit logging │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ 3. AI assists with refinements │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Human: "Add optimistic locking for concurrent updates" │ │
│ │ AI: Adds version column and conflict detection │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ 4. Human validates final implementation │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Status: REVIEWED - ready for production │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
3. Complete Project Specification
3.1 What You Will Build
A Kiro CLI agent that:
- Accepts natural language application specifications
- Parses and models the domain (entities, relationships, rules)
- Generates complete database schema with migrations
- Creates REST API with authentication and authorization
- Scaffolds frontend with components and routing
- Generates comprehensive tests
- Creates deployment configuration
3.2 Functional Requirements
| Requirement | Description |
|---|---|
| Spec Parsing | Extract entities, relationships, and rules from natural language |
| Domain Modeling | Create bounded contexts and aggregates |
| Schema Generation | Produce PostgreSQL schema with migrations |
| API Generation | Create REST endpoints with validation |
| Frontend Scaffolding | Generate React/Next.js components |
| Test Generation | Create unit, integration, and E2E tests |
| Deploy Config | Generate Docker and CI/CD files |
| Documentation | Produce API docs and README |
3.3 Non-Functional Requirements
- Maintainability: Generated code follows best practices
- Consistency: Uniform patterns across all generated files
- Extensibility: Easy to add custom code without conflicts
- Type Safety: Full TypeScript support throughout
4. Solution Architecture
4.1 System Architecture
┌──────────────────────────────────────────────────────────────────────────────┐
│ FULL-STACK APPLICATION GENERATOR │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ CLI INTERFACE │ │
│ │ │ │
│ │ kiro-cli --agent app-generator │ │
│ │ > "Generate a SaaS application for project management..." │ │
│ │ │ │
│ └────────────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ SPECIFICATION ANALYZER │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ Entity │ │ Relationship │ │ Business Rule │ │ │
│ │ │ Extractor │ │ Mapper │ │ Detector │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • Parse nouns │ │ • 1:1, 1:N, N:M│ │ • Permissions │ │ │
│ │ │ • Properties │ │ • Join tables │ │ • Constraints │ │ │
│ │ │ • Types │ │ • Foreign keys │ │ • Workflows │ │ │
│ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────┬──────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ GENERATION ORCHESTRATOR │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ SUBAGENT COORDINATOR │ │ │
│ │ │ │ │ │
│ │ │ Phase 1 Phase 2 Phase 3 Phase 4 │ │ │
│ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │
│ │ │ │ Schema │──▶│ API │──▶│Frontend │──▶│ Test │ │ │ │
│ │ │ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │ │ │
│ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ ▼ ▼ ▼ ▼ │ │ │
│ │ │ migrations/ src/api/ src/app/ __tests__/ │ │ │
│ │ │ │ │ │
│ │ └────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────┬──────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ MCP INTEGRATIONS │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ PostgreSQL │ │ Docker MCP │ │ File System │ │ │
│ │ │ MCP │ │ │ │ │ │ │
│ │ │ │ │ • Dockerfile │ │ • Write files│ │ │
│ │ │ • Schema │ │ • Compose │ │ • Create dirs│ │ │
│ │ │ • Migrations │ │ • Networks │ │ • Templates │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
4.2 Domain Model Schema
// Core types for application specification
interface ApplicationSpec {
name: string;
description: string;
entities: EntitySpec[];
relationships: RelationshipSpec[];
features: FeatureSpec[];
auth: AuthSpec;
deployment: DeploymentSpec;
}
interface EntitySpec {
name: string;
pluralName: string;
properties: PropertySpec[];
isAggregate: boolean;
aggregateRoot?: string;
timestamps: boolean;
softDelete: boolean;
}
interface PropertySpec {
name: string;
type: DataType;
required: boolean;
unique: boolean;
default?: string | number | boolean;
validation?: ValidationRule[];
}
type DataType =
| 'string'
| 'text'
| 'integer'
| 'float'
| 'boolean'
| 'date'
| 'datetime'
| 'json'
| 'enum'
| 'uuid';
interface RelationshipSpec {
from: string;
to: string;
type: '1:1' | '1:N' | 'N:M';
throughTable?: string;
onDelete: 'cascade' | 'set-null' | 'restrict';
required: boolean;
}
interface FeatureSpec {
name: string;
type: 'auth' | 'file-upload' | 'search' | 'notifications' | 'audit-log';
config: Record<string, unknown>;
}
interface AuthSpec {
type: 'jwt' | 'session' | 'oauth';
providers?: ('google' | 'github' | 'email')[];
roles: RoleSpec[];
}
interface RoleSpec {
name: string;
permissions: PermissionSpec[];
}
interface PermissionSpec {
entity: string;
actions: ('create' | 'read' | 'update' | 'delete')[];
conditions?: string; // e.g., "own" or "team"
}
interface DeploymentSpec {
platform: 'docker' | 'kubernetes' | 'vercel' | 'railway';
database: 'postgresql' | 'mysql' | 'sqlite';
storage?: 's3' | 'local';
ci: 'github-actions' | 'gitlab-ci';
}
interface GenerationContext {
spec: ApplicationSpec;
outputDir: string;
framework: {
backend: 'express' | 'fastify' | 'nestjs';
frontend: 'nextjs' | 'react' | 'vue';
orm: 'prisma' | 'drizzle' | 'typeorm';
styling: 'tailwind' | 'css-modules' | 'styled-components';
};
options: {
generateTests: boolean;
generateDocs: boolean;
generateDocker: boolean;
};
}
4.3 Generated File Structure
GENERATED APPLICATION STRUCTURE
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ project-management-app/ │
│ │ │
│ ├── prisma/ # Database layer │
│ │ ├── schema.prisma # Schema definition │
│ │ └── migrations/ # Migration files │
│ │ ├── 001_create_users.sql │
│ │ ├── 002_create_teams.sql │
│ │ └── ... │
│ │ │
│ ├── src/ │
│ │ ├── api/ # API layer │
│ │ │ ├── routes/ │
│ │ │ │ ├── users.ts # User CRUD │
│ │ │ │ ├── teams.ts # Team CRUD │
│ │ │ │ ├── projects.ts # Project CRUD │
│ │ │ │ └── tasks.ts # Task CRUD │
│ │ │ ├── middleware/ │
│ │ │ │ ├── auth.ts # Authentication │
│ │ │ │ ├── authorize.ts # Authorization │
│ │ │ │ └── validate.ts # Validation │
│ │ │ └── index.ts # API entry │
│ │ │ │
│ │ ├── services/ # Business logic │
│ │ │ ├── UserService.ts │
│ │ │ ├── TeamService.ts │
│ │ │ ├── ProjectService.ts │
│ │ │ └── TaskService.ts │
│ │ │ │
│ │ ├── validators/ # Input validation │
│ │ │ ├── user.ts │
│ │ │ ├── team.ts │
│ │ │ ├── project.ts │
│ │ │ └── task.ts │
│ │ │ │
│ │ └── types/ # TypeScript types │
│ │ └── index.ts │
│ │ │
│ ├── app/ # Frontend (Next.js) │
│ │ ├── (auth)/ │
│ │ │ ├── login/page.tsx │
│ │ │ └── register/page.tsx │
│ │ ├── (dashboard)/ │
│ │ │ ├── projects/ │
│ │ │ │ ├── page.tsx # Project list │
│ │ │ │ └── [id]/page.tsx # Project detail │
│ │ │ └── tasks/ │
│ │ │ └── [id]/page.tsx # Task detail │
│ │ └── layout.tsx │
│ │ │
│ ├── components/ # UI components │
│ │ ├── ui/ # Base components │
│ │ │ ├── Button.tsx │
│ │ │ ├── Input.tsx │
│ │ │ └── Card.tsx │
│ │ └── features/ # Feature components │
│ │ ├── ProjectCard.tsx │
│ │ ├── TaskList.tsx │
│ │ └── TeamSelector.tsx │
│ │ │
│ ├── __tests__/ # Tests │
│ │ ├── api/ # API tests │
│ │ ├── services/ # Service tests │
│ │ └── e2e/ # End-to-end tests │
│ │ │
│ ├── docker-compose.yml # Local dev environment │
│ ├── Dockerfile # Production build │
│ ├── .github/workflows/ # CI/CD │
│ │ ├── ci.yml │
│ │ └── deploy.yml │
│ │ │
│ └── docs/ # Documentation │
│ ├── api.md # API documentation │
│ └── architecture.md # Architecture overview │
│ │
└─────────────────────────────────────────────────────────────────────────┘
5. Phased Implementation Guide
Phase 1: Specification Parser (Days 1-7)
Goals:
- Parse natural language into structured spec
- Extract entities and properties
- Identify relationships
Tasks:
- Create ApplicationSpec schema
- Build entity extraction prompts
- Implement relationship detection
- Add validation for parsed spec
- Create spec preview for user approval
Milestone Checkpoint:
$ kiro-cli --agent app-generator
> "Create a blog app with posts, comments, and users"
[Parser] Analyzing specification...
[Entities Detected]
┌────────────────────────────────────────────────────────────────────┐
│ Entity │ Properties │ Type │
├──────────┼───────────────────────────────────┼───────────────────┤
│ User │ id, email, name, password, avatar │ Aggregate Root │
│ Post │ id, title, content, published │ Aggregate Root │
│ Comment │ id, content, author_id, post_id │ Entity (of Post) │
└──────────┴───────────────────────────────────┴───────────────────┘
[Relationships]
• User 1:N Posts (user writes many posts)
• Post 1:N Comments (post has many comments)
• User 1:N Comments (user writes many comments)
[Inferred Features]
• Authentication (email/password)
• Timestamps on all entities
• Soft delete for posts
Proceed with this model? [Y/n]
Hint 1: Use few-shot prompting with example specifications to improve entity extraction accuracy.
Phase 2: Schema Generation (Days 8-14)
Goals:
- Generate Prisma schema from spec
- Create migration files
- Add seed data generation
Tasks:
- Map entities to Prisma models
- Generate relationships (1:1, 1:N, N:M)
- Add proper indexes
- Create migration SQL files
- Generate seed data script
Milestone Checkpoint:
> "Generate database schema"
[PostgreSQL MCP] Generating schema...
Created: prisma/schema.prisma
┌─────────────────────────────────────────────────────────────────┐
│ model User { │
│ id String @id @default(uuid()) │
│ email String @unique │
│ name String │
│ password String │
│ avatar String? │
│ posts Post[] │
│ comments Comment[] │
│ createdAt DateTime @default(now()) │
│ updatedAt DateTime @updatedAt │
│ } │
│ │
│ model Post { │
│ id String @id @default(uuid()) │
│ title String │
│ content String │
│ published Boolean @default(false) │
│ author User @relation(fields: [authorId], ...) │
│ authorId String │
│ comments Comment[] │
│ createdAt DateTime @default(now()) │
│ updatedAt DateTime @updatedAt │
│ } │
│ ... │
└─────────────────────────────────────────────────────────────────┘
Created: prisma/migrations/001_initial.sql
Created: prisma/seed.ts
Hint 2: Generate @map and @@map annotations for snake_case database columns while keeping camelCase in TypeScript.
Phase 3: API Generation (Days 15-21)
Goals:
- Generate CRUD endpoints for all entities
- Add authentication and authorization
- Create validation schemas
Tasks:
- Create route files for each entity
- Generate service layer with business logic
- Implement Zod validation schemas
- Add authentication middleware
- Generate OpenAPI documentation
Milestone Checkpoint:
> "Generate API layer"
[API Subagent] Generating endpoints...
Created API routes:
├── src/api/routes/users.ts (6 endpoints)
├── src/api/routes/posts.ts (6 endpoints)
├── src/api/routes/comments.ts (5 endpoints)
└── src/api/routes/auth.ts (3 endpoints)
API Summary:
┌────────────────────────────────────────────────────────────────────┐
│ Method │ Endpoint │ Auth │ Description │
├────────┼────────────────────┼────────┼────────────────────────────┤
│ GET │ /api/posts │ No │ List all posts │
│ GET │ /api/posts/:id │ No │ Get post by ID │
│ POST │ /api/posts │ Yes │ Create new post │
│ PUT │ /api/posts/:id │ Yes │ Update post (owner only) │
│ DELETE │ /api/posts/:id │ Yes │ Delete post (owner only) │
│ ... │ ... │ ... │ ... │
└────────┴────────────────────┴────────┴────────────────────────────┘
Created: docs/api.md (OpenAPI specification)
Phase 4: Frontend Generation (Days 22-28)
Goals:
- Generate page components
- Create form components
- Implement data fetching
Tasks:
- Create page routes (Next.js app router)
- Generate list and detail views
- Build form components with validation
- Add data fetching with React Query
- Apply Tailwind styling
Milestone Checkpoint:
> "Generate frontend"
[Frontend Subagent] Generating components...
Created pages:
├── app/(auth)/login/page.tsx
├── app/(auth)/register/page.tsx
├── app/(dashboard)/posts/page.tsx
├── app/(dashboard)/posts/[id]/page.tsx
├── app/(dashboard)/posts/new/page.tsx
└── app/(dashboard)/profile/page.tsx
Created components:
├── components/features/PostCard.tsx
├── components/features/PostForm.tsx
├── components/features/CommentList.tsx
├── components/ui/Button.tsx
├── components/ui/Input.tsx
└── components/ui/Card.tsx
Created hooks:
├── hooks/usePosts.ts
├── hooks/usePost.ts
└── hooks/useAuth.ts
Phase 5: Test and Deploy (Days 29-35)
Goals:
- Generate comprehensive tests
- Create Docker configuration
- Set up CI/CD
Tasks:
- Generate API integration tests
- Create service unit tests
- Add component tests
- Build Dockerfile and docker-compose
- Create GitHub Actions workflows
Hint 3: Generate test fixtures from the seed data to ensure consistency between development and testing.
6. Testing Strategy
6.1 Generated Test Structure
// Example generated test
describe('PostService', () => {
beforeEach(async () => {
await db.post.deleteMany();
await db.user.deleteMany();
});
describe('create', () => {
it('should create a post for authenticated user', async () => {
const user = await createTestUser();
const post = await PostService.create({
title: 'Test Post',
content: 'Test content',
authorId: user.id
});
expect(post.title).toBe('Test Post');
expect(post.authorId).toBe(user.id);
});
it('should require authentication', async () => {
await expect(PostService.create({
title: 'Test',
content: 'Test',
authorId: 'invalid-id'
})).rejects.toThrow('Unauthorized');
});
});
});
6.2 Validation Tests
| Aspect | Test | Pass Criteria |
|---|---|---|
| Schema | Migrations apply cleanly | No SQL errors |
| API | All endpoints respond correctly | 2xx responses for valid requests |
| Auth | Protected routes require auth | 401 for unauthenticated |
| Frontend | Pages render without errors | No React errors |
| E2E | Full user flow works | Create, read, update, delete |
7. Common Pitfalls and Debugging
7.1 Common Issues
| Pitfall | Symptom | Solution |
|---|---|---|
| Circular dependencies | Import errors | Separate entity types into base module |
| Missing relationships | Foreign key errors | Review spec for implicit relationships |
| Auth scope issues | Unauthorized errors | Check permission rules in spec |
| Type mismatches | TypeScript errors | Regenerate types from schema |
| Migration conflicts | Database errors | Reset and regenerate migrations |
7.2 Debugging Strategies
1. Validate spec before generation:
> "Show me the parsed specification"
[Spec Validation]
├── Entities: 4 (User, Post, Comment, Tag)
├── Relationships: 5
├── Business Rules: 3
├── Warnings:
│ ├── Post.published has no default - assuming false
│ └── Comment.content has no max length - assuming 1000
└── Status: Valid (with warnings)
2. Incremental generation:
> "Generate only the User entity first"
# Verify User works before generating all entities
3. Test isolation:
> "Run tests for the API layer only"
[Test Runner]
├── src/api/__tests__/users.test.ts ✓ (12 tests)
├── src/api/__tests__/posts.test.ts ✗ (1 failure)
│ └── FAIL: should require auth for create
│ Expected 401, got 200
└── Fix: Authentication middleware not applied to POST /posts
8. Extensions and Challenges
8.1 Beginner Extensions
- Add GraphQL API as alternative to REST
- Generate Storybook stories for components
- Add i18n support with generated translation files
8.2 Intermediate Extensions
- Support for real-time features (WebSockets)
- Generate mobile app with React Native
- Add multi-tenant architecture support
8.3 Advanced Extensions
- AI-powered spec refinement through conversation
- Generate microservices architecture
- Support for event sourcing and CQRS patterns
9. Real-World Connections
9.1 Industry Tools
| Tool | Similar Pattern | Company |
|---|---|---|
| Blitz.js | Full-stack scaffolding | Blitz |
| RedwoodJS | Full-stack framework | Redwood |
| Amplication | Backend generation | Amplication |
| Supabase | Database + API | Supabase |
9.2 Production Considerations
- Customization: Generated code should be clearly marked and easy to extend
- Regeneration: Changes to spec should not overwrite custom code
- Testing: Generated tests are starting points, not complete coverage
- Security: Generated auth is basic - always add security hardening
10. Self-Assessment Checklist
Understanding Verification
- I can explain domain-driven design concepts
- I understand the 80/20 rule for code generation
- I can identify aggregates and bounded contexts
- I know when to use 1:1, 1:N, and N:M relationships
- I understand the generation pipeline phases
Implementation Verification
- Spec parser extracts entities correctly
- Relationships are detected and modeled
- Schema generates valid Prisma models
- API endpoints work with authentication
- Frontend renders and fetches data
- Tests pass for generated code
Integration Verification
- Full application runs with docker-compose
- CI/CD pipeline builds and deploys
- Generated code is maintainable
- Custom code can be added without conflicts
11. Completion Criteria
Minimum Viable Completion
- Parse specification and extract entities
- Generate database schema
- Create basic CRUD API
- Scaffold simple frontend pages
- Docker configuration works
Full Completion
- Complete authentication with roles
- Authorization on all endpoints
- Full frontend with forms and validation
- Comprehensive test coverage
- CI/CD pipeline
Excellence (Going Above and Beyond)
- AI-powered spec refinement
- Multiple framework support
- Real-time feature generation
- Custom code protection on regeneration
- Visual spec editor
This guide was expanded from LEARN_KIRO_CLI_MASTERY.md. For the complete learning path, see the README.