structure-a-backend-servicelisted

## When to use Reach for this when you are **creating a new service repo**, **adding a feature/module** to an existing one, or **reviewing** whether code is laid out the team way. It answers "where does this file go", "what do I name it", "how is a feature wired", "how do reads vs writes get split", and "how are tests structured". Scope: structure, naming, and wiring — **not** do/don't policy (additive migrations, no `process.env` in business logic, HTTP-layer tests, backward-compat), which lives in the global instructions, cross-referenced inline; follow both. ## Steps Each convention: **portable principle** → **▸ Example (TS/NestJS)** (neutral `listing` domain; `<feature>` / `<Entity>` = rename) → **▸ Other stacks**. Walk these in order when scaffolding. ### 0. Core principle (read first) Organize **by feature, not by layer**. A feature owns its entry points, its read path, its write path, its DTOs, and its events. Keep the transport/entry layer **thin** — it only validates input and delegates. Centralize the **domain model** (persisted entities + domain types) and **shared base classes** so features stay about behavior. Drive everything from **typed config**, never raw env reads. ### 1. Lay out the repo A service has one source tree split into **feature modules**, **centralized domain models**, two tiers of shared code, **config factories**, and **schema migrations** as a top-level sibling of source. ▸ **Example (TS/NestJS)** — copy the shape, swap the domain word