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)

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 ✅