# sagizod/eshoponcontainers architecture

> Architecture diagram of the GitHub repository sagizod/eshoponcontainers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sagizod/eshoponcontainers
- Repository: https://github.com/sagizod/eshoponcontainers

## Overview

#### Purpose and execution
eShopOnContainers is a .NET Core 3.1 reference e-commerce system demonstrating independently deployable, containerized microservices. Local composition starts from `src/docker-compose.yml`; the solution entry is `src/eShopOnContainers-ServicesAndWebApps.sln`. Each service is an ASP.NET Core process with its own Docker image and `Program.cs`/`Startup.cs` host boundary.

#### Client and edge layer
Browser clients are server-rendered MVC and an Angular SPA; a status site and webhook demo client are auxiliary entry points.
- MVC storefront: `src/Web/WebMVC/Program.cs`, `src/Web/WebMVC/Controllers/CatalogController.cs`
- Angular SPA hosted by ASP.NET Core: `src/Web/WebSPA/Client/main.ts`, `src/Web/WebSPA/Startup.cs`
- Separate mobile and web shopping BFFs aggregate downstream basket, catalog, and ordering calls: `src/ApiGateways/Web.Bff.Shopping/aggregator/Startup.cs`, `src/ApiGateways/Mobile.Bff.Shopping/aggregator/Controllers/OrderController.cs`
- Envoy gateway configurations define edge routing per client type: `src/ApiGateways/Envoy/config/webshopping/envoy.yaml`, `src/ApiGateways/Envoy/config/mobileshopping/envoy.yaml`.

#### Identity and service communication
`Identity.API` is the OAuth/OIDC identity boundary used by clients and protected APIs. BFFs and web applications propagate authorization via HTTP delegating handlers; internal service reads also expose gRPC contracts where present.
- Identity host/configuration: `src/Services/Identity/Identity.API/Startup.cs`, `src/Services/Identity/Identity.API/Configuration/Config.cs`
- Authorization propagation: `src/ApiGateways/Web.Bff.Shopping/aggregator/Infrastructure/HttpClientAuthorizationDelegatingHandler.cs`
- gRPC boundaries: `src/Services/Basket/Basket.API/Proto/basket.proto`, `src/Services/Catalog/Catalog.API/Proto/catalog.proto`, `src/Services/Ordering/Ordering.API/Proto/ordering.proto`.

#### Catalog and basket domains
Catalog owns product, brand/type, stock, and picture data through EF Core; Basket owns per-customer carts in Redis. Basket checkout publishes an integration event rather than synchronously creating an order.
- Catalog HTTP/gRPC API and persistence: `src/Services/Catalog/Catalog.API/Controllers/CatalogController.cs`, `src/Services/Catalog/Catalog.API/Infrastructure/CatalogContext.cs`
- Basket API and Redis repository: `src/Services/Basket/Basket.API/Controllers/BasketController.cs`, `src/Services/Basket/Basket.API/Infrastructure/Repositories/RedisBasketRepository.cs`
- Checkout event contract: `src/Services/Basket/Basket.API/IntegrationEvents/Events/UserCheckoutAcceptedIntegrationEvent.cs`.

#### Ordering workflow and payment saga
Ordering is the primary DDD/CQRS subsystem: commands enter its API, MediatR-style behaviors enforce validation, transactionality, and idempotency, and aggregates persist orders/buyers. It consumes checkout, payment, and stock events, emits order-status events, and drives a distributed workflow. Payment reacts after stock confirmation; a background worker manages the grace period; SignalR broadcasts lifecycle updates.
- API commands/workflow: `src/Services/Ordering/Ordering.API/Application/Commands/CreateOrderCommandHandler.cs`, `src/Services/Ordering/Ordering.API/Application/IntegrationEvents/EventHandling/UserCheckoutAcceptedIntegrationEventHandler.cs`
- Domain and persistence: `src/Services/Ordering/Ordering.Domain/AggregatesModel/OrderAggregate/Order.cs`, `src/Services/Ordering/Ordering.Infrastructure/OrderingContext.cs`
- Payment, background, and notifications: `src/Services/Payment/Payment.API/IntegrationEvents/EventHandling/OrderStatusChangedToStockConfirmedIntegrationEventHandler.cs`, `src/Services/Ordering/Ordering.BackgroundTasks/Tasks/GracePeriodManagerTask.cs`, `src/Services/Ordering/Ordering.SignalrHub/NotificationHub.cs`.

#### Eventing and external notifications
The shared EventBus abstracts RabbitMQ or Azure Service Bus. EF-backed integration-event logs support reliable publication alongside service database transactions. Catalog price/stock changes and ordering statuses fan out asynchronously to basket, payment, catalog, SignalR, and webhook subscribers. Webhooks stores subscriptions and delivers outbound HTTP callbacks.
- Bus abstractions/transports: `src/BuildingBlocks/EventBus/EventBus/Abstractions/IEventBus.cs`, `src/BuildingBlocks/EventBus/EventBusRabbitMQ/EventBusRabbitMQ.cs`, `src/BuildingBlocks/EventBus/EventBusServiceBus/EventBusServiceBus.cs`
- Transactional event log: `src/BuildingBlocks/EventBus/IntegrationEventLogEF/Services/IntegrationEventLogService.cs`
- Webhook boundary: `src/Services/Webhooks/Webhooks.API/Controllers/WebhooksController.cs`, `src/Services/Webhooks/Webhooks.API/Services/WebhooksSender.cs`.

#### Infrastructure and deployment
The normal runtime is Docker Compose; Kubernetes Helm charts deploy the same service topology, including Envoy gateways, ingress, SQL, Redis, RabbitMQ, and shared secrets. Azure templates provision SQL, Redis, Service Bus, Cosmos DB, and catalog storage. ELK Compose assets provide centralized logging.
- Composition/deployment: `src/docker-compose.yml`, `deploy/k8s/helm/app.yaml`, `deploy/k8s/helm/deploy-all.sh`
- Cloud resources: `deploy/azure/az/sql/sqldeploy.json`, `deploy/azure/az/redis/redisdeploy.json`, `deploy/azure/az/servicebus/sbusdeploy.json`
- Observability stack: `src/docker-compose.elk.yml`, `deploy/elk/logstash/pipeline/logstash.conf`.

Main entry points: [`src/Services/Ordering/Ordering.API/Application/Commands/CreateOrderCommandHandler.cs`](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Ordering/Ordering.API/Application/Commands/CreateOrderCommandHandler.cs) (Ordering API), [`src/ApiGateways/Web.Bff.Shopping/aggregator/Startup.cs`](https://github.com/sagizod/eshoponcontainers/blob/dev/src/ApiGateways/Web.Bff.Shopping/aggregator/Startup.cs) (Shopping BFFs), [`src/ApiGateways/Envoy/config/webshopping/envoy.yaml`](https://github.com/sagizod/eshoponcontainers/blob/dev/src/ApiGateways/Envoy/config/webshopping/envoy.yaml) (Envoy Gateways), [`src/docker-compose.yml`](https://github.com/sagizod/eshoponcontainers/blob/dev/src/docker-compose.yml) (Docker Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients & Edge"]
  node_mvc["MVC Storefront<br/>ASP.NET Core MVC<br/>[Program.cs]"]
  node_spa["Angular SPA<br/>Angular / ASP.NET host<br/>[main.ts]"]
  node_envoy["Envoy Gateways<br/>edge routing<br/>[envoy.yaml]"]
  node_bff["Shopping BFFs<br/>API aggregators<br/>[Startup.cs]"]
end

subgraph group_services["Business Services"]
  node_identity["Identity API<br/>OAuth/OIDC service<br/>[Startup.cs]"]
  node_catalog["Catalog API<br/>catalog service"]
  node_catalogdb[("Catalog database<br/>EF Core store<br/>[CatalogContext.cs]")]
  node_basket["Basket API<br/>cart service"]
  node_redis[("Redis baskets<br/>cart store")]
  node_orderingapi["Ordering API<br/>CQRS command API"]
  node_orderingdomain[("Order domain &amp; store<br/>[OrderingContext.cs]")]
  node_payment["Payment API<br/>payment saga participant"]
  node_grace["Grace-period worker<br/>background worker"]
  node_signalr["Order notifications<br/>SignalR hub<br/>[NotificationHub.cs]"]
  node_webhooks["Webhooks API<br/>outbound callback service"]
end

subgraph group_async["Async Platform"]
  node_eventbus["Integration Event Bus"]
  node_eventlog[("Transactional event log<br/>EF event outbox")]
end

subgraph group_ops["Deployment &amp; Observability"]
  node_compose["Docker Compose<br/>local composition<br/>[docker-compose.yml]"]
  node_helm["Kubernetes Helm<br/>deployment manifests<br/>[app.yaml]"]
  node_elk["ELK logging<br/>observability stack"]
end

node_compose -->|"runs"| node_mvc
node_compose -->|"runs"| node_eventbus
node_helm -->|"deploys"| node_envoy
node_mvc -->|"OAuth/OIDC"| node_identity
node_spa -->|"OAuth/OIDC"| node_identity
node_mvc -->|"API requests"| node_envoy
node_spa -->|"API requests"| node_envoy
node_envoy -->|"routes by client"| node_bff
node_bff -->|"aggregates reads"| node_catalog
node_bff -->|"aggregates carts"| node_basket
node_bff -->|"aggregates orders"| node_orderingapi
node_catalog -->|"persists"| node_catalogdb
node_basket -->|"stores carts"| node_redis
node_basket -->|"records checkout event"| node_eventlog
node_eventlog -->|"publishes reliably"| node_eventbus
node_eventbus -->|"checkout and status events"| node_orderingapi
node_orderingapi -->|"persists aggregates"| node_orderingdomain
node_orderingapi -->|"records order events"| node_eventlog
node_eventbus -->|"stock and price events"| node_catalog
node_eventbus -->|"stock-confirmed event"| node_payment
node_eventbus -->|"order status events"| node_signalr
node_eventbus -->|"order and catalog events"| node_webhooks
node_grace -->|"updates expired orders"| node_orderingapi
node_compose -->|"starts logging stack"| node_elk

click node_compose "https://github.com/sagizod/eshoponcontainers/blob/dev/src/docker-compose.yml"
click node_helm "https://github.com/sagizod/eshoponcontainers/blob/dev/deploy/k8s/helm/app.yaml"
click node_elk "https://github.com/sagizod/eshoponcontainers/blob/dev/src/docker-compose.elk.yml"
click node_mvc "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Web/WebMVC/Program.cs"
click node_spa "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Web/WebSPA/Client/main.ts"
click node_envoy "https://github.com/sagizod/eshoponcontainers/blob/dev/src/ApiGateways/Envoy/config/webshopping/envoy.yaml"
click node_bff "https://github.com/sagizod/eshoponcontainers/blob/dev/src/ApiGateways/Web.Bff.Shopping/aggregator/Startup.cs"
click node_identity "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Identity/Identity.API/Startup.cs"
click node_catalog "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Catalog/Catalog.API/Controllers/CatalogController.cs"
click node_catalogdb "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Catalog/Catalog.API/Infrastructure/CatalogContext.cs"
click node_basket "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Basket/Basket.API/Controllers/BasketController.cs"
click node_redis "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Basket/Basket.API/Infrastructure/Repositories/RedisBasketRepository.cs"
click node_orderingapi "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Ordering/Ordering.API/Application/Commands/CreateOrderCommandHandler.cs"
click node_orderingdomain "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Ordering/Ordering.Infrastructure/OrderingContext.cs"
click node_payment "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Payment/Payment.API/IntegrationEvents/EventHandling/OrderStatusChangedToStockConfirmedIntegrationEventHandler.cs"
click node_grace "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Ordering/Ordering.BackgroundTasks/Tasks/GracePeriodManagerTask.cs"
click node_signalr "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Ordering/Ordering.SignalrHub/NotificationHub.cs"
click node_webhooks "https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Webhooks/Webhooks.API/Controllers/WebhooksController.cs"
click node_eventlog "https://github.com/sagizod/eshoponcontainers/blob/dev/src/BuildingBlocks/EventBus/IntegrationEventLogEF/Services/IntegrationEventLogService.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_mvc,node_spa,node_envoy,node_bff toneBlue
class node_identity,node_catalog,node_catalogdb,node_basket,node_redis,node_orderingapi,node_orderingdomain,node_payment,node_grace,node_signalr,node_webhooks toneAmber
class node_eventbus,node_eventlog toneMint
class node_compose,node_helm,node_elk toneRose
```

## Components

### Clients & Edge

- [MVC Storefront](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Web/WebMVC/Program.cs): ASP.NET Core MVC · `src/Web/WebMVC/Program.cs`
- [Angular SPA](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Web/WebSPA/Client/main.ts): Angular / ASP.NET host · `src/Web/WebSPA/Client/main.ts`
- [Envoy Gateways](https://github.com/sagizod/eshoponcontainers/blob/dev/src/ApiGateways/Envoy/config/webshopping/envoy.yaml): edge routing · Routes web and mobile client traffic to BFFs. · `src/ApiGateways/Envoy/config/webshopping/envoy.yaml`
- [Shopping BFFs](https://github.com/sagizod/eshoponcontainers/blob/dev/src/ApiGateways/Web.Bff.Shopping/aggregator/Startup.cs): API aggregators · Separate web and mobile downstream aggregators. · `src/ApiGateways/Web.Bff.Shopping/aggregator/Startup.cs`

### Business Services

- [Identity API](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Identity/Identity.API/Startup.cs): OAuth/OIDC service · Authenticates clients and protected API calls. · `src/Services/Identity/Identity.API/Startup.cs`
- [Catalog API](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Catalog/Catalog.API/Controllers/CatalogController.cs): catalog service · Owns products, stock, brands, types, and pictures. · `src/Services/Catalog/Catalog.API/Controllers/CatalogController.cs`
- [Catalog database](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Catalog/Catalog.API/Infrastructure/CatalogContext.cs): EF Core store · `src/Services/Catalog/Catalog.API/Infrastructure/CatalogContext.cs`
- [Basket API](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Basket/Basket.API/Controllers/BasketController.cs): cart service · Checkout initiates the asynchronous ordering flow. · `src/Services/Basket/Basket.API/Controllers/BasketController.cs`
- [Redis baskets](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Basket/Basket.API/Infrastructure/Repositories/RedisBasketRepository.cs): cart store · `src/Services/Basket/Basket.API/Infrastructure/Repositories/RedisBasketRepository.cs`
- [Ordering API](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Ordering/Ordering.API/Application/Commands/CreateOrderCommandHandler.cs): CQRS command API · Handles checkout and order commands through validation, transactions, and idempotency. · `src/Services/Ordering/Ordering.API/Application/Commands/CreateOrderCommandHandler.cs`
- [Order domain & store](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Ordering/Ordering.Infrastructure/OrderingContext.cs): DDD aggregates / EF Core · Persists orders and buyers. · `src/Services/Ordering/Ordering.Infrastructure/OrderingContext.cs`
- [Payment API](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Payment/Payment.API/IntegrationEvents/EventHandling/OrderStatusChangedToStockConfirmedIntegrationEventHandler.cs): payment saga participant · Acts after stock confirmation. · `src/Services/Payment/Payment.API/IntegrationEvents/EventHandling/OrderStatusChangedToStockConfirmedIntegrationEventHandler.cs`
- [Grace-period worker](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Ordering/Ordering.BackgroundTasks/Tasks/GracePeriodManagerTask.cs): background worker · Manages order payment grace periods. · `src/Services/Ordering/Ordering.BackgroundTasks/Tasks/GracePeriodManagerTask.cs`
- [Order notifications](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Ordering/Ordering.SignalrHub/NotificationHub.cs): SignalR hub · Broadcasts order lifecycle updates. · `src/Services/Ordering/Ordering.SignalrHub/NotificationHub.cs`
- [Webhooks API](https://github.com/sagizod/eshoponcontainers/blob/dev/src/Services/Webhooks/Webhooks.API/Controllers/WebhooksController.cs): outbound callback service · Stores subscriptions and delivers HTTP callbacks. · `src/Services/Webhooks/Webhooks.API/Controllers/WebhooksController.cs`

### Async Platform

- **Integration Event Bus**: RabbitMQ / Azure Service Bus · Publishes and consumes cross-service integration events.
- [Transactional event log](https://github.com/sagizod/eshoponcontainers/blob/dev/src/BuildingBlocks/EventBus/IntegrationEventLogEF/Services/IntegrationEventLogService.cs): EF event outbox · Reliably publishes events with service database transactions. · `src/BuildingBlocks/EventBus/IntegrationEventLogEF/Services/IntegrationEventLogService.cs`

### Deployment & Observability

- [Docker Compose](https://github.com/sagizod/eshoponcontainers/blob/dev/src/docker-compose.yml): local composition · Starts the containerized service topology. · `src/docker-compose.yml`
- [Kubernetes Helm](https://github.com/sagizod/eshoponcontainers/blob/dev/deploy/k8s/helm/app.yaml): deployment manifests · Deploys the same topology to Kubernetes. · `deploy/k8s/helm/app.yaml`
- [ELK logging](https://github.com/sagizod/eshoponcontainers/blob/dev/src/docker-compose.elk.yml): observability stack · Centralizes container logs through Logstash. · `src/docker-compose.elk.yml`

## Connections

- Docker Compose → MVC Storefront: runs
- Docker Compose → Integration Event Bus: runs
- Kubernetes Helm → Envoy Gateways: deploys
- MVC Storefront → Identity API: OAuth/OIDC
- Angular SPA → Identity API: OAuth/OIDC
- MVC Storefront → Envoy Gateways: API requests
- Angular SPA → Envoy Gateways: API requests
- Envoy Gateways → Shopping BFFs: routes by client
- Shopping BFFs → Catalog API: aggregates reads · Uses HTTP and gRPC service contracts.
- Shopping BFFs → Basket API: aggregates carts
- Shopping BFFs → Ordering API: aggregates orders
- Catalog API → Catalog database: persists
- Basket API → Redis baskets: stores carts
- Basket API → Transactional event log: records checkout event
- Transactional event log → Integration Event Bus: publishes reliably
- Integration Event Bus → Ordering API: checkout and status events
- Ordering API → Order domain & store: persists aggregates
- Ordering API → Transactional event log: records order events
- Integration Event Bus → Catalog API: stock and price events
- Integration Event Bus → Payment API: stock-confirmed event
- Integration Event Bus → Order notifications: order status events
- Integration Event Bus → Webhooks API: order and catalog events
- Grace-period worker → Ordering API: updates expired orders
- Docker Compose → ELK logging: starts logging stack