Regtransfers/backend-dev-guidelines

@ 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

@ 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)

Layer; Convention

Controller; PascalCaseController.ts Service; camelCaseService.ts Repository; PascalCaseRepository.ts Routes; camelCaseRoutes.ts Validators; camelCase.schema.ts

@ 6. Dependency Injection Rules

• Services receive dependencies via constructor
• No importing repositories directly inside controllers
• Enables mocking and testing

export class UserService {
  constructor(
    private readonly userRepository: UserRepository
  ) {}
}

@ 7. Prisma & Repository Rules

• Prisma client never used directly in controllers

• Repositories:

• Encapsulate queries

• Handle transactions

• Expose intent-based methods

await userRepository.findActiveUsers();

@ 8. Async & Error Handling

@ asyncErrorWrapper Required

All async route handlers must be wrapped.

router.get(
  '/users',
  asyncErrorWrapper((req, res) =>
    controller.list(req, res)
  )
);

No unhandled promise rejections.

@ 9. Observability & Monitoring

@ Required

• Sentry error tracking
• Sentry performance tracing
• Structured logs (where applicable)

Every critical path must be observable.

@ 10. Testing Discipline

@ Required Tests

• Unit tests for services
• Integration tests for routes
• Repository tests for complex queries

describe('UserService', () => {
  it('creates a user', async () => {
    expect(user).toBeDefined();
  });
});

No tests → no merge.

@ 11. Anti-Patterns (Immediate Rejection)

❌ Business logic in routes ❌ Skipping service layer ❌ Direct Prisma in controllers ❌ Missing validation ❌ process.env usage ❌ console.log instead of Sentry ❌ Untested business logic

@ 12. 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

@ 13. Operator Validation Checklist

Before finalizing backend work:

• [ ] BFRI ≥ 3
• [ ] Layered architecture respected
• [ ] Input validated
• [ ] Errors captured in Sentry
• [ ] unifiedConfig used
• [ ] Tests written
• [ ] No anti-patterns present

@ 14. Skill Status

Status: Stable · Enforceable · Production-grade 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.
• never 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.