
About
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.
name: backend-dev-guidelines description: "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." risk: unknown source: community date_added: "2026-02-27"
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
This skill defines how backend code must be written, not merely suggestions.
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
BFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)
Range: -10 → +10
Interpretation
| BFRI | Meaning | Action | | -------- | --------- | ---------------------- | | 6–10 | Safe | 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
- Sentry error tracking
- Configuration management
- Backend refactors or migrations
2. Core Architecture Doctrine (Non-Negotiable)
1. Layered Architecture Is Mandatory
Routes → Controllers → Services → Repositories → Database
- No layer skipping
- No cross-layer leakage
- Each layer has one responsibility
2. Routes Only Route
// ❌ NEVER
router.post('/create', async (req, res) => {
await prisma.user.create(...);
});
// ✅ ALWAYS
router.post('/create', (req, res) =>
userController.create(req, res)
);
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
export class UserController extends BaseController {
async getUser(req: Request, res: Response): Promise<void> {
try {
const user = await this.userService.getById(req.params.id);
this.handleSuccess(res, user);
} catch (error) {
this.handleError(error, res, 'getUser');
}
}
}
No raw res.json calls outside BaseController helpers.
5. All Errors Go to Sentry
catch (error) {
Sentry.captureException(error);
throw error;
}
❌ console.log
❌ silent failures
❌ swallowed errors
6. unifiedConfig Is the Only Config Source
// ❌ NEVER
process.env.JWT_SECRET;
// ✅ ALWAYS
import { config } from '@/config/unifiedConfig';
config.auth.jwtSecret;
7. Validate All External Input with Zod
- Request bodies
- Query params
- Route params
- Webhook payloads
const schema = z.object({
email: z.string().email(),
});
const input = schema.parse(req.body);
No validation = bug.
3. Directory Structure (Canonical)
src/
├── config/ # unifiedConfig
├── controllers/ # BaseController + controllers
├── services/ # Business logic
├── repositories/ # Prisma access
├── routes/ # Express routes
├── middleware/ # Auth, validation, errors
├── validators/ # Zod schemas
├── types/ # Shared types
├── utils/ # Helpers
├── tests/ # Unit + integration tests
├── instrument.ts # Sentry (FIRST IMPORT)
├── app.ts # Express app
└── server.ts # HTTP server
4. Naming Conventions (Strict)
| Layer | Convention | | ---------- | --------
