Frontend Builder Agent

SF-03 — Automated Frontend Project Generation

Overview

The Frontend Builder Agent consumes PRD (SF-01) + Architecture (SF-02) and generates a complete, runnable Next.js project with TypeScript and Tailwind CSS.

Every page is a real component with meaningful JSX, state management, and API integration patterns — no stubs.

Quick Start

# From PRD + Architecture files
node scripts/frontend-builder-agent.mjs --prd prd-example.json --arch architecture-example.json --verbose

# Full pipeline from one sentence
node scripts/frontend-builder-agent.mjs --input-text "做一个宠物管理 App" --output my-app

Output Structure

frontend/
├── app/                          # Next.js App Router pages
│   ├── page.tsx                  # Home page
│   ├── layout.tsx                # (in src/app/)
│   ├── pet/[id]/page.tsx         # Dynamic route
│   ├── schedule/page.tsx
│   ├── daily-log/page.tsx
│   ├── album/page.tsx
│   ├── hospitals/page.tsx
│   └── profile/page.tsx
├── components/
│   ├── ui/                       # Shared UI (Button, Card, Input, Modal, EmptyState)
│   ├── layout/                   # Sidebar, BottomNav
│   └── {domain}/                 # Domain components (PetCard, ProductCard, NoteCard)
├── hooks/                        # Custom React hooks
│   ├── usePets.ts               # Per-resource data hooks
│   ├── useSchedules.ts
│   ├── useForm.ts               # Generic hooks
│   └── useDebounce.ts
├── services/                     # API service layer
│   ├── api.ts                   # Base API client (get/post/put/delete)
│   ├── pets.ts                  # Per-resource API functions
│   └── schedules.ts
├── types/
│   └── index.ts                 # TypeScript interfaces
├── package.json
├── tsconfig.json
├── tailwind.config.ts
├── next.config.ts
└── postcss.config.js

Architecture

┌─────────────────────────────────────────────────────┐
│              SF-03 Frontend Builder                 │
│                                                     │
│  PRD + Architecture ──▶                             │
│                                                     │
│  1. Type Generator                                  │
│     Domain → TS interfaces (User, Pet, Order...)    │
│     Always: ApiResponse, PaginatedResponse          │
│                                                     │
│  2. Config Generator                                │
│     package.json, tsconfig, tailwind, next.config   │
│                                                     │
│  3. Layout Generator                                │
│     Root layout + Sidebar (desktop) + BottomNav     │
│     Auto-generates nav from PRD pages               │
│                                                     │
│  4. UI Component Generator                          │
│     Button, Card, Input, Modal, EmptyState          │
│     All with props, variants, accessibility         │
│                                                     │
│  5. Domain Component Generator                      │
│     pet → PetCard, ScheduleCard                     │
│     ecommerce → ProductCard                         │
│     note → NoteCard                                 │
│                                                     │
│  6. Page Generator                                  │
│     Per-route page with real JSX                    │
│     Domain-specific layouts & interactions          │
│     Loading, error, and empty states                │
│                                                     │
│  7. Hook Generator                                  │
│     Per-resource: usePets, useSchedules...          │
│     Generic: useForm, useDebounce                   │
│                                                     │
│  8. API Service Generator                           │
│     Base client with fetch wrapper                  │
│     Per-resource: get/post/put/delete functions     │
│                                                     │
│  ──────────────▶ frontend/ directory               │
└─────────────────────────────────────────────────────┘

Page Quality

Every generated page contains:

Layout: Heading, description, grid/flex layout
State: useState for interactive elements
Hooks: useEffect for data loading simulation
Loading state: Spinner animation
Error state: Error message with retry button
Empty state: Illustrated empty state with CTA
Data display: Cards, lists, grids with real-looking mock data
Interactivity: Buttons, toggles, modals, forms

No page is a simple return <div>TODO</div>.

Domain Coverage

Domain	Pages	Components	Types
🐱 pet	7 pages	PetCard, ScheduleCard	Pet, Schedule, DailyLog, Hospital
🛒 ecommerce	6 pages	ProductCard	Product, Order, Logistics
📚 education	6 pages	—	Course, Lesson, Exercise, Progress
🏢 enterprise	6 pages	—	Department, Approval, Attendance
💪 fitness	5 pages	—	CheckIn, TrainingPlan
📝 note	4 pages	NoteCard	Note, Tag
🔧 generic	4+ pages	—	Item

Tech Stack

Framework: Next.js 15 (App Router)
Language: TypeScript 5 (strict mode)
Styling: Tailwind CSS 3.4
State: React 19 hooks (useState, useEffect, useCallback)
Routing: File-based dynamic routes ([id])
API: fetch-based client with typed wrappers

Test Coverage

32 tests across 11 suites.

node --test test/frontend-builder-agent.test.mjs

Downstream Integration

Generated frontend is designed for:

SF-04 (Dev Agent): Reads generated project → sets up CI/CD, runs compilation
SF-05 (QA Agent): Reads pages, types → generates test cases
Direct use: cd frontend && npm install && npm run dev

6.4 KiB Raw Blame History