Backend Dev Guidelines

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](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](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 {
        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](architecture-overview.md) | | Create routes/controllers | [routing-and-controllers.md](routing-and-controllers.md) | | Organize business logic | [services-and-repositories.md](services-and-repositories.md) | | Validate input | [validation-patterns.md](validation-patterns.md) | | Add error tracking | [sentry-and-monitoring.md](sentry-and-monitoring.md) | | Create middleware | [middleware-guide.md](middleware-guide.md) | | Database access | [database-patterns.md](database-patterns.md) | | Manage config | [configuration.md](configuration.md) | | Handle async/errors | [async-and-errors.md](async-and-errors.md) | | Write tests | [testing-guide.md](testing-guide.md) | | See examples | [complete-examples.md](complete-examples.md) |

---

Resource Files

[architecture-overview.md](architecture-overview.md)

Layered architecture, request lifecycle, separation of concerns

[routing-and-controllers.md](routing-and-controllers.md)

Route definitions, BaseController, error handling, examples

[services-and-repositories.md](services-and-repositories.md)

Service patterns, DI, repository pattern, caching

[validation-patterns.md](validation-patterns.md)

Zod schemas, validation, DTO pattern

[sentry-and-monitoring.md](sentry-and-monitoring.md)

Sentry init, error capture, performance monitoring

[middleware-guide.md](middleware-guide.md)

Auth, audit, error boundaries, AsyncLocalStorage

[database-patterns.md](database-patterns.md)

PrismaService, repositories, transactions, optimization

[configuration.md](configuration.md)

UnifiedConfig, environment configs, secrets

[async-and-errors.md](async-and-errors.md)

Async patterns, custom errors, asyncErrorWrapper

[testing-guide.md](testing-guide.md)

Unit/integration tests, mocking, coverage

[complete-examples.md](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 ✅

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: diet103
• Source: diet103/claude-code-infrastructure-showcase
• License: MIT

Install and usage instructions live in the source repository linked above.