Layered architecture

Layered Architecture

Dependencies point downward only: Controller → Facade → Service → Repository.

Layer responsibilities

• Controller — the HTTP edge: validate the request, delegate, map the result to a DTO + status code.
• Facade — orchestration across services (only when a use case spans several); no data access, no HTTP.
• Service — the business logic and rules; owns the transaction boundary.
• Repository — data access only: queries and persistence.

Do

• Keep controllers thin: parse/validate → call down → map response + correct status code.
• Put business logic in services; open transactions there (on writes).
• Add a facade only when orchestrating multiple services/repositories.
• Return DTOs from controllers; map entities at the boundary.
• Let each layer call only the layer directly below it.
• Use constructor injection.

Don't

• Don't put business logic or if-heavy decisions in controllers.
• Don't return entities from controllers or leak them upward.
• Don't let repositories make business decisions.
• Don't give services HTTP concerns (status codes, request objects).
• Don't skip a layer or call upward.
• Don't add a facade for a simple single-service call.

When reviewing, flag

Logic in controllers · entities returned to clients · repositories with business rules · services handling HTTP · transactions opened at the wrong layer.