Building Full Stack Features

Quick Start

Given a feature request, produce these five deliverables in order:

1. Architecture — high-level diagram (text-based) showing client, API, services, database
2. Folder Structure — tree view of affected/new files
3. Database Schema — tables/collections, fields, types, relations
4. API Flow — endpoints, request/response shapes, sequence of calls
5. Implementation Plan — ordered steps from DB → backend → frontend → integration

Example trigger: "Build a feature for users to bookmark articles."

Workflow

Progress:

• Clarify feature scope from the request (core entities, user actions, constraints)
• Design Architecture (components + data flow)
• Define Folder Structure (backend + frontend, following existing project conventions if known)
• Design Database Schema (tables, keys, indexes, relations)
• Design API Flow (REST/GraphQL endpoints, auth, error handling)
• Write Implementation Plan (numbered, sequential, testable steps)
• Note edge cases and follow-up considerations

Step details:

1. Architecture: Identify layers (Client UI → API Gateway/Controller → Service/Business Logic → Repository/ORM → Database). Note external integrations (auth, storage, third-party APIs). Use ASCII diagram or bullet hierarchy.

2. Folder Structure: Show only new/modified paths. Group by layer (/frontend, /backend, /db/migrations). Use . placeholders for existing untouched dirs.

3. Database Schema: Table name, columns with type + constraints (PK/FK/NOT NULL/UNIQUE), relations (1-1, 1-N, N-N), indexes for query performance.

4. API Flow: List endpoints as METHOD /path with purpose, request body, response body, status codes. Show sequence for multi-step flows (e.g., create → notify → update cache).

5. Implementation Plan: Order = migration → model/entity → repository → service → controller/route → frontend API client → UI component → state management → tests. Each step is a checkbox-able task.

Examples

Example 1: Input: "Build a feature for users to bookmark articles."

Output:

Client (React) → REST API (Express Controller) → BookmarkService → BookmarkRepository → PostgreSQL

backend/ src/ models/Bookmark.ts repositories/bookmarkRepository.ts services/bookmarkService.ts controllers/bookmarkController.ts routes/bookmarkRoutes.ts frontend/ src/ api/bookmarkApi.ts hooks/useBookmarks.ts components/BookmarkButton.tsx

Table: bookmarks

• id UUID PK
• user_id UUID FK -> users.id, NOT NULL
• article_id UUID FK -> articles.id, NOT NULL
• created_at TIMESTAMP DEFAULT now()
• UNIQUE(user_id, article_id)
• INDEX(user_id)

POST /api/bookmarks body: { articleId } auth: required (JWT) response: 201 { id, userId, articleId, createdAt }

DELETE /api/bookmarks/:id auth: required, owner-only response: 204

GET /api/bookmarks auth: required response: 200 [{ id, article: {...} }]

1. Create bookmarks migration
2. Add Bookmark model/entity
3. Implement bookmarkRepository (create, delete, listByUser)
4. Implement bookmarkService (validate duplicate, ownership check)
5. Add controller + routes with auth middleware
6. Add bookmarkApi.ts client functions
7. Build useBookmarks hook (fetch, toggle)
8. Build BookmarkButton component
9. Wire into ArticleCard/ArticlePage
10. Write unit tests (service) + integration tests (route)

Best Practices

- Reuse existing project conventions (naming, folder layout, ORM) instead of inventing new patterns
- Always include auth/authorization in API Flow when data is user-specific
- Design schema with indexes for expected query patterns, not just PK/FK
- Keep Implementation Plan strictly sequential and dependency-ordered
- Call out caching, pagination, or rate-limiting needs if the feature implies scale
- Prefer idempotent, RESTful endpoint design unless GraphQL/RPC is already the project standard

Common Pitfalls

- Don't skip the database schema even for "simple" features — hidden relations cause rework
- Don't design frontend components before backend contracts are defined
- Don't omit error responses/status codes in API Flow
- Don't produce a flat implementation plan — always order by dependency (DB before service before UI)
- Don't assume authentication/authorization; state it explicitly or ask if unspecified