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)

Score Formula

BFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)

Range: -10 → +10

Interpretation

2. When to Use This Skill

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

3. 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.

4. 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

5. Naming Conventions (Strict)

6. Dependency Injection Rules

• •Services receive dependencies via constructo