--- description: Documentation standards for backend TypeScript code (JSDoc comments) globs: backend/src/**/*.ts alwaysApply: false --- # Backend documentation conventions Every new or modified backend file must include clear JSDoc comments so maintenance stays easy (Spring Boot–style readability). ## Required comments 1. **File / module** — One block at the top describing the layer and responsibility: - `models/` → entity mapped to a DB table - `dto/` → API/query projection (not a full entity) - `repositories/` → data access (SQL) - `services/` → business logic - `controllers/` → HTTP handlers (thin; delegate to services) - `middleware/` → Express pipeline hooks ## Layer dependencies (Spring Boot style) - **Controller → Service only** — never import repositories or run SQL in controllers. - **Service → Repository (+ other services when needed)** — business logic, decryption, orchestration. - **Repository → Models / DTO row types** — SQL and data mapping only; no HTTP concerns. - **Exceptions kept as-is** when justified: background jobs (`depositMonitorService`), `authService` reading `settingsRepository` directly for token policy, `middleware` calling `authService.verifyToken`. 2. **Every exported function** — JSDoc with: - What it does (one sentence) - `@param` for non-obvious parameters - `@returns` when the return value is not obvious - `@throws` when the function throws domain errors 3. **Non-exported helpers** — Comment when logic is non-obvious (crypto, blockchain, ledger locking, etc.). 4. **Interfaces / types in models & dto** — Brief description of what they represent and which table/view they map to. ## Style - Write comments in **English** (matches existing codebase). - Prefer **why** over **what** when the code is self-explanatory. - Do not restate obvious one-liners (`return rows[0] || null` needs no comment). - Keep comments up to date when changing behavior. ## Example ```typescript /** * Finds a user by email hash (used for login and uniqueness checks). * @param emailHash SHA-256 hash of normalized email * @returns User row or null if not found */ export async function findByEmailHash(emailHash: string): Promise { ```