Backend Development Guidelines Skill

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 |

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 ✅

Agent Skills: Backend Development Guidelines

Install this agent skill to your local

Skill Files