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
-
Route: Clean definition, delegate to controller
-
Controller: Extend BaseController
-
Service: Business logic with DI
-
Repository: Database access (if complex)
-
Validation: Zod schema
-
Sentry: Error tracking
-
Tests: Unit + integration tests
-
Config: Use unifiedConfig
New Microservice Checklist
-
Directory structure (see architecture-overview.md)
-
instrument.ts for Sentry
-
unifiedConfig setup
-
BaseController class
-
Middleware stack
-
Error boundary
-
Testing framework
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)
- 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));
- 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'); } } }
- All Errors to Sentry
try { await operation(); } catch (error) { Sentry.captureException(error); throw error; }
- Use unifiedConfig, NEVER process.env
// ❌ NEVER const timeout = process.env.TIMEOUT_MS;
// ✅ ALWAYS import { config } from './config/unifiedConfig'; const timeout = config.timeouts.default;
- Validate All Input with Zod
const schema = z.object({ email: z.string().email() }); const validated = schema.parse(req.body);
- Use Repository Pattern for Data Access
// Service → Repository → Database const users = await userRepository.findActive();
- 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 ✅