# ardalis/riverbooks architecture

> Architecture diagram of the GitHub repository ardalis/riverbooks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ardalis/riverbooks
- Repository: https://github.com/ardalis/riverbooks

## Overview

##### Project type and purpose
- RiverBooks is a .NET “modular monolith” sample application.
- It demonstrates how to split a single ASP.NET Core Web API into discrete, feature‐oriented modules (Books, Users, OrderProcessing, EmailSending, Reporting), all hosted in one process.

##### File structure
- src/RiverBooks.Web – the ASP.NET Core host (Program.cs, middleware, appsettings).
- src/RiverBooks.* (Books, Users, OrderProcessing, EmailSending, Reporting) – each module follows a consistent layering:
– Contracts (DTOs, Commands, Queries)
– Endpoints / Controllers
– UseCases or Service classes
– Domain (entities, events)
– Infrastructure/Data (EF DbContext & Migrations, repositories, caches)
– Integrations (handlers for domain/integration events)
- src/RiverBooks.SharedKernel – cross-cutting concerns (MediatR behaviors, event dispatcher).
- Tests projects for each module.

##### Relationships & data flows
1. HTTP Request → Web API middleware → Module Endpoint (controller) → MediatR pipeline (validators, behaviors) → Handler / Service
2. Handler → EF Repository → SQL Database ↔ Entities
3. Handler may Publish DomainEvent or IntegrationEvent → SharedKernel dispatches to IntegrationEventHandlers in same process
4. Example: CreateOrderCommand
- OrderProcessing publishes OrderCreatedIntegrationEvent
- Reporting module’s NewOrderCreatedIngestionHandler consumes it to update reports (in-memory or DB)
- OrderProcessing’s SendConfirmationEmailOrderCreatedEventHandler enqueues a SendEmailCommand into EmailSending outbox
5. EmailSendingBackgroundService reads outbox (MongoDB) → MimeKitEmailSender → SMTP server
6. Users module and OrderProcessing module share integration events for user‐address lookup; OrderProcessing caches user addresses in Redis

##### Architectural patterns & design principles
- Modular Monolith – feature‐based modules share a host but remain decoupled
- Onion/Clean Architecture – separation of Contracts (DTOs), Domain, Infrastructure
- CQRS via separate Commands and Queries
- Mediator pattern (MediatR) for in-process messaging
- Outbox pattern (Email outbox in MongoDB) for reliable background processing
- Use of EF Core for data access and migrations per module
- Caching level (Redis) to avoid repeated lookups

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entry
    HTTP["HTTP Request"]:::external
    HTTP -->|"HTTP → API"| WEB

    %% Host
    subgraph "RiverBooks.Web Host" 
        direction TB
        WEB["RiverBooks.Web"]:::host
        WEB --> RequestLoggingMiddleware
        click WEB "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Web"
        RequestLoggingMiddleware["RequestLoggingMiddleware"]:::host
        click RequestLoggingMiddleware "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Web/RequestLoggingMiddleware.cs"
        WEB --> ProgramCs
        ProgramCs["Program.cs"]:::host
        click ProgramCs "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Web/Program.cs"
    end

    %% Shared Kernel
    subgraph "SharedKernel" 
        direction TB
        FluentValidationBehavior["FluentValidationBehavior"]:::shared
        click FluentValidationBehavior "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.SharedKernel/FluentValidationBehavior.cs"
        LoggingBehavior["LoggingBehavior"]:::shared
        click LoggingBehavior "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.SharedKernel/LoggingBehavior.cs"
        DomainEventDispatcher["MediatRDomainEventDispatcher"]:::shared
        click DomainEventDispatcher "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.SharedKernel/MediatRDomainEventDispatcher.cs"
    end
    WEB --> FluentValidationBehavior
    WEB --> LoggingBehavior
    WEB --> DomainEventDispatcher

    %% Books Module
    subgraph "Books Module" 
        direction TB
        BE["BookEndpoints"]:::books
        click BE "https://github.com/ardalis/riverbooks/tree/main/src/RiverBooks.Books/BookEndpoints"
        BS["BookService"]:::books
        click BS "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Books/BookService.cs"
        BR["EfBookRepository"]:::books
        click BR "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Books/Data/EfBookRepository.cs"
        BDB["BookDbContext"]:::books
        click BDB "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Books/Data/BookDbContext.cs"
        BH["BookDetailsQueryHandler"]:::books
        click BH "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Books/Integrations/BookDetailsQueryHandler.cs"
    end
    WEB --> BE
    BE -->|"CreateBookRequest"| BS
    BS -->|"EF Repo"| BR
    BR -->|"DbContext"| BDB

    %% Users Module
    subgraph "Users Module"
        direction TB
        UE["UserEndpoints"]:::users
        click UE "https://github.com/ardalis/riverbooks/tree/main/src/RiverBooks.Users/UserEndpoints"
        CE["CartEndpoints"]:::users
        click CE "https://github.com/ardalis/riverbooks/tree/main/src/RiverBooks.Users/CartEndpoints"
        UH["UseCase Handlers"]:::users
        click UH "https://github.com/ardalis/riverbooks/tree/main/src/RiverBooks.Users/UseCases"
        UR["EfApplicationUserRepository"]:::users
        click UR "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Users/Data/EfApplicationUserRepository.cs"
        UA["EfUserStreetAddressRepository"]:::users
        click UA "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Users/Data/EfUserStreetAddressRepository.cs"
        UDB["UsersDbContext"]:::users
        click UDB "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Users/Data/UsersDbContext.cs"
    end
    WEB --> UE
    WEB --> CE
    UE --> UH
    UH --> UR
    UH --> UA
    UR --> UDB
    UA --> UDB

    %% OrderProcessing Module
    subgraph "OrderProcessing Module"
        direction TB
        OE["OrderEndpoints"]:::orders
        click OE "https://github.com/ardalis/riverbooks/tree/main/src/RiverBooks.OrderProcessing/Endpoints"
        OHC["OrderHandling UseCases"]:::orders
        click OHC "https://github.com/ardalis/riverbooks/tree/main/src/RiverBooks.OrderProcessing/UseCases"
        OR["EfOrderRepository"]:::orders
        click OR "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.OrderProcessing/Infrastructure/Data/EfOrderRepository.cs"
        ODB["OrderProcessingDbContext"]:::orders
        click ODB "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.OrderProcessing/Infrastructure/Data/OrderProcessingDbContext.cs"
        RC["ReadThroughOrderAddressCache"]:::orders
        click RC "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.OrderProcessing/Infrastructure/ReadThroughOrderAddressCache.cs"
        CC["RedisOrderAddressCache"]:::orders
        click CC "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.OrderProcessing/Infrastructure/RedisOrderAddressCache.cs"
    end
    WEB --> OE
    OE --> OHC
    OHC --> OR
    OR --> ODB
    OHC --> CC
    OHC --> RC

    %% EmailSending Module
    subgraph "EmailSending Module"
        direction TB
        EL["ListEmailsEndpoint"]:::email
        click EL "https://github.com/ardalis/riverbooks/tree/main/src/RiverBooks.EmailSending/ListEmailsEndpoint"
        QH["SendEmailCommandHandler"]:::email
        click QH "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.EmailSending/Integrations/QueueEmailForSending/SendEmailCommandHandler.cs"
        BSVC["EmailSendingBackgroundService"]:::email
        click BSVC "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.EmailSending/SendQueuedEmail/EmailSendingBackgroundService.cs"
        OUT["MongoDbEmailOutboxProcessor"]:::email
        click OUT "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.EmailSending/SendQueuedEmail/MongoDbEmailOutboxProcessor.cs"
        SMTPS["MimeKitEmailSender"]:::email
        click SMTPS "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.EmailSending/SendQueuedEmail/MimeKitEmailSender.cs"
        OEntity["EmailOutboxEntity"]:::email
        click OEntity "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.EmailSending/EmailOutboxEntity.cs"
        MongoSettings["MongoDBSettings"]:::email
        click MongoSettings "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.EmailSending/MongoDBSettings.cs"
    end
    WEB --> EL
    QH --> OEntity
    BSVC --> OUT
    OUT --> OEntity
    BSVC --> SMTPS

    %% Reporting Module
    subgraph "Reporting Module"
        direction TB
        RE["ReportEndpoints"]:::reporting
        click RE "https://github.com/ardalis/riverbooks/tree/main/src/RiverBooks.Reporting/ReportEndpoints"
        SRV1["DefaultSalesReportService"]:::reporting
        click SRV1 "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Reporting/DefaultSalesReportService.cs"
        SRV2["TopSellingBooksReportService"]:::reporting
        click SRV2 "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Reporting/TopSellingBooksReportService.cs"
        IH["NewOrderCreatedIngestionHandler"]:::reporting
        click IH "https://github.com/ardalis/riverbooks/blob/main/src/RiverBooks.Reporting/Integrations/NewOrderCreatedIngestionHandler.cs"
    end
    WEB --> RE
    IH --> SRV1
    IH --> SRV2

    %% Inter-module Events
    OHC -->|"OrderCreatedIntegrationEvent"| IH
    OHC -->|"OrderCreatedIntegrationEvent"| QH
    OHC -->|"SendEmailCommand"| QH
    %% Datastores & External
    subgraph "External Systems"
        direction TB
        SQL["SQL Server"]:::external
        Redis["Redis Cache"]:::external
        Mongo["MongoDB"]:::external
        SMTP["SMTP Server"]:::external
    end
    BDB --> SQL
    UDB --> SQL
    ODB --> SQL
    CC --> Redis
    RC --> Redis
    OEntity --> Mongo
    MongoSettings --> Mongo
    SMTPS --> SMTP

    %% Styles
    classDef host fill:#f8f9fa,stroke:#333,stroke-width:1px;
    classDef external fill:#eeeeee,stroke:#999;
    classDef shared fill:#f5c6cb,stroke:#333;
    classDef books fill:#cce5ff,stroke:#333;
    classDef users fill:#d4edda,stroke:#333;
    classDef orders fill:#fff3cd,stroke:#333;
    classDef email fill:#e2e3e5,stroke:#333;
    classDef reporting fill:#d1ecf1,stroke:#333;
```
