# aspnetrun/run-aspnetcore-microservices architecture

> Architecture diagram of the GitHub repository aspnetrun/run-aspnetcore-microservices, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aspnetrun/run-aspnetcore-microservices
- Repository: https://github.com/aspnetrun/run-aspnetcore-microservices

## Overview

Based on our analysis, this repository is an e-commerce microservices project built with .NET. Its purpose is to serve as a real-world implementation of microservices using Domain-Driven Design (DDD), Command‐Query Responsibility Segregation (CQRS), and both synchronous (via gRPC) and asynchronous (via RabbitMQ and MassTransit) inter-service communication. It also includes an API Gateway using YARP to route external calls, a Web UI for the shopping experience, and shared libraries (BuildingBlocks) for cross-cutting concerns.

##### Key Components
- API Gateway: Represent the YarpApiGateway microservice which uses YARP reverse proxy patterns (routing, clustering, transformations, and rate limiting).
- Web UI: The Shopping.Web (WebApps/Shopping.Web) that provides the front-end user interface using Razor pages and Bootstrap.
- Microservices:
– Catalog Microservice (Catalog.API): Implements minimal APIs using a vertical slice architecture. It handles product-related operations and uses a document DB (Marten on PostgreSQL) along with libraries like Carter and MediatR.
– Basket Microservice (Basket.API): A RESTful API that utilizes Redis for distributed caching and also communicates with the Discount microservice over gRPC. It implements patterns like Proxy, Decorator, and Cache-Aside. It also publishes BasketCheckout events to RabbitMQ via MassTransit.
– Discount Microservice (Discount.Grpc): A gRPC server built with ASP.NET. It exposes services over protobuf and uses SQLite via Entity Framework Core.
– Ordering Microservice: This is split into multiple projects (Ordering.API, Ordering.Application, Ordering.Domain, Ordering.Infrastructure) implementing DDD with CQRS patterns. It consumes events (like BasketCheckout) via MassTransit-RabbitMQ and interacts with a SQL Server database.
- Building Blocks: Shared libraries (within the BuildingBlocks directory) that include messaging, CQRS abstractions, validation, logging, and exception handling.
- Messaging Infrastructure: RabbitMQ (with MassTransit abstractions) which is used for async event-driven communication between microservices.
- Databases and External Services: Include relational databases (PostgreSQL, SQL Server, SQLite) and distributed caching (Redis).

##### Relationships and Interactions
- From the API Gateway, route calls to the Web UI and the respective microservices.
- That the Web UI (Shopping.Web) calls the API Gateway (possibly using Refit HttpClientFactory), which in turn routes requests to services on Catalog, Basket, Ordering, etc.
- That Basket API makes synchronous gRPC calls to the Discount.Grpc service.
- Asynchronous flows where Basket publishes a BasketCheckout event to RabbitMQ; then, Ordering microservice subscribes to this event.
– PostgreSQL for Catalog (Document DB with Marten).
– Redis for Basket caching.
– SQLite for Discount.
– SQL Server for Ordering.
- Denote Docker Compose as the container orchestration mechanism that brings all these containers together.

##### Architectural Patterns and Technologies
- That the system follows microservices architecture principles: loosely-coupled services, independent deployments (containerized via Docker Compose), and segregated data storage.
- DDD and CQRS patterns in services like Ordering and Catalog.
- GRPC for high-performance, synchronous inter-service communication (Basket to Discount) and RabbitMQ for asynchronous pub-sub message exchanges.
- Use mediation patterns (MediatR) along with validation (FluentValidation) in the service pipelines.
- API Gateway design aspects such as routing rules, rate limiting (FixedWindowLimiter), and clustering as part of the gateway’s configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Layer
    Client["External Client"]:::external

    %% Gateway Layer
    Yarp["YarpApiGateway"]:::gateway
    Web["Shopping.Web"]:::frontend

    Client -->|"HTTPRequest"| Yarp
    Yarp -->|"Routes"| Web

    %% Microservices Layer
    Catalog["Catalog.API"]:::microservice
    Basket["Basket.API"]:::microservice
    Discount["Discount.Grpc"]:::microservice

    subgraph "Ordering Microservice"
        OrderingAPI["Ordering.API"]:::microservice
        OrderingApp["Ordering.Application"]:::microservice
        OrderingDomain["Ordering.Domain"]:::microservice
        OrderingInfra["Ordering.Infrastructure"]:::microservice
    end

    %% Gateway routing to Microservices
    Yarp -->|"Routes"| Catalog
    Yarp -->|"Routes"| Basket
    Yarp -->|"Routes"| OrderingAPI

    %% Inter-Service Communications
    Basket -->|"gRPCCall"| Discount
    Basket -->|"PublishEvent"| RabbitMQ
    RabbitMQ -->|"ConsumeEvent"| OrderingAPI

    %% Shared Building Blocks
    BB["BuildingBlocks"]:::buildingblocks
    Catalog -.->|"Uses"| BB
    Basket -.->|"Uses"| BB
    Discount -.->|"Uses"| BB
    OrderingAPI -.->|"Uses"| BB
    OrderingApp -.->|"Uses"| BB
    OrderingDomain -.->|"Uses"| BB
    OrderingInfra -.->|"Uses"| BB

    %% Infrastructure: Databases and Messaging
    Postgres["PostgreSQL"]:::database
    Redis["Redis Cache"]:::database
    SQLite["SQLite"]:::database
    SQLServer["SQL Server"]:::database
    RabbitMQ["RabbitMQ"]:::messaging

    Catalog -->|"Uses"| Postgres
    Basket -->|"Uses"| Redis
    Discount -->|"Uses"| SQLite
    OrderingInfra -->|"Uses"| SQLServer

    %% Container Orchestration
    Docker["Docker Compose"]:::orchestration
    Docker -->|"Orchestrates"| Yarp
    Docker -->|"Orchestrates"| Web
    Docker -->|"Orchestrates"| Catalog
    Docker -->|"Orchestrates"| Basket
    Docker -->|"Orchestrates"| Discount
    Docker -->|"Orchestrates"| OrderingAPI

    %% Styles Declaration
    classDef external fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef gateway fill:#aqua,stroke:#333,stroke-width:2px;
    classDef frontend fill:#ff99cc,stroke:#333,stroke-width:2px;
    classDef microservice fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef buildingblocks fill:#dddddd,stroke:#333,stroke-width:2px;
    classDef database fill:#e6e6fa,stroke:#333,stroke-width:2px;
    classDef messaging fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef orchestration fill:#d3d3d3,stroke:#333,stroke-width:2px;

    %% Click Events
    click Yarp "https://github.com/aspnetrun/run-aspnetcore-microservices/tree/master/src/ApiGateways/YarpApiGateway"
    click Web "https://github.com/aspnetrun/run-aspnetcore-microservices/blob/master/src/WebApps/Shopping.Web"
    click Catalog "https://github.com/aspnetrun/run-aspnetcore-microservices/blob/master/src/Services/Catalog/Catalog.API"
    click Basket "https://github.com/aspnetrun/run-aspnetcore-microservices/blob/master/src/Services/Basket/Basket.API"
    click Discount "https://github.com/aspnetrun/run-aspnetcore-microservices/blob/master/src/Services/Discount/Discount.Grpc"
    click OrderingAPI "https://github.com/aspnetrun/run-aspnetcore-microservices/blob/master/src/Services/Ordering/Ordering.API"
    click OrderingApp "https://github.com/aspnetrun/run-aspnetcore-microservices/blob/master/src/Services/Ordering/Ordering.Application"
    click OrderingDomain "https://github.com/aspnetrun/run-aspnetcore-microservices/blob/master/src/Services/Ordering/Ordering.Domain"
    click OrderingInfra "https://github.com/aspnetrun/run-aspnetcore-microservices/blob/master/src/Services/Ordering/Ordering.Infrastructure"
    click BB "https://github.com/aspnetrun/run-aspnetcore-microservices/tree/master/src/BuildingBlocks"
```
