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
• Module Structure
• Error Codes Format — Structured error codes, prefix conventions, traceId
• Foreign Key Chains — Multi-currency FK chain, translation FK chain, FK protection for admin DELETE