🧭 Architecture Guidelines for Backend Application

These guidelines define how to structure and organize the backend architecture for the project using NestJS, TypeORM, and clean layering principles.

---

This document also includes the conventions for organizing the application structure, including module layout, naming rules, and folder hierarchy.

modular monolith conventions.

---

🧱 Project Layers

1. Entity Layer

• Contains ORM entities (TypeORM @Entity() classes).
• Entities model the database structure.
• Only internal logic; no external dependencies like DTOs.

2. DTO Layer

a) Domain DTOs

• Used within use-cases and services.
• Belong to application/domain layer.
• Must not depend on API/CLI DTOs.
• May depend on Entities, but not on presentation-level DTOs.
• Mapping into Domain DTOs is done via non-static mappers, not fromEntity() inside DTO.

b) API/CLI DTOs (Presentation DTOs)

• Presentation-specific output format (API, CLI, etc).
• Belong to the presentation layer.
• Can be mapped via presentation mappers (non-static).
• Lower layers may depend on upper layers, but the domain layer must never depend on higher-level concerns.

3. Entity Service Layer

• Contains logic for a single entity (e.g., UserService).

• Should interact only with the corresponding repository.

• Can return both:

  • Entity — for use-case services
  • Domain DTO — for API/CLI usage (only if simple)

• Must not depend on other services or use-cases.

4. Use-Case Service Layer

• Represents a single business scenario (e.g., CreateUserService, GetUserWithPostsService).
• Should typically expose only one public method — usually named run(...).
• In more complex cases where multiple related operations are needed, it is acceptable to define several clearly named public methods instead of using run(...).
• Can depend on multiple entity services, repositories, or infrastructure services.
• Returns a Domain DTO.
• Does not return Entity directly.

5. Presentation Layer (Controller, CLI)

• Depends only on use-case services or entity services (for simple reads).
• Receives or returns presentation-specific DTOs.
• Must never operate on Entity directly.
• Performs mapping to and from presentation DTOs using non-static mappers.

6. Infrastructure Layer

• Services to interact with email, queues, external APIs, files, etc.
• Can be injected into use-case services.

---

📦 Mapping Conventions

Source	Target	How
Entity	Domain DTO	via dedicated mapper
Domain DTO	API/CLI DTO	via dedicated mapper

📌 Do not place fromEntity() or fromDomain() inside DTOs, and avoid doing mapping inside services as well. Use dedicated mapper classes to convert between layers.

🧩 Naming and grouping of mappers (e.g., one vs many) — left to the team’s discretion.

---

✅ Best Practices

• Keep Entity Services focused per entity.
• Use Use-Case Services for all orchestrations across domains.
• Structure code to allow reuse across API, CLI, cron, etc.
• Prefer explicit DTOs at every boundary.
• Maintain one scenario = one use-case service with a single .run() method.
• Avoid returning Entity from any service that crosses layers.
• Domain DTOs may depend on Entity, but never on presentation DTOs.
• API/CLI DTOs may depend on Domain DTOs, but never the other way around.
• Entity Services must not depend on Use-Case Services or other Entity Services.
• Use-case services can depend on multiple Entity Services and Repositories.
• Controllers and CLI commands must never see Entities.
• Use dedicated mapper classes instead of placing logic inside DTOs.

---

📁 Suggested Folder Structure

src/
  users/
    entities/
      user.entity.ts
    services/
      user.service.ts
    use-cases/
      get-user.service.ts
    dto/
      domain/                # Domain DTOs (used in use-cases)
        user-domain.dto.ts
      presentation/          # API/CLI DTOs
        user-api-response.dto.ts
        user-cli-response.dto.ts
    mappers/
      user.mapper.ts         # Contains conversion logic between layers
    enums/
      user-role.enum.ts
    controllers/
      user.controller.ts

📌 Notes:

• Domain DTOs are stored under dto/domain/ — they are part of the application layer.
• Presentation-layer DTOs are stored under dto/presentation/ — used in API/CLI.
• Each module (e.g., users/) is a self-contained feature with clearly organized responsibilities.
• Mapping logic is implemented in mappers/ folder per feature.

---

🔚 Summary

This architecture encourages:

• Separation of concerns
• Clear ownership of logic
• Readable, testable, and maintainable code

Following these guidelines will help create a codebase that is easy to extend, open to the community, and maintainable in the long term.