Layers interactions and naming conventions

Basic rules

To ensure proper code structure and maintain clear separation of layers, the following rules are applied. These conventions help developers define and maintain well-organized and independent layers.

Contract

Code-first

This method generates the OpenAPI Specification (OAS) from endpoints defined in the code. It is suitable when there is no existing contract, and the development team prefers to derive the contract directly from the code (e.g., controllers).

• Annotations: Use annotations provided by Swashbuckle NuGet packages to generate accurate specification files
• Models: Prefer using record types for API body models (requests/responses) to reduce boilerplate code and simplify implementation
• Status Codes: Ensure all possible status codes returned by endpoints are explicitly mapped in the code and included in the OAS file using SwaggerResponse annotations. These can also be applied at the controller level for cleaner code
• This approach is generally preferred for its simplicity and flexibility

Contract first

When an existing contract (OAS) is available, a code generation tool can be used to:

• Generate controllers, DTOs, and controller service interfaces
• Implement and update the generated code when the contract evolves

The project includes a code generator that processes specification files to create developer-approved code, incorporating best practices.

Layers, mapping and naming

Regardless of the chosen approach, the following naming conventions and mapping rules ensure consistency:

Naming Conventions (Suffixes):

• Presentation layer
  • Request / Response for top-level objects
  • Dto for nested models within requests and responses
• Application laye
  • Model / Result for data representations outside the domain layer (e.g., aggregations, projections)
• Domain layer
  • No suffix is used for domain entities

Mapping and Layer Interactions

• Creating application layer classes (e.g., for queries/commands) is optional.
• Passing domain entities directly to the presentation layer is allowed but discouraged for presentation exposure. Only presentation layer objects should be exposed.
• Application layer models should be created in cases of complex queries/commands or when additional abstractions are necessary. The decision depends on complexity and team preference.