backend-dev-guidelines-universal

Organize code into four layers: Routes map HTTP endpoints, Controllers handle request/response parsing, Services contain business logic, and Repositories manage database access. Keep controllers thin and services framework-agnostic so each layer is independently testable.

Controller validation checks HTTP-level concerns like required fields, types, and formats using tools like Zod, Pydantic, or Joi. Service validation enforces business rules such as state transitions, cross-field logic, and authorization checks.

Yes, the patterns are framework-agnostic and include adaptation examples for Django, FastAPI, Express, NestJS, Fastify, Go, and Spring Boot. Map routes, controllers, services, and repositories to your framework's routing, handlers, and data access mechanisms.

Return a consistent JSON envelope with success flag and an error object containing code, message, details array, and timestamp. Map business and data errors to appropriate HTTP status codes like 400, 401, 404, 409, and 500 at the controller layer.

Strict layering adds overhead for very small services, prototypes, or single-endpoint APIs where simplicity matters more. The guidelines emphasize ruthless simplicity: start simple and introduce layers only as complexity grows.