backend-principles
Backend Architecture Preferences
Follow the project's existing architecture and explicit task constraints. For a prototype or a small direct endpoint, keep the implementation together until separate responsibilities justify layers. Do not introduce layers just to satisfy a folder pattern.
My Preferred Layered Structure
When a backend needs layers, I prefer Controller / Service / Repository over traditional MVC:
| Layer | Responsibility |
|---|---|
| Controller | HTTP input/output and short orchestration of services |
| Service | One business capability; accesses repositories/gateways in its domain |
| Repository | Data access and persistence queries |
| Use case / workflow | Multi-step orchestration that is complex or reused beyond HTTP |
Within this structure, prefer composing services in a controller or use case when that clarifies the business flow and keeps dependencies acyclic. A direct, acyclic service call is acceptable when it fits the existing architecture; do not add a pass-through orchestration layer solely to prohibit it. Follow established structures rather than restructuring unrelated code.
Extract orchestration when its responsibilities or reuse justify it, not at a fixed line count. Keep transaction ownership, partial failure recovery, and retry behavior explicit in the orchestrating operation; moving calls between layers does not solve consistency.