backend-dev-guidelines

Layered architecture separates concerns into Routes → Controllers → Services → Repositories. Routes handle HTTP requests, controllers orchestrate business logic, services contain core logic, and repositories manage data access through Prisma. This structure improves testability, maintainability, and scalability across microservices.

Use Zod for type-safe input validation. Define schemas at route entry points, validate request data before passing to controllers, and leverage TypeScript inference to automatically type validated inputs. This prevents invalid data from entering business logic and ensures runtime safety.

Implement a BaseController that standardizes error handling and integrates Sentry for error tracking. Centralize error responses, log contextual information, and route all errors through middleware. This ensures every service reports failures consistently and enables cross-service observability.

Yes, this Skill provides migration guidance for converting legacy endpoints into the layered architecture. Refactor incrementally: extract business logic into services, create repositories for data access, and update controllers to use the new structure while maintaining backward compatibility.

Use unifiedConfig for type-safe, centralized configuration across services. Store environment variables in a single validated schema, share configuration across auth-service, blog-api, and notifications-service, and prevent runtime configuration errors through TypeScript type checking.

Follow explicit async patterns: always await promises in controllers and services, wrap handlers in try-catch blocks, and propagate errors to middleware. This prevents unhandled promise rejections, ensures proper error tracking in Sentry, and maintains predictable request-response flow.