backend-dev-guidelines_skill

Overview

This skill is a practical backend development guide for Node.js/Express/TypeScript microservices focused on consistent, testable, and observable services. It codifies a layered architecture (routes → controllers → services → repositories), patterns for error tracking, validation, configuration, and testing. Use it to standardize new features, services, or refactors across related microservices.

How this skill works

The guide inspects code and design choices against a set of core principles: keep routes thin, implement controllers that extend a BaseController, place business logic in services, and centralize data access in repositories with Prisma. It enforces input validation with Zod, configuration via unifiedConfig, error capture with Sentry, and a middleware/error-boundary stack. It also provides checklists, directory layout, naming conventions, and testing recommendations to ensure consistent implementations.

When to use it

• Creating or modifying HTTP routes, endpoints, and Express APIs
• Implementing controllers, services, repositories, or dependency injection
• Adding input validation, middleware, or Sentry error monitoring
• Working with Prisma database access or migrating legacy patterns
• Setting up unifiedConfig or configuring environment-driven behavior

Best practices

• Keep routes as thin routers that delegate to controllers only
• Extend a shared BaseController for consistent success/error handling
• Validate all input with Zod before business logic runs
• Send all uncaught errors to Sentry and avoid console.log for errors
• Use repository pattern for all Prisma access and DI for services
• Read and apply the New Backend Feature and New Microservice checklists

Example use cases

• Add a new POST endpoint: create route → controller → service → repository with Zod validation and Sentry capture
• Refactor monolithic route logic into layered controller/service/repository structure
• Instrument a service with Sentry and performance monitoring via instrument.ts
• Migrate process.env usage to unifiedConfig and update config typings
• Write unit and integration tests for services and controller error paths