Backend Development Elite

A Claude Code skill establishing consistency and best practices across backend services. Covers project structure, API design, error handling, database patterns, authentication, testing, logging, and deployment for modern Node.js/Express/TypeScript backend development.

When to Use This Skill

Choose Backend Dev Elite when:

• You're setting up a new backend service with Node.js/TypeScript
• You want consistent patterns across multiple microservices
• You need production-ready error handling, logging, and monitoring
• You want to establish coding standards for your backend team
• You need guidance on authentication, authorization, and security patterns

Consider alternatives when:

• You need serverless-specific patterns (use an AWS/Azure serverless skill)
• You want frontend development guidance (use a frontend skill)
• You need database-specific optimization (use a database skill)

Quick Start

Copy
# Install the skill
claude install backend-dev-elite

# Set up a new service
claude "Set up a Node.js/Express/TypeScript backend with: project structure, error handling middleware, logging, and health checks"

# Add authentication
claude "Add JWT authentication with refresh tokens to my Express API. Include middleware, route protection, and token rotation"

# Implement a feature
claude "Implement a CRUD API for a products service with validation, pagination, and proper error responses"

Core Concepts

Project Structure

src/
├── controllers/      # Request handling, response formatting
├── services/          # Business logic, orchestration
├── repositories/      # Data access layer
├── middleware/         # Auth, error handling, logging, validation
├── routes/            # Route definitions
├── types/             # TypeScript types and interfaces
├── utils/             # Shared utilities
├── config/            # Environment config, constants
├── validators/        # Request validation schemas
└── index.ts           # App entry point

tests/
├── unit/              # Unit tests (services, utils)
├── integration/       # API endpoint tests
└── fixtures/          # Test data and factories

Layer Responsibilities

Layer	Responsibility	Dependencies
Controller	Parse request, call service, format response	Service layer
Service	Business logic, validation, orchestration	Repository layer
Repository	Data access, queries, transactions	Database
Middleware	Cross-cutting: auth, logging, errors	Config

Error Handling Pattern

Copy
// Custom error classes
class AppError extends Error {
  constructor(
    public statusCode: number,
    public code: string,
    message: string,
  ) {
    super(message);
  }
}

class NotFoundError extends AppError {
  constructor(resource: string) {
    super(404, 'NOT_FOUND', `${resource} not found`);
  }
}

// Error middleware
app.use((err, req, res, next) => {
  const status = err.statusCode || 500;
  res.status(status).json({
    error: { code: err.code, message: err.message },
  });
});

Configuration

Parameter	Type	Default	Description
framework	string	"express"	Framework: express, fastify, nestjs, hono
database	string	"postgresql"	Database: postgresql, mongodb, mysql
orm	string	"prisma"	ORM: prisma, drizzle, typeorm, knex
auth	string	"jwt"	Auth: jwt, session, oauth2, api_key
testing	string	"vitest"	Testing: vitest, jest, mocha

Best Practices

1. Separate controllers from business logic — Controllers handle HTTP concerns (parsing request, formatting response). Services contain business logic. Repositories handle data access. This separation makes each layer testable and replaceable.

2. Use typed error classes — Create a hierarchy of error classes with status codes and machine-readable codes. throw new NotFoundError('User') is clearer than throw new Error('not found') and automatically maps to the right HTTP response.

3. Validate all input at the boundary — Use Zod or Joi to validate request bodies, query parameters, and path parameters in middleware. Reject invalid input early with clear error messages before it reaches your business logic.

4. Log structured JSON — Use a logger like Pino that outputs structured JSON. Include request ID, user ID, and operation context in every log line. Structured logs are searchable and parseable by log aggregation tools.

5. Write integration tests for API endpoints — Unit tests for services are good, but integration tests that make real HTTP requests to your API catch more bugs. Use Supertest with an in-memory database for fast, reliable API tests.

Common Issues

Unhandled promise rejections crash the server — Express doesn't catch async errors by default. Use express-async-errors or wrap every async handler with a try-catch. In Express 5, async error handling is built-in.

Circular dependencies between modules — Usually a sign that your module boundaries are wrong. Extract shared logic into a separate module, or restructure so dependencies flow in one direction (controller → service → repository).

Environment configuration is inconsistent — Use a single config module that validates all environment variables at startup. If a required variable is missing, fail fast with a clear error message rather than crashing later with a cryptic error.