# swmiller/aspnetcore-microservices-architecture architecture

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

- Interactive diagram: https://gitdiagram.com/swmiller/aspnetcore-microservices-architecture
- Repository: https://github.com/swmiller/aspnetcore-microservices-architecture

## Overview

This is an educational ASP.NET Core microservices shopping application, with separate web, basket, catalog, discount, and ordering components plus shared building blocks. The principal workflow is browsing products, maintaining a basket, checking out, and managing orders. The excerpts show the web app’s gateway-based client setup and the basket checkout’s publish-and-delete behavior; ordering and several service interactions are represented from the tree and index, so uncertain connections are omitted or marked unverified.

Main entry points: [`src/WebApps/Shopping.Web/Services`](https://github.com/swmiller/aspnetcore-microservices-architecture/tree/main/src/WebApps/Shopping.Web/Services) (API clients), [`src/Services/Ordering/Ordering.Application/Orders/Commands/CreateOrder/CreateOrderHandler.cs`](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Ordering/Ordering.Application/Orders/Commands/CreateOrder/CreateOrderHandler.cs) (Order handlers), [`src/Services/Basket/Basket.API/Basket`](https://github.com/swmiller/aspnetcore-microservices-architecture/tree/main/src/Services/Basket/Basket.API/Basket) (Basket endpoints), [`src/Services/Basket/Basket.API/Basket/CheckoutBasket/CheckoutBasketHandler.cs`](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Basket/Basket.API/Basket/CheckoutBasket/CheckoutBasketHandler.cs) (Basket checkout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Shopping web"]
  node_webapp["Razor storefront<br/>[Pages]"]
  node_webclients["API clients<br/>[Services]"]
end

subgraph group_commerce["Commerce APIs"]
  node_gateway["YARP gateway<br/>[Program.cs]"]
  node_catalog["Product catalog<br/>[Products]"]
  node_catalogdata[("Catalog data<br/>[Product.cs]")]
  node_basket["Basket endpoints<br/>[Basket]"]
  node_basketmodel["Shopping cart<br/>[ShoppingCart.cs]"]
  node_basketrepo["Basket repository"]
  node_basketstore[("Basket persistence")]
  node_discount["Discount gRPC<br/>[DiscountService.cs]"]
  node_discountdata[("Coupon store<br/>[DiscountContext.cs]")]
  node_checkout["Basket checkout"]
end

subgraph group_ordering["Order management"]
  node_orderingapi["Order endpoints<br/>[CreateOrder.cs]"]
  node_orderhandlers["Order handlers"]
  node_orderdomain["Order domain<br/>[Order.cs]"]
  node_orderstore[("Order persistence")]
end

subgraph group_shared["Shared infrastructure"]
  node_broker["Message broker<br/>[Extentions.cs]"]
  node_checkoutevent["Checkout event"]
  node_cqrs["CQRS contracts<br/>[ICommand.cs]"]
  node_behaviors["Request behaviors"]
  node_exceptions["Exception handling"]
end

node_shopper(("Shopper"))

node_shopper -->|"uses"| node_webapp
node_webapp -->|"calls"| node_webclients
node_webclients -->|"targets"| node_gateway
node_webclients -->|"requests products"| node_catalog
node_webclients -->|"requests basket"| node_basket
node_gateway -.-> node_catalog
node_gateway -.-> node_basket
node_catalog -.->|"manages products"| node_catalogdata
node_basket -->|"uses cart"| node_basketmodel
node_basketrepo -.->|"persists"| node_basketstore
node_basket -->|"uses repository"| node_basketrepo
node_discount -->|"reads and writes"| node_discountdata
node_checkout -->|"loads and deletes"| node_basketrepo
node_checkout -->|"creates"| node_checkoutevent
node_checkout -->|"publishes"| node_broker
node_checkoutevent -.->|"may trigger order creation"| node_orderingapi
node_orderingapi -.->|"dispatches requests"| node_orderhandlers
node_orderhandlers -.->|"updates order"| node_orderdomain
node_orderhandlers -.->|"persists orders"| node_orderstore
node_orderhandlers -.->|"uses contract"| node_cqrs
node_behaviors -->|"validates commands"| node_cqrs
node_exceptions -.->|"formats errors"| node_webapp

click node_webapp "https://github.com/swmiller/aspnetcore-microservices-architecture/tree/main/src/WebApps/Shopping.Web/Pages"
click node_webclients "https://github.com/swmiller/aspnetcore-microservices-architecture/tree/main/src/WebApps/Shopping.Web/Services"
click node_gateway "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/ApiGateways/YarpApiGateway/Program.cs"
click node_catalog "https://github.com/swmiller/aspnetcore-microservices-architecture/tree/main/src/Services/Catalog/Catalog.API/Products"
click node_catalogdata "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Catalog/Catalog.API/Models/Product.cs"
click node_basket "https://github.com/swmiller/aspnetcore-microservices-architecture/tree/main/src/Services/Basket/Basket.API/Basket"
click node_basketmodel "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Basket/Basket.API/Models/ShoppingCart.cs"
click node_basketrepo "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Basket/Basket.API/Data/CachedBasketRepository.cs"
click node_basketstore "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Basket/Basket.API/Data/BasketRepository.cs"
click node_discount "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Discount/Discount.Grpc/Services/DiscountService.cs"
click node_discountdata "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Discount/Discount.Grpc/Data/DiscountContext.cs"
click node_checkout "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Basket/Basket.API/Basket/CheckoutBasket/CheckoutBasketHandler.cs"
click node_broker "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/BuildingBlocks/BuildingBlocks.Messaging/MassTransit/Extentions.cs"
click node_checkoutevent "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/BuildingBlocks/BuildingBlocks.Messaging/Events/BasketCheckoutEvent.cs"
click node_orderingapi "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Ordering/Ordering.API/Endpoints/CreateOrder.cs"
click node_orderhandlers "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Ordering/Ordering.Application/Orders/Commands/CreateOrder/CreateOrderHandler.cs"
click node_orderdomain "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Ordering/Ordering.Domain/Models/Order.cs"
click node_orderstore "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Ordering/Ordering.Infrastructure/Data/ApplicationDbContext.cs"
click node_cqrs "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/BuildingBlocks/BuildingBlocks/CQRS/ICommand.cs"
click node_behaviors "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/BuildingBlocks/BuildingBlocks/Behaviors/ValidationBehavior.cs"
click node_exceptions "https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/BuildingBlocks/BuildingBlocks/Exceptions/Handler/CustomExceptionHandler.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_webclients toneBlue
class node_gateway,node_catalog,node_catalogdata,node_basket,node_basketmodel,node_basketrepo,node_basketstore,node_discount,node_discountdata,node_checkout toneAmber
class node_orderingapi,node_orderhandlers,node_orderdomain,node_orderstore toneMint
class node_broker,node_checkoutevent,node_cqrs,node_behaviors,node_exceptions toneRose
class node_shopper toneIndigo
```

## Components

### Shopping web

- [Razor storefront](https://github.com/swmiller/aspnetcore-microservices-architecture/tree/main/src/WebApps/Shopping.Web/Pages): `src/WebApps/Shopping.Web/Pages`
- [API clients](https://github.com/swmiller/aspnetcore-microservices-architecture/tree/main/src/WebApps/Shopping.Web/Services): `src/WebApps/Shopping.Web/Services`

### Commerce APIs

- [YARP gateway](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/ApiGateways/YarpApiGateway/Program.cs): `src/ApiGateways/YarpApiGateway/Program.cs`
- [Product catalog](https://github.com/swmiller/aspnetcore-microservices-architecture/tree/main/src/Services/Catalog/Catalog.API/Products): `src/Services/Catalog/Catalog.API/Products`
- [Catalog data](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Catalog/Catalog.API/Models/Product.cs): `src/Services/Catalog/Catalog.API/Models/Product.cs`
- [Basket endpoints](https://github.com/swmiller/aspnetcore-microservices-architecture/tree/main/src/Services/Basket/Basket.API/Basket): `src/Services/Basket/Basket.API/Basket`
- [Shopping cart](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Basket/Basket.API/Models/ShoppingCart.cs): `src/Services/Basket/Basket.API/Models/ShoppingCart.cs`
- [Basket repository](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Basket/Basket.API/Data/CachedBasketRepository.cs): `src/Services/Basket/Basket.API/Data/CachedBasketRepository.cs`
- [Basket persistence](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Basket/Basket.API/Data/BasketRepository.cs): `src/Services/Basket/Basket.API/Data/BasketRepository.cs`
- [Discount gRPC](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Discount/Discount.Grpc/Services/DiscountService.cs): `src/Services/Discount/Discount.Grpc/Services/DiscountService.cs`
- [Coupon store](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Discount/Discount.Grpc/Data/DiscountContext.cs): `src/Services/Discount/Discount.Grpc/Data/DiscountContext.cs`
- [Basket checkout](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Basket/Basket.API/Basket/CheckoutBasket/CheckoutBasketHandler.cs): `src/Services/Basket/Basket.API/Basket/CheckoutBasket/CheckoutBasketHandler.cs`

### Order management

- [Order endpoints](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Ordering/Ordering.API/Endpoints/CreateOrder.cs): `src/Services/Ordering/Ordering.API/Endpoints/CreateOrder.cs`
- [Order handlers](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Ordering/Ordering.Application/Orders/Commands/CreateOrder/CreateOrderHandler.cs): `src/Services/Ordering/Ordering.Application/Orders/Commands/CreateOrder/CreateOrderHandler.cs`
- [Order domain](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Ordering/Ordering.Domain/Models/Order.cs): `src/Services/Ordering/Ordering.Domain/Models/Order.cs`
- [Order persistence](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/Services/Ordering/Ordering.Infrastructure/Data/ApplicationDbContext.cs): `src/Services/Ordering/Ordering.Infrastructure/Data/ApplicationDbContext.cs`

### Shared infrastructure

- [Message broker](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/BuildingBlocks/BuildingBlocks.Messaging/MassTransit/Extentions.cs): `src/BuildingBlocks/BuildingBlocks.Messaging/MassTransit/Extentions.cs`
- [Checkout event](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/BuildingBlocks/BuildingBlocks.Messaging/Events/BasketCheckoutEvent.cs): `src/BuildingBlocks/BuildingBlocks.Messaging/Events/BasketCheckoutEvent.cs`
- [CQRS contracts](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/BuildingBlocks/BuildingBlocks/CQRS/ICommand.cs): `src/BuildingBlocks/BuildingBlocks/CQRS/ICommand.cs`
- [Request behaviors](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/BuildingBlocks/BuildingBlocks/Behaviors/ValidationBehavior.cs): `src/BuildingBlocks/BuildingBlocks/Behaviors/ValidationBehavior.cs`
- [Exception handling](https://github.com/swmiller/aspnetcore-microservices-architecture/blob/main/src/BuildingBlocks/BuildingBlocks/Exceptions/Handler/CustomExceptionHandler.cs): `src/BuildingBlocks/BuildingBlocks/Exceptions/Handler/CustomExceptionHandler.cs`

### Other components

- **Shopper**

## Connections

- Shopper → Razor storefront: uses
- Razor storefront → API clients: calls (evidence: `src/WebApps/Shopping.Web/Pages/ProductList.cshtml.cs`)
- API clients → YARP gateway: targets
- API clients → Product catalog: requests products
- API clients → Basket endpoints: requests basket (evidence: `src/WebApps/Shopping.Web/Services/IBasketService.cs`)
- YARP gateway → Product catalog
- YARP gateway → Basket endpoints
- Product catalog → Catalog data: manages products
- Basket endpoints → Shopping cart: uses cart
- Basket repository → Basket persistence: persists
- Basket endpoints → Basket repository: uses repository
- Discount gRPC → Coupon store: reads and writes (evidence: `src/Services/Discount/Discount.Grpc/Services/DiscountService.cs`)
- Basket checkout → Basket repository: loads and deletes (evidence: `src/Services/Basket/Basket.API/Basket/CheckoutBasket/CheckoutBasketHandler.cs`)
- Basket checkout → Checkout event: creates (evidence: `src/Services/Basket/Basket.API/Basket/CheckoutBasket/CheckoutBasketHandler.cs`)
- Basket checkout → Message broker: publishes (evidence: `src/Services/Basket/Basket.API/Basket/CheckoutBasket/CheckoutBasketHandler.cs`)
- Checkout event → Order endpoints: may trigger order creation
- Order endpoints → Order handlers: dispatches requests
- Order handlers → Order domain: updates order
- Order handlers → Order persistence: persists orders
- Order handlers → CQRS contracts: uses contract
- Request behaviors → CQRS contracts: validates commands (evidence: `src/BuildingBlocks/BuildingBlocks/Behaviors/ValidationBehavior.cs`)
- Exception handling → Razor storefront: formats errors
