backend-dev-guidelines

Organize code into four layers: routes handle only routing and middleware registration, controllers extend a BaseController for request handling, services contain business logic with dependency injection, and repositories encapsulate Prisma data access. Each layer has exactly one responsibility.

Wrap async handlers with an asyncErrorWrapper utility that forwards errors to Express error middleware via next(error). Register the error boundary after all routes, capture every exception to Sentry, and use custom error classes like NotFoundError or ValidationError with proper HTTP status codes.

No. Use a unifiedConfig module that reads from a config file with environment variable fallbacks, validates values at startup, and provides type-safe access. Direct process.env usage causes typos, missing defaults, and untestable configuration scattered across the codebase.

Use Prisma's include option to fetch related records in a single query, or batch queries with the in operator when includes are impractical. Limit selected fields with select and avoid deeply nested includes that fetch unnecessary data.

Use repositories for complex queries with joins, queries reused in multiple places, or when you need caching and easy test mocking. Skip repositories for simple one-off queries or early prototyping where the abstraction adds no value.

Create an instrument.ts file that initializes Sentry with integrations and PII scrubbing, and import it first in server.ts. Register Sentry request handlers before routes and error handlers after routes, then capture exceptions in controllers via BaseController.handleError.