# 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

```bash
# 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.

```bash
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`