Backend Development Guidelines
Purpose
Establish consistency and best practices across backend services using modern Node.js/Express/TypeScript patterns.
Written for Node.js/Express/TypeScript with Prisma and Sentry. Different stack? Adapt the architectural principles - see CLAUDE_INTEGRATION_GUIDE.md in the repo root.
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
| Need to... | Read this |
|---|
| Understand architecture | architecture-overview.md |
| Create routes/controllers | routing-and-controllers.md |
| Organize business logic | services-and-repositories.md |
| Validate input | validation-patterns.md |
| Add error tracking | sentry-and-monitoring.md |
| Create middleware | middleware-guide.md |
| Database access | database-patterns.md |
| Manage config | configuration.md |
| Handle async/errors | async-and-errors.md |
| Write tests | testing-guide.md |
| See examples | complete-examples.md |
Resource Files
architecture-overview.md
Layered architecture, request lifecycle, separation of concerns
routing-and-controllers.md
Route definitions, BaseController, error handling, examples
services-and-repositories.md
Service patterns, DI, repository pattern, caching
validation-patterns.md
Zod schemas, validation, DTO pattern
sentry-and-monitoring.md
Sentry init, error capture, performance monitoring
middleware-guide.md
Auth, audit, error boundaries, AsyncLocalStorage
database-patterns.md
PrismaService, repositories, transactions, optimization
configuration.md
UnifiedConfig, environment configs, secrets
async-and-errors.md
Async patterns, custom errors, asyncErrorWrapper
testing-guide.md
Unit/integration tests, mocking, coverage
complete-examples.md
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 ✅