add-backend-development

name	add-backend-development
description	Backend API architecture: Clean Architecture, SOLID, DTOs, Services, Repositories, RESTful — stack-agnostic.

Backend Development

Skill for backend API implementation following universal architectural principles.

Use for: Routes/Controllers, Services, DTOs, Domain logic, Data access, Error handling Not for: Frontend (ux-design), Database migrations (database-development), Security (security-audit)

Stack resolution: Consult CLAUDE.md ## Architecture Contract for the framework in use (Express, Fastify, NestJS, Hono, Elysia, etc.). Apply these principles using the framework's idiomatic patterns. The AI already knows each framework's syntax — this skill teaches architecture, not framework tutorials.

Reference: Always consult CLAUDE.md for general project standards.

---

When NOT to Use

• Frontend / UI work — use ux-design or add-frontend-development instead
• Database migrations or schema design — use add-database-development
• Security audits / threat modeling — use add-security-audit
• Pure scripts, CLIs, or non-API code — these patterns target HTTP API services
• Greenfield architecture decisions — use add-backend-architecture to choose structure first
• Project scaffolding — use add-project-scaffolding for initial setup

---

Clean Architecture

domain → application → infrastructure → presentation

Layer	Allowed deps	Content
domain	zero	entities, value objects, enums, types, domain errors
application	domain only	service interfaces, use cases, DTOs
infrastructure	domain, application	repository implementations, external services, config
presentation	all	routes/controllers, middleware, error mapping

Rules:

• Lower layers NEVER import from upper layers
• Domain has ZERO I/O, ZERO framework dependencies — pure business logic
• Application layer defines interfaces (ports) — infrastructure implements them (adapters)
• Presentation layer is the only place aware of HTTP

---

SOLID Principles

• SRP — Each class/module has one reason to change. Services don't handle HTTP. Repositories don't validate.
• OCP — Extend behavior via new implementations, not modifying existing code. Strategy/plugin patterns.
• LSP — Implementations must be substitutable for their interfaces without breaking behavior.
• ISP — Prefer small, focused interfaces. Don't force consumers to depend on methods they don't use.
• DIP — Services depend on interfaces, not implementations. Inject abstractions, never concrete classes.

---

RESTful Standards

Method	Use	Idempotent	Body	Status
GET	read	yes	no	200
POST	create	no	yes	201
PUT	full update	yes	yes	200
PATCH	partial	yes	yes	200
DELETE	remove	yes	no	204

URL rules:

Do:

• Nouns: /users
• Plural: /accounts
• Nested: /accounts/:id/users
• Kebab: /user-roles
• Versioned: /api/v1

Don't:

• Verbs: /getUsers
• Singular: /user
• Mixed case: /userRoles

Params:

• Path → resource id
• Query → filter, pagination, sort, search

Status codes:

Code	Meaning
200	GET, PUT, PATCH ok
201	POST created
204	DELETE ok
400	validation
401	no auth
403	no permission
404	not found
409	conflict

---

Dependency Injection / IoC

EVERY service, repository, and handler MUST be registered in the framework's DI container.

Principles:

• Services receive dependencies via constructor injection
• Depend on interfaces/abstractions, never concrete implementations
• Register all components in the framework's container/module system
• Cross-module dependencies must be explicitly exported/shared

Common DI errors: Unresolved dependency = not registered. Cross-module failure = not exported. Route 404 = module not loaded. Consult framework docs for idiomatic registration.

---

Naming Conventions

File naming (lookup):

Type	Pattern
Controller / Route	kebab.controller.ts or kebab.routes.ts
Service	kebab.service.ts
Repository	PascalRepository.ts
Interface	IPascalRepository.ts
Entity	Pascal.ts
Enum	PascalCase.ts
DTO	PascalDto.ts

Casing rules:

Element	Casing
Files	kebab-case or PascalCase (follow project convention)
Classes	PascalCase
Interfaces	I + PascalCase
DB columns	snake_case
Variables	camelCase

Paths and aliases: Follow the project's existing import aliases and directory structure. Do not invent new aliases — check tsconfig.json paths and existing code.

---

DTOs

DTO naming:

Action	Pattern
create	Create[Entity]Dto
update	Update[Entity]Dto
patch	Patch[Entity]Dto
response	[Entity]ResponseDto
list	[Entity]ListResponseDto
query	[Entity]QueryDto

Rules:

• Input DTOs (create/update/patch) are SEPARATE from response DTOs
• Validation happens at the presentation layer entry point, NEVER in domain
• Use the project's validation library (class-validator, zod, typebox, valibot, joi, etc.)
• Every input field must have validation rules defined
• Response DTOs control what leaves the API — never expose raw entities

---

Services

• Business logic lives here — NO HTTP concepts (no req/res, no status codes, no headers)
• Receives pure data (DTOs or primitives), returns pure data (entities or response DTOs)
• Depends on repository interfaces, not implementations
• Orchestrates domain logic — does not contain persistence logic
• One service per bounded context / feature area

---

Repository Pattern

• Interface defined in application/domain layer
• Implementation in infrastructure layer
• Services depend on the interface, never the implementation
• Returns domain entities, not raw rows or ORM-specific objects
• All data access goes through repositories — no direct DB calls in services

---

Error Handling

Layer	Responsibility
domain	Throw domain-specific errors (NotFoundError, BusinessRuleViolationError, ConflictError). No HTTP concepts.
application	Let domain errors propagate. Add application-level errors if needed (ValidationError).
presentation	Map domain/application errors to HTTP status codes. This is the ONLY layer that knows about HTTP.

Error mapping:

Domain	HTTP
NotFoundError	404
ValidationError	400
UnauthorizedError	401
ForbiddenError	403
ConflictError	409
BusinessRuleViolationError	422

Rule: Services throw domain errors. The presentation layer (middleware, error handler, or framework mechanism) maps them to HTTP responses. Never import HTTP concepts into services.

---

Module / Feature Structure

Organize code by domain/feature, not by technical role. Each feature module contains its own controllers, services, DTOs, and domain logic.

[feature]/
├── dtos/
│   ├── Create[Feature]Dto.ts
│   ├── Update[Feature]Dto.ts
│   └── [Feature]ResponseDto.ts
├── [feature].controller.ts (or routes.ts)
├── [feature].service.ts
└── [feature].module.ts (or index.ts)

DDD-lite principles:

• Entities encapsulate behavior (methods, not just data bags)
• Value objects for concepts with no identity (Money, Email, DateRange)
• Organize by bounded context, not by technical layer
• Keep domain logic in entities/services, not in controllers or repositories

---

Multi-Tenancy

• ALWAYS filter by tenant identifier (e.g., account_id) at repository level
• Tenant ID extracted from auth context (JWT/session), NEVER from request body
• Super Admin may access cross-tenant data — explicitly guard this
• NEVER trust client-provided tenant ID

---

Configuration

• NEVER access env vars directly in services (process.env, Bun.env, etc.)
• ALWAYS use a centralized, typed configuration service/module

Rules:

• Define a configuration interface with typed properties
• Load and validate config at startup
• Inject config service into consumers
• Fail fast on missing required config

---

KISS and YAGNI

• Don't add abstraction layers you don't need yet
• Don't implement patterns the project doesn't use
• Prefer simple, readable code over clever code
• Add complexity only when requirements demand it
• Follow existing project patterns — consistency over personal preference

---

Validation Checklist

RESTful Standards

• URLs use nouns, not verbs (no /getUsers, /createOrder)
• Correct HTTP methods (GET=read, POST=create, PUT=full update, PATCH=partial, DELETE=remove)
• Correct status codes (POST→201, DELETE→204, GET/PUT/PATCH→200)
• URL pattern follows /api/v1/resource

Clean Architecture

• Layer dependencies respected (domain → application → infrastructure → presentation)
• Domain has zero I/O or framework dependencies
• Repositories return domain entities, not DTOs or raw rows

Dependency Injection

• All services/repositories/handlers registered in DI container
• Dependencies injected via constructor, not instantiated directly
• Services depend on interfaces, not concrete implementations
• Cross-module dependencies explicitly exported/shared

DTOs

• Naming follows convention (Create/Update/Patch/Response + EntityDto)
• Validation rules on all input DTO fields
• Response DTOs exist for read operations

Error Handling

• Services throw domain errors, not HTTP exceptions
• Presentation layer maps domain errors to HTTP responses
• Domain errors are descriptive and typed

Multi-Tenancy

• Every query filters by tenant identifier
• Tenant ID extracted from auth context, never from request body
• Client-provided tenant ID never trusted

Configuration

• Uses centralized config service, never direct env var access