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): Stack : Language/framework for backend and frontend (e.g., Express + React, Django + Vue, Go + HTMX) Service type : API-only, full-stack monolith, or microservice? Database : SQL (PostgreSQL, SQLite, MySQL) or NoSQL (MongoDB, Redis)? Integration : REST, GraphQL, tRPC, or gRPC? Real-time : Needed? If yes — SSE, WebSocket, or polling? 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: Build check : Ensure both backend and frontend compile without errors # Backend cd server && npm run build # Frontend cd client && npm run build 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> Integration check : Verify frontend can connect to backend (CORS, API base URL, auth flow) 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} ` , 'NOT_FOUND' , 404 ); } } class ValidationError extends AppError { constructor ( public readonly errors : FieldError [] ) { super ( 'Validation failed' , 'VALIDATION_ERROR' , 422 ); } } # 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 (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 # 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 // ❌ N+1: 1 query + N queries const orders = await db. order . findMany ();