---

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 | | API client approach | Typed fetch / React Query / tRPC / OpenAPI codegen | Section 5 | | Auth strategy | JWT + refresh / session / third-party | Section 6 | | Real-time method | Polling / SSE / WebSocket | Section 11 | | Error handling | Typed error hierarchy + global handler | Section 3 |

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 (shared types, OpenAPI, or tRPC)
• [ ] CORS configured with explicit origins (not * in production)
• [ ] Refresh token flow implemented (httpOnly cookie + transparent retry on 401)

---

Quick Navigation

| Need to… | Jump to | |----------|---------| | Organize project folders | 1. Project Structure | | Manage config + secrets | 2. Configuration | | Handle errors properly | 3. Error Handling | | Write database code | 4. Database Access Patterns | | Set up API client from frontend | 5. API Client Patterns | | Add auth middleware | 6. Auth & Middleware | | Set up logging | 7. Logging & Observability | | Add background jobs | 8. Background Jobs | | Implement caching | 9. Caching | | Upload files (presigned URL, multipart) | 10. File Upload Patterns | | Add real-time features (SSE, WebSocket) | 11. Real-Time Patterns | | Handle API errors in frontend UI | 12. Cross-Boundary Error Handling | | Harden for production | 13. Production Hardening | | Design API endpoints | API Design | | Design database schema | Database Schema | | Auth flow (JWT, refresh, Next.js SSR, RBAC) | references/auth-flow.md | | CORS, env vars, environment management | references/environment-management.md |

---

Core Principles (7 Iron Rules)

1. ✅ Organize by FEATURE, not by technical layer
2. ✅ Controllers never contain business logic
3. ✅ Services never import HTTP request/response types
4. ✅ All config from env vars, validated at startup, fail fast
5. ✅ Every error is typed, logged, and returns consistent format
6. ✅ All input validated at the boundary — trust nothing from client
7. ✅ Structured JSON logging with request ID — not console.log

---

1. Project Structure & Layering (CRITICAL)

Feature-First Organization

✅ Feature-first                    ❌ Layer-first
src/                                src/
  orders/                             controllers/
    order.controller.ts                 order.controller.ts
    order.service.ts                    user.controller.ts
    order.repository.ts               services/
    order.dto.ts                        order.service.ts
    order.test.ts                       user.service.ts
  users/                              repositories/
    user.controller.ts                  ...
    user.service.ts
  shared/
    database/
    middleware/

Three-Layer Architecture

Controller (HTTP) → Service (Business Logic) → Repository (Data Access)

| Layer | Responsibility | ❌ Never | |-------|---------------|---------| | Controller | Parse request, validate, call service, format response | Business logic, DB queries | | Service | Business rules, orchestration, transaction mgmt | HTTP types (req/res), direct DB | | Repository | Database queries, external API calls | Business logic, HTTP types |

Dependency Injection (All Languages)

TypeScript:

class OrderService {
  constructor(
    private readonly orderRepo: OrderRepository,    // ✅ injected interface
    private readonly emailService: EmailService,
  ) {}
}

Python:

class OrderService:
    def __init__(self, order_repo: OrderRepository, email_service: EmailService):
        self.order_repo = order_repo                 # ✅ injected
        self.email_service = email_service

Go:

type OrderService struct {
    orderRepo    OrderRepository                      // ✅ interface
    emailService EmailService
}

func NewOrderService(repo OrderRepository, email EmailService) *OrderService {
    return &OrderService{orderRepo: repo, emailService: email}
}

---

2. Configuration & Environment (CRITICAL)

Centralized, Typed, Fail-Fast

TypeScript:

const config = {
  port: parseInt(process.env.PORT || '3000', 10),
  database: { url: requiredEnv('DATABASE_URL'), poolSize: intEnv('DB_POOL_SIZE', 10) },
  auth: { jwtSecret: requiredEnv('JWT_SECRET'), expiresIn: process.env.JWT_EXPIRES_IN || '1h' },
} as const;

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing required env var: ${name}`);  // fail fast
  return value;
}

Python:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str                        # required — app won't start without it
    jwt_secret: str                          # required
    port: int = 3000                         # optional with default
    db_pool_size: int = 10
    class Config:
        env_file = ".env"

settings = Settings()                        # fails fast if DATABASE_URL missing

Rules

✅ All config via environment variables (Twelve-Factor)
✅ Validate required vars at startup — fail fast
✅ Type-cast at config layer, not at usage sites
✅ Commit .env.example with dummy values

❌ Never hardcode secrets, URLs, or credentials
❌ Never commit .env files
❌ Never scatter process.env / os.environ throughout code

---

3. Error Handling & Resilience (HIGH)

Typed Error Hierarchy

// Base (TypeScript)
class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode: number,
    public readonly isOperational: boolean = true,
  ) { super(message); }
}
class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} not found: ${id