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

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)

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

2. All Controllers Extend BaseController

3. All Errors to Sentry

4. Use unifiedConfig, NEVER process.env

5. Validate All Input with Zod

6. Use Repository Pattern for Data Access

7. Comprehensive Testing Required

Common Imports

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 ✅