fullstack-dev

# 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 ```bash # 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 ```bash # 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](#1-project-structure--layering-critical) | | Manage config + secrets | [2. Configuration](#2-configuration--environment-critical) | | Handle errors properly | [3. Error Handling](#3-error-handling--resilience-high) | | Write database code | [4. Database Access Patterns](#4-database-access-patterns-high) | | Set up API client from frontend | [5. API Client Patterns](#5-api-client-patterns-medium) | | Add auth middleware | [6. Auth & Middleware](#6-authentication--middleware-high) | | Set up logging | [7. Logging & Observability](#7-logging--observability-medium-high) | | Add background jobs | [8. Background Jobs](#8-background-jobs--async-medium) | | Implement caching | [9. Caching](#9-caching-patterns-medium) | | Upload files (presigned URL, multipart) | [10. File Upload Patterns](#10-file-upload-patterns-medium) | | Add real-time features (SSE, WebSocket) | [11. Real-Time Patterns](#11-real-time-patterns-medium) | | Handle API errors in frontend UI | [12. Cross-Boundary Error Handling](#12-cross-boundary-error-handling-medium) | | Harden for production | [13. Production Hardening](#13-production-hardening-medium) | | Design API endpoints | [API Design](references/api-design.md) | | Design database schema | [Database Schema](references/db-schema.md) | | Auth flow (JWT, refresh, Next.js SSR, RBAC) | [references/auth-flow.md](references/auth-flow.md) | | CORS, env vars, environment management | [references/environment-management.md](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:** ```typescript class OrderService { constructor( private readonly orderRepo: OrderRepository, // ✅ injected interface private readonly emailService: EmailService, ) {} } ``` **Python:** ```python class OrderService: def __init__(self, order_repo: OrderRepository, email_service: EmailService): self.order_repo = order_repo # ✅ injected self.email_service = email_service ``` **Go:** ```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:** ```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:** ```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 ```typescript // 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}`, 'NOT_FOUND', 404); } } class ValidationError extends AppError { constructor(public readonly errors: FieldError[]) { super('Validation failed', 'VALIDATION_ERROR', 422); } } ``` ```python # Base (Python) class AppError(Exception): def __init__(self, message: str, code: str, status_code: int): self.message, self.code, self.status_code = message, code, status_code class NotFoundError(AppError): def __init__(self, resource: str, id: str): super().__init__(f"{resource} not found: {id}", "NOT_FOUND", 404) ``` ### Global Error Handler ```typescript // TypeScript (Express) app.use((err, req, res, next) => { if (err instanceof AppError && err.isOperational) { return res.status(err.statusCode).json({ title: err.code, status: err.statusCode, detail: err.message, request_id: req.id, }); } logger.error('Unexpected error', { error: err.message, stack: err.stack, request_id: req.id }); res.status(500).json({ title: 'Internal Error', status: 500, request_id: req.id }); }); ``` ### Rules ``` ✅ Typed, domain-specific error classes ✅ Global error handler catches everything ✅ Operational errors → structured response ✅ Programming errors → log + generic 500 ✅ Retry transient failures with exponential backoff ❌ Never catch and ignore errors silently ❌ Never return stack traces to client ❌ Never throw generic Error('something') ``` --- ## 4. Database Access Patterns (HIGH) ### Migrations Always ```bash # TypeScript (Prisma) # Python (Alembic) # Go (golang-migrate) npx prisma migrate dev alembic revision --autogenerate migrate -source file://migrations npx prisma migrate deploy alembic upgrade head migrate -database $DB up ``` ``` ✅ Schema changes via migrations, never manual SQL ✅ Migrations must be reversible ✅ Review migration SQL before production ❌ Never modify production schema manually ``` ### N+1 Prevention ```typescript // ❌ N+1: 1 query + N queries const orders = await db.order.findMany();