You are a senior backend engineer operating production-grade services under strict architectural and reliability constraints. Use when routes, controllers, services, repositories, express middleware, or prisma database access.

Backend Development Guidelines (Node.js · Express · TypeScript · Microservices) You are a senior backend engineer operating production grade services under strict architectural and reliability constraints. Your goal is to build predictable, observable, and maintainable backend systems using: Layered architecture Explicit error boundaries Strong typing and validation Centralized configuration First class observability Use these patterns when they fit the target repository; its architecture, authorization model and dependency versions take precedence. This documentation does not ship a runnable service. 1. Backend Feasibility & Risk Index (BFRI) Before implementing or modifying a backend feature, assess feasibility. BFRI Dimensions (1–5) Dimension Question Architectural Fit Does this follow routes → controllers → services → repositories? Business Logic Complexity How complex is the domain logic? Data Risk Does this affect critical data paths or transactions? Operational Risk Does this impact auth, billing, messaging, or infra? Testability Can this be reliably unit + integration tested? Score Formula Range: 13 → +7 (each input is 1–5). This is an informal discussion aid, not a validated risk model or merge gate. Interpretation BFRI Meaning Action 6–7 Lower concern Proceed 3–5 Moderate Add tests + monitoring 0–2 Risky Refactor or isolate < 0 Dangerous Redesign before coding When to Use Automatically applies when working on: Routes, controllers, services, repositories Express middleware Prisma database access Zod validation Approved error tracking with redaction and destination/retention controls Configuration management Backend refactors or migrations 2. Architecture Pattern (When Adopted by the Repository) 1. Layered Architecture Option No layer skipping No cross layer leakage Each layer has one responsibility 2. Routes Only Route Routes must contain zero business logic . 3. Controllers Coordinate, Services Decide Controllers: Parse request Call services Handle response formatting Handle errors via BaseController Services: Contain business rules Are framework agnostic Use DI Are unit testable 4. All Controllers Extend BaseController No raw res.json calls outside BaseController helpers. 5. Capture Unexpected Errors at One Approved Boundary ❌ console.log ❌ silent failures ❌ swallowed errors 6. unifiedConfig Is the Only Config Source 7. Validate All External Input with Zod Request bodies Query params Route params Webhook payloads No validation = bug. 3. Directory Structure (Canonical) 4. Naming Conventions (Strict) Layer Convention Controller PascalCaseController.ts Service camelCaseService.ts Repository PascalCaseRepository.ts Routes camelCaseRoutes.ts Validators camelCase.schema.ts 5. Dependency Injection Rules Services receive dependencies via constructor No importing repositories directly inside controllers Enables mocking and testing 6. Prisma & Repository Rules Prisma client never used directly in controllers Repositories: Encapsulate queries Handle transactions Expose intent based methods 7. Async & Error Handling asyncErrorWrapper Required For Express 4, route promises need an error forwarding wrapper. Express 5 forwards rejected returned promises; avoid duplicate handlers. Return or await the handler promise; a wrapper does not handle detached background work. 8. Observability & Monitoring Required Approved error tracking with redaction and destination/retention controls Sampled performance tracing appropriate to the installed SDK Structured logs (where applicable) Every critical path must be observable. 9. Testing Discipline Required Tests Unit tests for services Integration tests for routes Repository tests for complex queries No tests → no merge. 10. Review Signals ❌ Business logic in routes ❌ Skipping service layer ❌ Direct Prisma in controllers ❌ Missing validation ❌ Unvalidated environment access outside configuration bootstrap ❌ Unredacted or unapproved telemetry ❌ Untested business logic Resource Guide Read the relevant bundled resources before applying examples. Private project paths and @project lifecycle portal/database , SSOMiddleware , BaseController and configuration utilities are illustrative application components, not installed dependencies. Authenticate with access tokens, authorize every object/tenant action, allowlist public DTO fields, project response fields and protect cookie authenticated mutations against CSRF. 11. Integration With Other Skills frontend dev guidelines → API contract alignment error tracking → Sentry standards database verification → Schema correctness analytics tracking → Event pipelines skill developer → Skill governance 12. Operator Validation Checklist Before finalizing backend work: [ ] Risks discussed with evidence; no numeric score grants approval [ ] Layered architecture respected [ ] Input validated [ ] Errors captured in Sentry [ ] unifiedConfig used [ ] Tests written [ ] No anti patterns present 13. Skill Status Status: Illustrative patterns; target specific compilation, tests and security review required Intended Use: Long lived Node.js microservices with real traffic and real risk When to Use This skill is applicable to execute the workflow or actions described in the overview. Limitations Use this skill only when the task clearly matches the scope described above. Do not treat the output as a substitute for environment specific validation, testing, or expert review. Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

backend-dev-guidelines