Backend Development Guidelines
Purpose
Establish consistency and best practices across backend microservices (blog-api, auth-service, notifications-service) using modern Node.js/Express/TypeScript patterns.
When to Use This Skill
Automatically activates when working on:
- Creating or modifying routes, endpoints, APIs
- Building controllers, services, repositories
- Implementing middleware (auth, validation, error handling)
- Database operations with Prisma
- Error tracking with Sentry
- Input validation with Zod
- Configuration management
- Backend testing and refactoring
Quick Start
New Backend Feature Checklist
New Microservice Checklist
Architecture Overview
Layered Architecture
HTTP Request
↓
Routes (routing only)
↓
Controllers (request handling)
↓
Services (business logic)
↓
Repositories (data access)
↓
Database (Prisma)
Key Principle: Each layer has ONE responsibility.
See architecture-overview.md for complete details.
Directory Structure
service/src/
├── config/ # UnifiedConfig
├── controllers/ # Request handlers
├── services/ # Business logic
├── repositories/ # Data access
├── routes/ # Route definitions
├── middleware/ # Express middleware
├── types/ # TypeScript types
├── validators/ # Zod schemas
├── utils/ # Utilities
├── tests/ # Tests
├── instrument.ts # Sentry (FIRST IMPORT)
├── app.ts # Express setup
└── server.ts # HTTP server
Naming Conventions:
- Controllers:
PascalCase - UserController.ts
- Services:
camelCase - userService.ts
- Routes:
camelCase + Routes - userRoutes.ts
- Repositories:
PascalCase + Repository - UserRepository.ts
Core Principles (7 Key Rules)
1. Routes Only Route, Controllers Control
// ❌ NEVER: Business logic in routes
router.post('/submit', async (req, res) => {
// 200 lines of logic
});
// ✅ ALWAYS: Delegate to controller
router.post('/submit', (req, res) => controller.submit(req, res));
2. All Controllers Extend BaseController
export class UserController extends BaseController {
async getUser(req: Request, res: Response): Promise<void> {
try {
const user = await this.userService.findById(req.params.id);
this.handleSuccess(res, user);
} catch (error) {
this.handleError(error, res, 'getUser');
}
}
}
3. All Errors to Sentry
try {
await operation();
} catch (error) {
Sentry.captureException(error);
throw error;
}
4. Use unifiedConfig, NEVER process.env
// ❌ NEVER
const timeout = process.env.TIMEOUT_MS;
// ✅ ALWAYS
import { config } from './config/unifiedConfig';
const timeout = config.timeouts.default;
5. Validate All Input with Zod
const schema = z.object({ email: z.string().email() });
const validated = schema.parse(req.body);
6. Use Repository Pattern for Data Access
// Service → Repository → Database
const users = await userRepository.findActive();
7. Comprehensive Testing Required
describe('UserService', () => {
it('should create user', async () => {
expect(user).toBeDefined();
});
});
Common Imports
// Express
import express, { Request, Response, NextFunction, Router } from 'express';
// Validation
import { z } from 'zod';
// Database
import { PrismaClient } from '@prisma/client';
import type { Prisma } from '@prisma/client';
// Sentry
import * as Sentry from '@sentry/node';
// Config
import { config } from './config/unifiedConfig';
// Middleware
import { SSOMiddlewareClient } from './middleware/SSOMiddleware';
import { asyncErrorWrapper } from './middleware/errorBoundary';
Quick Reference
HTTP Status Codes
| Code | Use Case |
|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Server Error |
Service Templates
Blog API (✅ Mature) - Use as template for REST APIs
Auth Service (✅ Mature) - Use as template for authentication patterns
Anti-Patterns to Avoid
❌ Business logic in routes
❌ Direct process.env usage
❌ Missing error handling
❌ No input validation
❌ Direct Prisma everywhere
❌ console.log instead of Sentry
Navigation Guide
Resource Files
Layered architecture, request lifecycle, separation of concerns
Route definitions, BaseController, error handling, examples
Service patterns, DI, repository pattern, caching
Zod schemas, validation, DTO pattern
Sentry init, error capture, performance monitoring
Auth, audit, error boundaries, AsyncLocalStorage
PrismaService, repositories, transactions, optimization
UnifiedConfig, environment configs, secrets
Async patterns, custom errors, asyncErrorWrapper
Unit/integration tests, mocking, coverage
Full examples, refactoring guide
Related Skills
- database-verification - Verify column names and schema consistency
- error-tracking - Sentry integration patterns
- skill-developer - Meta-skill for creating and managing skills
Skill Status: COMPLETE ✅
Line Count: < 500 ✅
Progressive Disclosure: 11 resource files ✅
