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