High-Level Design (HLD)

1. Architectural Overview

The system follows Clean Architecture principles to ensure separation of concerns, testability, and independence from frameworks. It utilizes CQRS (Command Query Responsibility Segregation) via the MediatR library to decouple read and write operations, ensuring scalable and maintainable code.

1.1. Project Layers

Domain: Contains core business logic, entities, value objects, domain events, and custom exceptions. It has zero dependencies on other layers or external frameworks.
Application: Defines use cases and coordinates business logic. It contains MediatR Commands, Queries, Handlers, and validation rules (FluentValidation).
Infrastructure: Implements interfaces defined in the Application layer, such as Persistence (EF Core), Identity (JWT), Caching (Redis), and third-party API integrations.
Presentation (WebAPI / AdminAPI): Acts as the entry point for clients, handling HTTP requests, routing, security middlewares, and returning standardized API responses.

2. Technology Stack & Infrastructure

Framework: .NET Core (8/9).
Persistence: Entity Framework (EF) Core with SQL Server / PostgreSQL.
Caching: Redis for distributed session management, refresh token storage, and performance optimization of frequent queries.
Messaging: MediatR for in-process messaging. Extensible to asynchronous message brokers (RabbitMQ/Kafka) for background tasks and microservice communication.
Observability: Serilog for structured logging (sinking to Seq/Elasticsearch) and OpenTelemetry for distributed tracing and monitoring.

3. Core Technical Strategies

3.1. Security & Authentication Architecture

Authentication: Stateless authentication using JWT (JSON Web Tokens).
Token Rotation: Implements a secure Refresh Token mechanism. Refresh tokens are hashed using a token hasher before being stored in the database to prevent leakage.
Single Active Session: Logging in automatically revokes previous active refresh tokens for the user, forcing a single active session.
Authorization: Role-based access control (RBAC) and policy-based authorization managed through claims-based identity.

3.2. Data Management & CQRS

Commands: Handled by MediatR to perform write operations (Create, Update, Delete) and mutate system state. Often wrapped in database transactions via an IUnitOfWork.
Queries: Optimized for read-only operations, often bypassing complex domain models to query the database directly (e.g., using EF Core AsNoTracking or Dapper) and returning flat DTOs (Data Transfer Objects).
Validation: Automated input validation using FluentValidation integrated directly into the MediatR pipeline behavior, ensuring invalid requests are rejected before reaching handlers.

3.3. Caching Strategy (Redis)

Key Convention: Strictly namespaced keys using the pattern {app}:{layer}:{entity}:{action}:{identifier}.
Data Types: Optimized use of Hash for objects, String for simple data, and Set for tracking grouping tags.
Invalidation: Tag-based invalidation ensures that when an entity is updated, all related cached queries are instantly purged.
Mandatory TTL: Every cached item has an explicit Time-To-Live (TTL) to prevent memory leaks and ensure data freshness.

3.4. Error Handling & Response Standard

Global Exception Handling: Centralized middleware/exception filter to catch all unhandled exceptions, preventing stack trace leaks and transforming them into a standard JSON format.
Result Pattern: All API responses wrap data in a standardized ApiResponse<T> or Result<T> object, ensuring consistency in error codes, success markers, and payload structure across the FE/BE bridge.

4. Deployment & CI/CD Strategy

Containerization: Multi-stage Docker builds for Backend APIs to ensure minimal image sizes and consistent runtime environments.
Orchestration: Docker Compose for local development and local testing. Target environments use Kubernetes or managed container services.
CI/CD Pipelines: Automated GitHub Actions / GitLab CI pipelines for restoring over NuGet, building, running unit and integration tests, building Docker images, and deploying to servers.

5. System Flow Diagram (Context & Container)

graph TD
    Client[Client Apps : Web / Mobile] -->|HTTPS / JWT| API[Presentation : WebAPI / AdminAPI]
  
    subgraph "Clean Architecture Core"
        API -->|MediatR Command/Query| App[Application Layer]
        App -->|Uses Entities & Interfaces| Domain[Domain Layer]
    end
  
    subgraph "Infrastructure Layer"
        App -->|Calls Implementations| Infra[Infrastructure Layer]
        Infra -->|EF Core Queries| DB[(SQL Database)]
        Infra -->|StackExchange.Redis| Redis[(Redis Cache)]
        Infra -->|Serilog| Logs[Logging System]
    end

4.9 KiB Raw Blame History