backend-dev-guidelines

Layered architecture separates routes, controllers, services, and repositories into distinct tiers. Routes handle HTTP requests, controllers manage request/response logic, services contain business logic, and repositories handle data access via Prisma. This separation improves testability and maintainability across microservices.

Centralized error handling with Sentry integration captures exceptions automatically across your application. Implement a BaseController pattern that wraps route handlers to catch errors, format them consistently, and send them to Sentry. This ensures all services report issues uniformly without repetitive error management code.

Zod provides schema validation for incoming request payloads with full TypeScript type inference. Define schemas at the controller layer, validate before passing data to services, and catch validation errors to return structured responses. This prevents invalid data from reaching business logic or the database.

Yes, dependency injection decouples services from their dependencies, making code testable and flexible. Wire up services in a DI container, inject them into controllers, and swap implementations for testing. This pattern scales well across multiple microservices like blog-api, auth-service, and notifications-service.

Use unifiedConfig to centralize environment variables and settings across services with type safety. Load configuration once at startup, validate schema upfront, and inject it into services. This prevents runtime configuration errors and ensures consistency between blog-api, auth-service, and notifications-service.

Incrementally refactor toward layered architecture by extracting business logic from routes into services, adding repositories for data access, and implementing centralized error handling. Move validation into dedicated schemas, introduce dependency injection, and add tests at each layer to ensure correctness during migration.