/fullstack-dev

name: fullstack-dev
description: |
  Full-stack backend architecture and frontend-backend integration guide.
  TRIGGER when: building a full-stack app, creating REST API with frontend, scaffolding backend service,
  building todo app, building CRUD app, building real-time app, building chat app,
  Express + React, Next.js API, Node.js backend, Python backend, Go backend,
  designing service layers, implementing error handling, managing config/auth,
  setting up API clients, implementing auth flows, handling file uploads,
  adding real-time features (SSE/WebSocket), hardening for production.
  DO NOT TRIGGER when: pure frontend UI work, pure CSS/styling, database schema only.
license: MIT
metadata:
  category: full-stack
  version: "1.0.0"
  sources:
    - The Twelve-Factor App (12factor.net)
    - Clean Architecture (Robert C. Martin)
    - Domain-Driven Design (Eric Evans)
    - Patterns of Enterprise Application Architecture (Martin Fowler)
    - Martin Fowler (Testing Pyramid, Contract Tests)
    - Google SRE Handbook (Release Engineering)
    - ThoughtWorks Technology Radar

Full-Stack Development Practices

MANDATORY WORKFLOW — Follow These Steps In Order

**When this skill is triggered, you MUST follow this workflow before writing any code.**

Step 0: Gather Requirements

Before scaffolding anything, ask the user to clarify (or infer from context):

1. **Stack**: Language/framework for backend and frontend (e.g., Express + React, Django + Vue, Go + HTMX) 2. **Service type**: API-only, full-stack monolith, or microservice? 3. **Database**: SQL (PostgreSQL, SQLite, MySQL) or NoSQL (MongoDB, Redis)? 4. **Integration**: REST, GraphQL, tRPC, or gRPC? 5. **Real-time**: Needed? If yes — SSE, WebSocket, or polling? 6. **Auth**: Needed? If yes — JWT, session, OAuth, or third-party (Clerk, Auth.js)?

If the user has already specified these in their request, skip asking and proceed.

Step 1: Architectural Decisions

Based on requirements, make and state these decisions before coding:

| Decision | Options | Reference | |----------|---------|-----------| | Project structure | Feature-first (recommended) vs layer-first | [Section 1](#1-project-structure--layering-critical) | | API client approach | Typed fetch / React Query / tRPC / OpenAPI codegen | [Section 5](#5-api-client-patterns-medium) | | Auth strategy | JWT + refresh / session / third-party | [Section 6](#6-authentication--middleware-high) | | Real-time method | Polling / SSE / WebSocket | [Section 11](#11-real-time-patterns-medium) | | Error handling | Typed error hierarchy + global handler | [Section 3](#3-error-handling--resilience-high) |

Briefly explain each choice (1 sentence per decision).

Step 2: Scaffold with Checklist

Use the appropriate checklist below. Ensure ALL checked items are implemented — do not skip any.

Step 3: Implement Following Patterns

Write code following the patterns in this document. Reference specific sections as you implement each part.

Step 4: Test & Verify

After implementation, run these checks before claiming completion:

1. **Build check**: Ensure both backend and frontend compile without errors

   # Backend
   cd server && npm run build
   # Frontend
   cd client && npm run build

2. **Start & smoke test**: Start the server, verify key endpoints return expected responses

   # Start server, then test
   curl http://localhost:3000/health
   curl http://localhost:3000/api/<resource>

3. **Integration check**: Verify frontend can connect to backend (CORS, API base URL, auth flow) 4. **Real-time check** (if applicable): Open two browser tabs, verify changes sync

If any check fails, fix the issue before proceeding.

Step 5: Handoff Summary

Provide a brief summary to the user:

• **What was built**: List of implemented features and endpoints
• **How to run**: Exact commands to start backend and frontend
• **What's missing / next steps**: Any deferred items, known limitations, or recommended improvements
• **Key files**: List the most important files the user should know about

---

Scope

**USE this skill when:**

• Building a full-stack application (backend + frontend)
• Scaffolding a new backend service or API
• Designing service layers and module boundaries
• Implementing database access, caching, or background jobs
• Writing error handling, logging, or configuration management
• Reviewing backend code for architectural issues
• Hardening for production
• Setting up API clients, auth flows, file uploads, or real-time features

**NOT for:**

• Pure frontend/UI concerns (use your frontend framework's docs)
• Pure database schema design without backend context

---

Quick Start — New Backend Service Checklist

• [ ] Project scaffolded with **feature-first** structure
• [ ] Configuration **centralized**, env vars **validated at startup** (fail fast)
• [ ] **Typed error hierarchy** defined (not generic `Error`)
• [ ] **Global error handler** middleware
• [ ] **Structured JSON logging** with request ID propagation
• [ ] Database: **migrations** set up, **connection pooling** configured
• [ ] **Input validation** on all endpoints (Zod / Pydantic / Go validator)
• [ ] **Authentication middleware** in place
• [ ] **Health check** endpoints (`/health`, `/ready`)
• [ ] **Graceful shutdown** handling (SIGTERM)
• [ ] **CORS** configured (explicit origins, not `*`)
• [ ] **Security headers** (helmet or equivalent)
• [ ] `.env.example` committed (no real secrets)

Quick Start — Frontend-Backend Integration Checklist

• [ ] **API client** configured (typed fetch wrapper, React Query, tRPC, or OpenAPI generated)
• [ ] **Base URL** from environment variable (not hardcoded)
• [ ] **Auth token** attached to requests automatically (interceptor / middleware)
• [ ] **Error handling** — API errors mapped to user-facing messages
• [ ] **Loading states** handled (skeleton/spinner, not blank screen)
• [ ] **Type safety** across the boundary (share