# 010106 Backend Architecture

> Backend architecture — typed errors, structured API responses, domain modules, service/repository layering, env sanitization, and FK protection.

- Skill: `natuleadan/010106-backend-architecture` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add natuleadan/010106-backend-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/natuleadan/010106-backend-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: natuleadan (https://skillmd.com/u/natuleadan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/natuleadan/010106-backend-architecture

---


# Backend Architecture Standards

## Overview

Coding standards for backend module structure, error handling, and API response patterns.

## Quick Reference

### Module Structure

Standard module files:
- `types.ts` — Interfaces and types
- `schemas.ts` — Validation schemas (e.g., Zod)
- `constants.ts` — Domain constants
- `repository.ts` — Data access (queries + mutations)
- `service.ts` — Business logic
- `actions.ts` — Server Action entry points
- `utils.ts` — Pure helper functions

### Error Handling

- Use typed error classes: `HttpError` → `ValidationError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`
- Structured API response: `{ data, error: { code, message, traceId } }`
- Error codes follow `PREFIX_CATEGORY_INDEX` (e.g., `VAL_000_001`)
- Database errors mapped to user-friendly messages

### Environment Variables

- Centralized `env.ts` with `requireEnv()` for validation
- All env vars accessed through this file only
- Logs sanitized before output (strip secrets, emails, tokens)

## References

- [Error Handling](references/error-handling.md)
- [Module Structure](references/module-structure.md)
- [Error Codes Format](references/error-codes-format.md) — Structured error codes, prefix conventions, traceId
- [Foreign Key Chains](references/foreign-key-chains.md) — Multi-currency FK chain, translation FK chain, FK protection for admin DELETE