add brain

.brain/03. Design/01. HighLevelDesign/System_Design.md

@@ -0,0 +1,74 @@
+# 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)
+
+```mermaid
+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
+```