Opinionated backend development standards for Node.js + Express + TypeScript microservices. Covers layered architecture, BaseController pattern, dependency injection, Prisma repositories, Zod validation, unifiedConfig, Sentry error tracking, async safety, and testing discipline.
Add this skill
npx mdskills install sickn33/backend-dev-guidelinesComprehensive production-grade backend architecture guidelines with clear layered structure and strong observability practices
1---2name: backend-dev-guidelines3description: Opinionated backend development standards for Node.js + Express + TypeScript microservices. Covers layered architecture, BaseController pattern, dependency injection, Prisma repositories, Zod validation, unifiedConfig, Sentry error tracking, async safety, and testing discipline.4---56# Backend Development Guidelines78**(Node.js · Express · TypeScript · Microservices)**910You are a **senior backend engineer** operating production-grade services under strict architectural and reliability constraints.1112Your goal is to build **predictable, observable, and maintainable backend systems** using:1314* Layered architecture15* Explicit error boundaries16* Strong typing and validation17* Centralized configuration18* First-class observability1920This skill defines **how backend code must be written**, not merely suggestions.2122---2324## 1. Backend Feasibility & Risk Index (BFRI)2526Before implementing or modifying a backend feature, assess feasibility.2728### BFRI Dimensions (1–5)2930| Dimension | Question |31| ----------------------------- | ---------------------------------------------------------------- |32| **Architectural Fit** | Does this follow routes → controllers → services → repositories? |33| **Business Logic Complexity** | How complex is the domain logic? |34| **Data Risk** | Does this affect critical data paths or transactions? |35| **Operational Risk** | Does this impact auth, billing, messaging, or infra? |36| **Testability** | Can this be reliably unit + integration tested? |3738### Score Formula3940```41BFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)42```4344**Range:** `-10 → +10`4546### Interpretation4748| BFRI | Meaning | Action |49| -------- | --------- | ---------------------- |50| **6–10** | Safe | Proceed |51| **3–5** | Moderate | Add tests + monitoring |52| **0–2** | Risky | Refactor or isolate |53| **< 0** | Dangerous | Redesign before coding |5455---5657## 2. When to Use This Skill5859Automatically applies when working on:6061* Routes, controllers, services, repositories62* Express middleware63* Prisma database access64* Zod validation65* Sentry error tracking66* Configuration management67* Backend refactors or migrations6869---7071## 3. Core Architecture Doctrine (Non-Negotiable)7273### 1. Layered Architecture Is Mandatory7475```76Routes → Controllers → Services → Repositories → Database77```7879* No layer skipping80* No cross-layer leakage81* Each layer has **one responsibility**8283---8485### 2. Routes Only Route8687```ts88// ❌ NEVER89router.post('/create', async (req, res) => {90 await prisma.user.create(...);91});9293// ✅ ALWAYS94router.post('/create', (req, res) =>95 userController.create(req, res)96);97```9899Routes must contain **zero business logic**.100101---102103### 3. Controllers Coordinate, Services Decide104105* Controllers:106107 * Parse request108 * Call services109 * Handle response formatting110 * Handle errors via BaseController111112* Services:113114 * Contain business rules115 * Are framework-agnostic116 * Use DI117 * Are unit-testable118119---120121### 4. All Controllers Extend `BaseController`122123```ts124export class UserController extends BaseController {125 async getUser(req: Request, res: Response): Promise<void> {126 try {127 const user = await this.userService.getById(req.params.id);128 this.handleSuccess(res, user);129 } catch (error) {130 this.handleError(error, res, 'getUser');131 }132 }133}134```135136No raw `res.json` calls outside BaseController helpers.137138---139140### 5. All Errors Go to Sentry141142```ts143catch (error) {144 Sentry.captureException(error);145 throw error;146}147```148149❌ `console.log`150❌ silent failures151❌ swallowed errors152153---154155### 6. unifiedConfig Is the Only Config Source156157```ts158// ❌ NEVER159process.env.JWT_SECRET;160161// ✅ ALWAYS162import { config } from '@/config/unifiedConfig';163config.auth.jwtSecret;164```165166---167168### 7. Validate All External Input with Zod169170* Request bodies171* Query params172* Route params173* Webhook payloads174175```ts176const schema = z.object({177 email: z.string().email(),178});179180const input = schema.parse(req.body);181```182183No validation = bug.184185---186187## 4. Directory Structure (Canonical)188189```190src/191├── config/ # unifiedConfig192├── controllers/ # BaseController + controllers193├── services/ # Business logic194├── repositories/ # Prisma access195├── routes/ # Express routes196├── middleware/ # Auth, validation, errors197├── validators/ # Zod schemas198├── types/ # Shared types199├── utils/ # Helpers200├── tests/ # Unit + integration tests201├── instrument.ts # Sentry (FIRST IMPORT)202├── app.ts # Express app203└── server.ts # HTTP server204```205206---207208## 5. Naming Conventions (Strict)209210| Layer | Convention |211| ---------- | ------------------------- |212| Controller | `PascalCaseController.ts` |213| Service | `camelCaseService.ts` |214| Repository | `PascalCaseRepository.ts` |215| Routes | `camelCaseRoutes.ts` |216| Validators | `camelCase.schema.ts` |217218---219220## 6. Dependency Injection Rules221222* Services receive dependencies via constructor223* No importing repositories directly inside controllers224* Enables mocking and testing225226```ts227export class UserService {228 constructor(229 private readonly userRepository: UserRepository230 ) {}231}232```233234---235236## 7. Prisma & Repository Rules237238* Prisma client **never used directly in controllers**239* Repositories:240241 * Encapsulate queries242 * Handle transactions243 * Expose intent-based methods244245```ts246await userRepository.findActiveUsers();247```248249---250251## 8. Async & Error Handling252253### asyncErrorWrapper Required254255All async route handlers must be wrapped.256257```ts258router.get(259 '/users',260 asyncErrorWrapper((req, res) =>261 controller.list(req, res)262 )263);264```265266No unhandled promise rejections.267268---269270## 9. Observability & Monitoring271272### Required273274* Sentry error tracking275* Sentry performance tracing276* Structured logs (where applicable)277278Every critical path must be observable.279280---281282## 10. Testing Discipline283284### Required Tests285286* **Unit tests** for services287* **Integration tests** for routes288* **Repository tests** for complex queries289290```ts291describe('UserService', () => {292 it('creates a user', async () => {293 expect(user).toBeDefined();294 });295});296```297298No tests → no merge.299300---301302## 11. Anti-Patterns (Immediate Rejection)303304❌ Business logic in routes305❌ Skipping service layer306❌ Direct Prisma in controllers307❌ Missing validation308❌ process.env usage309❌ console.log instead of Sentry310❌ Untested business logic311312---313314## 12. Integration With Other Skills315316* **frontend-dev-guidelines** → API contract alignment317* **error-tracking** → Sentry standards318* **database-verification** → Schema correctness319* **analytics-tracking** → Event pipelines320* **skill-developer** → Skill governance321322---323324## 13. Operator Validation Checklist325326Before finalizing backend work:327328* [ ] BFRI ≥ 3329* [ ] Layered architecture respected330* [ ] Input validated331* [ ] Errors captured in Sentry332* [ ] unifiedConfig used333* [ ] Tests written334* [ ] No anti-patterns present335336---337338## 14. Skill Status339340**Status:** Stable · Enforceable · Production-grade341**Intended Use:** Long-lived Node.js microservices with real traffic and real risk342---343
Full transparency — inspect the skill content before installing.