Claprec: Inside the Architecture - N-Tier, decoupling, microservices (2/6)

Series Roadmap

Product Overview (1/6)
Architecture: N-Tier Design, Decoupling, and Microservices (2/6)
Frontend: Angular SSR, NgRx, and OpenAPI Integration (3/6)
Machine Learning in Practice (4/6)
Database Design and Data Modeling (5/6)
Engineering Tradeoffs: Limited Time vs. Ideal Architecture (6/6)

System Architecture Overview

The application is deployed within a Dockerized environment consisting of six containers:

3 Backend Microservices: API (the main one), Real-time, and Views-processing.
1 Frontend Container.
Infrastructure: Microsoft SQL Server (MSSQL) and RabbitMQ message broker.

To visualize the backend architecture, the following animation illustrates the layers and some of their dependencies.

This article focuses specifically on the architectural decisions and patterns implemented within the backend microservices.

Main Microservice

The main microservice acts as the primary backend service. It follows an N-Tier Architecture, where the depth of the stack varies based on the complexity of the functionality being implemented.

Architectural Layers

To ensure strict Separation of Concerns (SoC) and adherence to the DRY (Don't Repeat Yourself) principle, the architecture defines three distinct stack depths:

Entity Mutations / CRUD (8 Layers):
Higher CRUD Controller -> Base Higher CRUD Controller -> Service -> Base Higher CRUD Service -> Validation -> BusinessRule -> Base Service -> Repository
Database-Stored Enums (6 Layers):
Db Enum Controller -> Base Db Enum Controller -> Service -> Base Db Enum Service -> Base Service -> Repository
Generic Functionality (4 Layers):
Controller -> Service -> Base Service -> Repository

The "HigherCrud" System: Solving Multiple Inheritance

Entities often share common behaviors: existence checks, validation logic, and standard business rules. Ideally, this would be implemented via multiple inheritance.

However, C# does not support multiple class inheritance, unlike C++.

To compose shared behaviors with a minimal code duplication, I implemented a solution inspired by Unix file permissions (bitwise flags).

The Bitwise Controller Hierarchy

I categorized CRUD operations into "Pure" base controllers, assigning each a specific level (bit value):

Level 0 (ReadBasic): GET paginated list and GET specific entity.
Level 1 (ReadCalculated): Inherits Level 0 + more extensive GET endpoint for calculated properties.
Level 2 (Delete): Inherits Level 0 + DELETE endpoint (includes existence checks).
Level 4 (Create): Inherits Level 0 + POST endpoint (includes validation).
Level 8 (Update): Inherits Level 0 + PATCH endpoint (includes existence checks and validation).

// Level0AbstractHigherCrudController.cs

// Level 0 (Read Basic)

public abstract class Level0AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> :
    AbstractBaseHigherCrudController,
    ILevel0AbstractHigherCrudController<TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>
    where T : class
    where TDtoPlain : class
    where TDtoRelated : TDtoPlain
    where TSearch : BaseSearchDto
{
    private readonly ILevel0AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> _baseHigherCrudServiceLevel0;

    protected Level0AbstractHigherCrudController(ILevel0AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> baseHigherCrudServiceLevel0)
    {
        _baseHigherCrudServiceLevel0 = baseHigherCrudServiceLevel0;
    }

    [SwaggerOperation("Level 0", "Get paginated entities")]
    [HttpGet]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status204NoContent)]
    public virtual async Task<ActionResult<PaginatedResponse<TDtoRelated>>> Get([FromQuery] TSearch search)
    {
        return await _baseHigherCrudServiceLevel0.GetPaginated(search, FormReqURLBuilder());
    }

    [SwaggerOperation("Level 0", "Get an entity")]
    [HttpGet(GET_BY_ID_ROUTE)]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status404NotFound, Type = typeof(DtoError))]
    public virtual async Task<ActionResult<TDtoRelated>> GetById(TPrimaryKey id)
    {
        return await _baseHigherCrudServiceLevel0.GetById(id);
    }
}

// Level1AbstractHigherCrudController.cs

// Level 1 (Read Calculated)

public abstract class Level1AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TDtoCalculated, TPrimaryKey, TSearch> :
    Level0AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>,
    ILevel1AbstractHigherCrudController<TDtoPlain, TDtoRelated, TDtoCalculated, TPrimaryKey, TSearch>
    where T : class
    where TDtoPlain : class
    where TDtoRelated : TDtoPlain
    where TDtoCalculated : TDtoPlain
    where TSearch : BaseSearchDto
{
    private readonly ILevel1AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TDtoCalculated, TPrimaryKey, TSearch> _level1AbstractBaseHigherCrudService;

    protected Level1AbstractHigherCrudController(ILevel1AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TDtoCalculated, TPrimaryKey, TSearch> level1AbstractBaseHigherCrudService)
        : base(level1AbstractBaseHigherCrudService)
    {
        _level1AbstractBaseHigherCrudService = level1AbstractBaseHigherCrudService;
    }

    [SwaggerOperation("Level 1", "Get an entity (detailed)")]
    [HttpGet(GET_CALCULATED_BY_ID_ROUTE)]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status404NotFound, Type = typeof(DtoError))]
    public virtual async Task<ActionResult<TDtoCalculated>> GetCalculatedById(TPrimaryKey id)
    {
        return await _level1AbstractBaseHigherCrudService.GetCalculatedById(id);
    }
}

// Level2AbstractHigherCrudController.cs

// Level 2 (Delete)

public abstract class Level2AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> :
    Level0AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>,
    ILevel2AbstractHigherCrudController<TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>
    where T : class
    where TDtoPlain : class
    where TDtoRelated : TDtoPlain
    where TSearch : BaseSearchDto
{
    private readonly ILevel2AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> _level2AbstractBaseHigherCrudService;

    protected Level2AbstractHigherCrudController(ILevel2AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> level2AbstractBaseHigherCrudService)
        : base(level2AbstractBaseHigherCrudService)
    {
        _level2AbstractBaseHigherCrudService = level2AbstractBaseHigherCrudService;
    }

    [SwaggerOperation("Level 2", "Delete an entity")]
    [HttpDelete(REMOVE_BY_ID_ROUTE)]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status404NotFound, Type = typeof(DtoError))]
    public virtual async Task RemoveById(TPrimaryKey id)
    {
        await _level2AbstractBaseHigherCrudService.RemoveById(id);
    }
}

// Level4AbstractHigherCrudController.cs

// Level 4 (Create)

public abstract class Level4AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TInsert, TInsertValidation> :
    Level0AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>,
    ILevel4AbstractHigherCrudController<TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TInsert>
    where T : class
    where TDtoPlain : class
    where TDtoRelated : TDtoPlain
    where TSearch : BaseSearchDto
{
    private readonly ILevel4AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TInsert> _level4AbstractBaseHigherCrudService;

    protected Level4AbstractHigherCrudController(ILevel4AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TInsert> level4AbstractBaseHigherCrudService)
        : base(level4AbstractBaseHigherCrudService)
    {
        _level4AbstractBaseHigherCrudService = level4AbstractBaseHigherCrudService;
    }

    [SwaggerOperation("Level 4", "Create an entity")]
    [HttpPost]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status400BadRequest, Type = typeof(List<DtoValidationError>))]
    [SwaggerResponse(StatusCodes.Status422UnprocessableEntity, "Unprocessable Entity", typeof(List<DtoValidationError>))]
    public virtual async Task<ActionResult<TDtoPlain>> Insert([FromBody] TInsert insert)
    {
        return await _level4AbstractBaseHigherCrudService.Insert(insert);
    }
}

// Level8AbstractHigherCrudController.cs

// Level 8 (Update)

public abstract class Level8AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TUpdate, TUpdateValidation> :
    Level0AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>,
    ILevel8AbstractHigherCrudController<TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TUpdate>
    where T : class
    where TDtoPlain : class
    where TDtoRelated : TDtoPlain
    where TSearch : BaseSearchDto
{
    private readonly ILevel8AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TUpdate> _level8AbstractBaseHigherCrudService;

    protected Level8AbstractHigherCrudController(ILevel8AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TUpdate> level8AbstractBaseHigherCrudService)
        : base(level8AbstractBaseHigherCrudService)
    {
        _level8AbstractBaseHigherCrudService = level8AbstractBaseHigherCrudService;
    }

    [SwaggerOperation("Level 8", "Update an entity")]
    [HttpPatch(UPDATE_BY_ID_ROUTE)]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status400BadRequest, Type = typeof(List<DtoValidationError>))]
    [SwaggerResponse(StatusCodes.Status404NotFound, Type = typeof(DtoError))]
    [SwaggerResponse(StatusCodes.Status422UnprocessableEntity, "Unprocessable Entity", typeof(List<DtoValidationError>))]
    public virtual async Task<ActionResult<TDtoPlain>> UpdateById(TPrimaryKey id, [FromBody] TUpdate update)
    {
        return await _level8AbstractBaseHigherCrudService.UpdateById(id, update);
    }
}

Composing Controllers

Developers can inherit directly from "Pure" controllers for simple endpoints. By summing these values, we create "Mix" controllers that combine functionalities. A specific entity controller simply inherits from the appropriate Mix base class.

Example: An entity requiring ReadBasic (0), Create (4) and Delete (2) functionality inherits from Level 6.
Full CRUD: An entity requiring all operations inherits from Level 15 (0+1+2+4+8).

Implementation Logic

Since C# does not support multiple inheritance, we cannot simply inherit Level2 and Level4 simultaneously to create Level6. Instead, the "Mix" classes pre-chain the inheritance hierarchy to simulate this composition.

For example, Level 13 (Update + Create + Read Calculated + Read Basic) is implemented by inheriting from Level 5, which in turn inherits from Level 1, which inherits from Level 0. This linear chain aggregates the features cumulatively:

Level 0 provides ReadBasic capabilities
Level 1 inherits Level 0 (ReadBasic) and adds ReadCalculated capabilities.
Level 5 inherits Level 1 and adds Create capabilities.
Level 13 inherits Level 5 and adds Update capabilities.

Admittedly, this approach requires pre-defining these specific "Mix" classes in the base library, resulting in a certain degree of code duplication within the foundational layer. However, this is a necessary compromise to bypass the language's constraints. It is a trade-off that pays off significantly in Developer Experience (DX). The result is an elegant and intuitive interface: developers simply inherit from the specific "Level" class they desire, and the complex composition of behaviors is handled automatically.

Service Layer & Extensibility

The Service Layer mirrors the controller hierarchy precisely, ensuring that every "Level" in the API stack has a corresponding logical backbone (Base Higher CRUD Service). This parallel structure handles the validation pipeline, business rules and other concerns.
To ensure flexibility, the architecture relies on polymorphism: core operations are implemented as virtual methods, allowing an override of specific behaviors - such as injecting custom logic before a save - without disrupting the inheritance chain.
Furthermore, if an entity requires functionality outside the standard CRUD scope, the solution is intuitive: simply define a new method in the Controller and a corresponding one in the Service, effortlessly adding the required custom functionality.

Practical Example: "Product" Entity

To implement full CRUD for a "Product" entity:

Inherit HigherBaseCrudController (Level 15).
Inherit HigherBaseCrudService (Level 15).
Define Format and Business Rule Validators.
Define DTOs.

// ProductController.cs

[ApiController]
[Route("")]
public class ProductController :
    Level15AbstractHigherCrudController<Product, DtoPlainProduct, DtoRelatedProduct, DtoCalculatedProduct, long, SearchDtoProduct, InsertDtoProduct, UpdateDtoProduct, IAbstractValidation<InsertDtoProduct>, IAbstractValidation<UpdateDtoProduct>>
{
    private readonly IHigherCrudServiceProduct _higherCrudServiceProduct;

    public ProductController(
        IHigherCrudServiceProduct higherCrudServiceProduct
    ) : base(higherCrudServiceProduct)
    {
        _higherCrudServiceProduct = higherCrudServiceProduct;
    }

    // ...
}

Result: The system scaffolds 6 endpoints automatically (3 GET, 1 POST, 1 DELETE, 1 PATCH).

Validation Pipeline

The validation layer optimizes resource usage by preventing unnecessary database calls.

Format Validator: Checks data constraints (e.g., string length < 255). Returns HTTP 400 on failure.
Business Rule Validator: Checks database constraints (e.g., unique email). Returns HTTP 422 on failure.

Optimization:

If Format Validation fails, the pipeline short-circuits, and Business Rule Validation (DB hit) is skipped.
Business Rule Validation fails fast (returns immediately on first error) to minimize DB load.
Error responses share a unified interface, simplifying frontend error parsing.

// AbstractValidation.cs

public abstract class AbstractValidation<T> : IAbstractValidation<T>
{
    private readonly List<IValidatorWithException<T>> _validators = new();

    public async Task Validate(T t)
    {
        foreach (var validator in _validators)
        {
            var validationResult = await validator.ValidateAsync(t);

            if (!validationResult.IsValid)
            {
                validator.ThrowException(validationResult.Errors);
            }
        }
    }

    protected void AddValidatorsInOrder(params IValidatorWithException<T>[] validators)
    {
        foreach (var validator in validators)
        {
            _validators.Add(validator);
        }
    }
}

// AbstractFormatValidatorWithException.cs

public abstract class AbstractFormatValidatorWithException<T> : AbstractValidator<T>, IFormatValidatorWithException<T>
{
    void IValidatorWithException<T>.ThrowException(List<ValidationFailure> validationFailures)
    {
        throw new ValidationException(validationFailures);
    }
}

// AbstractBusinessRuleValidatorWithException.cs

public abstract class AbstractBusinessRuleValidatorWithException<T> : AbstractValidator<T>, IBusinessRuleValidatorWithException<T>
{
    protected AbstractBusinessRuleValidatorWithException()
    {
        RuleLevelCascadeMode = CascadeMode.Stop;
    }

    void IValidatorWithException<T>.ThrowException(List<ValidationFailure> validationFailures)
    {
        throw new BusinessRuleException(validationFailures);
    }
}

Data Mapping & API Standards

AutoMapper & PATCH Semantics:
Implementing partial updates (PATCH) with AutoMapper presents a challenge: distinguishing between an intentional null update and an ignored field.

Scenario: An entity has an optional description. Updating it to null (to clear it) is indistinguishable from "do not update" if AutoMapper ignores nulls.
Solution: Manual mapping is used for specific edge cases to ensure correctness. Alternatively, switching to PUT (full replacement) solves the ambiguity but increases payload size.

Infrastructure:

Swagger: Configured with versioning and Bearer JWT authentication (including session tracking).
Database Enums: Enums are defined in a dedicated backend layer for seeding, storing byte IDs, and rendering string values (prettified for UI).
SMTP: Email sending is handled by a thread-safe background service (Queue-based) to prevent SMTP failures during concurrent requests.
NSFW filter: Applied to publicly visible media; skipped for private uploads (e.g., identity verification).

Testing & Performance

The backend includes Unit and Integration tests.

Performance Optimization: Integration test execution time was reduced by 91.1% (from 8.3 minutes to 44.2 seconds). A detailed IEEE-format breakdown is available here.

Views-Processing Microservice

This microservice is designed for data analytics and post-processing.

Event-Driven: Listens for view events thrown by the Main microservice via RabbitMQ.
Data Storage: Persists metadata (creation date, user ID, entity ID, IP address etc.) into a dedicated MSSQL database.
Purpose: Aggregates engagement data (views on businesses, products, reviews, comments) for analytical insights.

Real-Time Microservice

Built on SignalR, this microservice manages live connectivity and user presence with a strong focus on resource optimization.

Performance & Resource Management

Memory Footprint: Optimized to utilize 300-350MB of RAM for 5,000+ concurrent users during stress tests.
User Presence: Activity status is stored as a bit flag in the relational database.
Storage: Uses ConcurrentDictionary (static in-memory) for connection management, resolving thread-safety issues encountered with standard dictionaries.

// ChatHub.cs

// user.Id, dictionary of: connectionId, listenToUserId
private static readonly ConcurrentDictionary<long, ConcurrentDictionary<string, long>> _connectedUsersForIndividualChat = new();

Resilience Strategy

Because state is stored in RAM, service failure leads to temporary incoherent IsActive status.

Solution: Rather than implementing complex snapshot persistence, the system relies on the frontend's auto-retry connection strategy. Upon reconnection, the state self-corrects. This trades temporary inconsistency for implementation simplicity and lower overhead.

Bandwidth Optimization

To minimize WebSocket traffic:

Counts vs. Payloads: Only unread notification/chat counts are pushed to clients, not the full objects.
Chat Messages: Messages are only exchanged live when a user explicitly joins a specific chat room.
Queue Management: No message accumulation occurs when a user is disconnected; counts update only upon connection.

Architecture

Repository pattern: Uses Entity Framework via the Repository pattern for data access.
Integration: consumes RabbitMQ events from the main microservice (e.g., new notifications for: replies, reviews etc.).

What's Next

With the backend architecture solidly in place - from N-Tier layers to bitwise CRUD composition - the foundation is set. Next, we'll shift to the client side.

Join me in Claprec: Frontend - Angular, NgRx, and OpenAPI (3/6), where I transition from Next.js to Angular's opinionated structure. We will tackle complex challenges including real-time chat scroll management, architecting reusable pagination, handling recursive state with NgRx, and enforcing type safety via Contract-First Design.

Questions or thoughts on the architecture? Drop a comment - I'd love to hear!

推荐订阅源

DEV Community