# kgrzybek/sample-dotnet-core-cqrs-api architecture

> Architecture diagram of the GitHub repository kgrzybek/sample-dotnet-core-cqrs-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kgrzybek/sample-dotnet-core-cqrs-api
- Repository: https://github.com/kgrzybek/sample-dotnet-core-cqrs-api

## Overview

##### Main Components (Layers)
- Presentation/API Layer: Represented by the “SampleProject.API” project. This contains the controllers (e.g., CustomersController.cs, CustomerOrdersController.cs), middleware (like CorrelationMiddleware), configuration files, and the API bootstrap code (Program.cs, Startup.cs etc.).
- Application Layer: Shown in the “SampleProject.Application” directory. This layer organizes the CQRS components (commands, queries, handlers), integration handlers/notifications (such as OrderPlacedNotification, CustomerRegisteredNotificationHandler), validations, and processing modules. It glues the REST API to the domain logic.
- Domain Layer: Found in “SampleProject.Domain”. It contains core business entities such as Customer, Order, Payment, Product with their IDs, business rules, domain events, and shared kernel aspects like MoneyValue. This layer holds the business logic and DDD rules.
- Infrastructure Layer: Detailed in “SampleProject.Infrastructure”. This layer is responsible for data persistence (using EF Core), SQL connections, caching (MemoryCacheStore), email sending, logging, domain event dispatching, integration with Quartz.NET for the Outbox Pattern, and even seed work. It provides the technical implementation behind the abstractions defined in the Application and Domain layers.
- Database: Although only scripts (e.g., InitializeDatabase.sql) are provided, the database is a key external component used by raw SQL read models (via Dapper) and EF Core (write model).

##### Relationships and Interactions
- The API layer accepts REST calls which are then directed to controllers. Controllers invoke corresponding handlers in the Application layer.
- In the Application layer, incoming commands and queries are processed via MediatR and their respective handlers. Commands modify the state (write model) and trigger domain events, while queries retrieve data (read model) using raw SQL.
- The Domain layer enforces business rules, encapsulates business logic, and publishes domain events that may be handled asynchronously.
- The Infrastructure layer implements data access (repositories, EF Core DbContexts) and cross-cutting concerns like caching, logging, email notifications, and outbox processing.
- External flows include the “Cache-Aside” pattern (depicted as a caching component interacting with the Infrastructure layer) and an Outbox component (triggered by Quartz.NET jobs).

##### Architectural Patterns
- CQRS: Clearly separate the command (write) side from the query (read) side. Indicate that the read model is executed via Dapper and raw SQL, while the write side uses Domain Driven Design practices.
- DDD and Domain Events: Highlight domain entities, business rules, and event propagation.
- Integration Patterns: Include components for caching, problem details for API error handling, and the Outbox Pattern for integration and eventual consistency.

##### Specific Technologies and Frameworks
- .NET Core (as the framework for the API)
- MediatR (for command/query and domain event handling)
- Entity Framework Core (for write model persistence)
- Dapper (for executing raw SQL against database views for the read model)
- FluentValidation (for validating requests)
- Quartz.NET (for scheduling outbox process jobs)
- In-memory cache (for caching mechanisms)

##### Design Elements
- Use clear labels for each component (e.g., “API Controllers”, “Command Handlers”, “Domain Entities”, “Repositories”, “Cache”, “Outbox Processor”).
- From the API layer to the Application layer via HTTP requests.
- From the Application layer to the Domain layer when handling business logic.
- From the Domain layer to the Infrastructure layer for persistence and external integrations.

##### Final Recommendations
- Be as detailed as needed: make sure every critical component and dependency is accounted for. Include even auxiliary components like integration tests if beneficial for clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client and Database
    Client("Client Request"):::external
    DB("Database (SQL/Dapper)"):::external

    %% Presentation/API Layer
    subgraph "Presentation/API Layer"
        A4("API Bootstrap"):::presentation
        A3("CorrelationMiddleware"):::presentation
        A1("Customers Controller"):::presentation
        A2("Customer Orders Controller"):::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        B2("Validation (FluentValidation)"):::application
        B1("CQRS Handlers"):::application
        B3("Domain Event Handlers"):::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        C1("Business Entities & Rules"):::domain
        C2("Domain Events & SeedWork"):::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        D1("EF Core Persistence/DbContext"):::infrastructure
        D2("Caching (Cache-Aside)"):::infrastructure
        D3("Email Service"):::infrastructure
        D4("Logging & Domain Event Dispatcher"):::infrastructure
        D5("Outbox Processor (Quartz.NET)"):::infrastructure
    end

    %% Relationships
    Client -->|"sendsHTTPReq"| A4
    A4 -->|"initializes"| A3
    A4 -->|"routesTo"| A1
    A4 -->|"routesTo"| A2

    A1 -->|"validates"| B2
    A2 -->|"validates"| B2
    B2 -->|"triggers"| B1

    B1 -->|"executesCommand"| C1
    B1 -->|"readsDataUsingDapper"| DB
    B1 -->|"logsActivity"| D4
    B1 -->|"checksCache"| D2

    C1 -->|"persistsData"| D1
    D1 -->|"read/writtenTo"| DB

    C1 -->|"emitsEvents"| C2
    C2 -->|"handledBy"| B3

    B3 -->|"sendsEmail"| D3
    B3 -->|"triggersOutbox"| D5
    D5 -->|"processesOutbox"| D1

    %% Click Events - Presentation/API Layer
    click A1 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/blob/master/src/SampleProject.API/Customers/CustomersController.cs"
    click A2 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/blob/master/src/SampleProject.API/Orders/CustomerOrdersController.cs"
    click A3 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/blob/master/src/SampleProject.API/Configuration/CorrelationMiddleware.cs"
    click A4 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/blob/master/src/SampleProject.API/Program.cs"
    click A4 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/blob/master/src/SampleProject.API/Startup.cs"

    %% Click Events - Application Layer
    click B1 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/blob/master/src/SampleProject.Application"
    click B2 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/blob/master/src/SampleProject.Application/Orders/PlaceCustomerOrder/PlaceCustomerOrderCommandValidator.cs"
    click B3 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/blob/master/src/SampleProject.Application/Orders/PlaceCustomerOrder/OrderPlacedNotificationHandler.cs"

    %% Click Events - Domain Layer
    click C1 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/tree/master/src/SampleProject.Domain/Customers"
    click C2 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/tree/master/src/SampleProject.Domain/SeedWork"

    %% Click Events - Infrastructure Layer
    click D1 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/tree/master/src/SampleProject.Infrastructure/Database"
    click D2 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/tree/master/src/SampleProject.Infrastructure/Caching"
    click D3 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/tree/master/src/SampleProject.Infrastructure/Emails"
    click D4 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/tree/master/src/SampleProject.Infrastructure/Logging"
    click D5 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/tree/master/src/SampleProject.Infrastructure/Processing/Outbox"
    click D5 "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/tree/master/src/SampleProject.Infrastructure/Quartz"

    %% Click Events - Database Scripts
    click DB "https://github.com/kgrzybek/sample-dotnet-core-cqrs-api/blob/master/src/InitializeDatabase.sql"

    %% Styles
    classDef presentation fill:#f9c74f,stroke:#000,stroke-width:1px;
    classDef application fill:#90be6d,stroke:#000,stroke-width:1px;
    classDef domain fill:#f94144,stroke:#000,stroke-width:1px;
    classDef infrastructure fill:#577590,stroke:#000,stroke-width:1px;
    classDef external fill:#90caf9,stroke:#000,stroke-width:1px;
```
