backend-code-organisation

Mission

• Keep backend services modular: resources handle transport, managers own business logic, and data access stays isolated.
• Maintain clean dependency flow across modules (service → core → models) to encourage reuse and testability.

Layering Principles

• Resources: Only translate HTTP/storage inputs to domain calls. No database or cross-service logic. Convert SecurityContext early.
• Managers: Encapsulate business rules; coordinate helpers, other managers, workflows, and DAL components. Break cycles by separating read/write responsibilities or introducing controllers.
• Helpers/Services: Reusable integrations (feature flags, external clients). Centralize external service calls to simplify retries and upgrades.
• Repos/DAL/DAO: Keep database interactions single-purpose. Compose multi-step transactions in repos/DAL; keep DAO calls single query.
• Utils/Validators/Transformers: Pure functions and extensions only; avoid hidden state.
• Cache Managers: Inject Redis/Lettuce clients, expose typed get/invalidate helpers.