# senhorrg/eshoponcontainers-nestjs architecture

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

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

## Overview

1. This is a pnpm-based monorepo with three main kinds of code: runnable apps in `apps/`, reusable libraries in `packages/`, and shared interface artifacts in `contracts/`. The architecture is intentionally service-oriented, with each NestJS service owning its own API, application logic, integration handlers, and infrastructure adapters.

2. The core bounded contexts are `identity-service`, `catalog-service`, `ordering-service`, `basket-service`, and `webhooks-service`. Each service maps to a business area and keeps its own persistence and runtime concerns separate. `order-grace-worker` and `payment-worker` are background processors rather than user-facing APIs.

3. The synchronous request path is mostly HTTP. Browser clients talk directly to `identity`, `catalog`, and `ordering`; `basket-service` also exposes HTTP, and `basket-service` additionally exposes gRPC using the contract in `contracts/grpc/basket.proto`. `mobile-bff` is a thin proxy layer for mobile-style callers that need one consolidated entry point.

4. The main frontend is `storefront-web`, a React/Vite SPA that calls the backend services over HTTP and keeps some cart state locally for guests. When authenticated, it syncs basket/cart behavior through the BFF. `webhook-client` is a separate SPA for exercising the Webhooks API, and `operations-dashboard` is an observability-focused SPA for health, logs, metrics, and trace navigation.

5. The asynchronous backbone is RabbitMQ plus the outbox/inbox pattern. Services write business state and outbox rows in the same transaction, then a publisher forwards integration events to RabbitMQ. Consumers use inbox/processed-event ledgers to deduplicate and make handlers safe to retry.

6. `ordering-service` is the most workflow-heavy backend. It uses CQRS-style command/query handlers, a create-order workflow, and integration publishers/consumers to coordinate order lifecycle state transitions. `order-grace-worker` and `payment-worker` participate in saga-like flows by reacting to events and emitting follow-up events.

7. `catalog-service` combines catalog CRUD, AI-assisted catalog features, and event-driven reactions to ordering lifecycle events. It has Prisma-backed persistence, catalog-specific HTTP controllers, and integration handlers for events such as awaiting-validation and paid/shipped flows. It also stores and serves product images.

8. `basket-service` uses Redis as its primary data store rather than PostgreSQL. Its job is to hold customer basket state, validate access via HTTP/gRPC auth guards, and react to order-started events so baskets can be cleared or synchronized when checkout progresses.

9. `identity-service` owns authentication and account registration. It issues symmetric JWTs in the study setup, resolves login aliases/emails, and persists identity data in PostgreSQL through Prisma. This service is the trust source for other backends that validate user identity.

10. `webhooks-service` manages webhook subscriptions and dispatch. It persists subscriptions and processed integration events in PostgreSQL, consumes selected domain events from RabbitMQ, and sends outbound webhooks to registered URLs. It is the integration boundary for external systems that want order/catalog notifications.

11. Shared code in `packages/` is architecture-critical. `packages/domains/*` contains framework-free domain models and rules for basket, catalog, identity, and ordering. `packages/infrastructure/*` centralizes cross-cutting concerns such as auth, observability, HTTP resilience, health checks, inbox/outbox helpers, event-bus abstractions, exception filters, and shared UI primitives.

12. `contracts/` is the architectural source of truth for interoperability. It holds golden JSON examples for integration events, OpenAPI snapshots for each HTTP service, and the gRPC definition for basket. CI uses these artifacts to detect contract drift between services and clients.

13. The runtime infrastructure is PostgreSQL per bounded context, Redis for basket state, RabbitMQ for event transport, and optional Keycloak for OIDC-based flows. Observability is first-class: services emit structured logs, traces, and metrics, and the local stack includes Grafana, Jaeger, Prometheus, Loki, and an OTel collector.

14. Deployment is designed around local reproducibility and study, not a production cloud platform. The default path is Docker Compose with optional observability and optional Kubernetes/k3d/Argo CD manifests. The repo also includes Helm charts and Dockerfiles for the Nest services and storefront.

15. Testing follows the same boundaries: unit tests live close to each package/service, integration tests exercise inbox/outbox and containerized dependencies, and Playwright E2E covers browser journeys and service probes. This reinforces the architecture by checking both internal domain rules and cross-service behavior.

Main entry points: [`apps/catalog-service`](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/catalog-service) (Catalog), [`apps/basket-service`](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/basket-service) (Basket), [`apps/ordering-service`](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/ordering-service) (Ordering), [`apps/mobile-bff`](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/mobile-bff) (Mobile BFF)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
  node_storefront["Storefront<br/>React SPA"]
  node_mobilebff["Mobile BFF<br/>Nest proxy"]
  node_identity["Identity<br/>Nest auth"]
  node_catalog["Catalog"]
  node_basket["Basket"]
  node_ordering["Ordering<br/>Nest workflow"]
  node_webhooks["Webhooks<br/>Nest dispatch"]
  node_graceworker["Grace Worker<br/>background worker"]
  node_paymentworker["Payment Worker<br/>background worker"]
end

subgraph group_packages["Packages"]
  node_domdomains{{"Domain models<br/>framework-free domain"}}
  node_infraauth{{"Auth pkg<br/>jwt/oidc auth"}}
  node_infrabus{{"Event bus<br/>RabbitMQ AMQP"}}
  node_inboxoutbox{{"Inbox/Outbox<br/>delivery guarantees"}}
  node_observability{{"Observability<br/>otel/logging"}}
  node_healthpkg{{"Health pkg<br/>health checks"}}
  node_ui{{"UI kit<br/>shared UI"}}
end

subgraph group_contracts["Contracts"]
  node_contractsapi["OpenAPI<br/>API snapshots"]
  node_contractsevents["Events<br/>golden JSON"]
  node_contractgrpc["Basket proto<br/>gRPC schema<br/>[basket.proto]"]
end

subgraph group_infra["Runtime infra"]
  node_postgres[("PostgreSQL<br/>relational DB")]
  node_redis[("Redis<br/>key-value store")]
  node_rabbitmq["RabbitMQ<br/>event transport"]
  node_grafana(("Ops stack<br/>observability stack"))
end

subgraph group_delivery["Delivery"]
  node_deploy["Deploy<br/>compose/helm/gitops"]
  node_tests["Tests<br/>integration/e2e"]
end

node_storefront -->|"login/register"| node_identity
node_storefront -->|"browse/search"| node_catalog
node_storefront -->|"cart sync"| node_basket
node_storefront -->|"checkout"| node_ordering
node_mobilebff -->|"proxy auth"| node_identity
node_mobilebff -->|"proxy catalog"| node_catalog
node_mobilebff -->|"proxy basket"| node_basket
node_mobilebff -->|"proxy orders"| node_ordering
node_basket -->|"implements"| node_contractgrpc
node_identity -->|"stores"| node_postgres
node_catalog -->|"stores"| node_postgres
node_ordering -->|"stores"| node_postgres
node_webhooks -->|"stores"| node_postgres
node_basket -->|"stores"| node_redis
node_paymentworker -->|"uses"| node_redis
node_ordering -->|"publishes/consumes"| node_rabbitmq
node_basket -->|"consumes"| node_rabbitmq
node_catalog -->|"consumes"| node_rabbitmq
node_webhooks -->|"consumes"| node_rabbitmq
node_graceworker -->|"consumes"| node_rabbitmq
node_paymentworker -->|"consumes"| node_rabbitmq
node_ordering -->|"uses"| node_inboxoutbox
node_catalog -->|"uses"| node_inboxoutbox
node_basket -->|"uses"| node_inboxoutbox
node_webhooks -->|"uses"| node_inboxoutbox
node_ordering -->|"uses"| node_domdomains
node_catalog -->|"uses"| node_domdomains
node_basket -->|"uses"| node_domdomains
node_identity -->|"uses"| node_domdomains
node_mobilebff -->|"uses"| node_observability
node_identity -->|"uses"| node_observability
node_catalog -->|"uses"| node_observability
node_basket -->|"uses"| node_observability
node_ordering -->|"uses"| node_observability
node_webhooks -->|"uses"| node_observability
node_healthpkg -.->|"checks"| node_postgres
node_healthpkg -.->|"checks"| node_redis
node_healthpkg -.->|"checks"| node_rabbitmq
node_storefront -.->|"consumes"| node_ui
node_webhooks -.->|"aligns"| node_contractsapi
node_identity -.->|"aligns"| node_contractsapi
node_catalog -.->|"aligns"| node_contractsapi
node_basket -.->|"aligns"| node_contractsapi
node_ordering -.->|"aligns"| node_contractsapi
node_mobilebff -.->|"aligns"| node_contractsapi
node_ordering -.->|"emits/consumes"| node_contractsevents
node_catalog -.->|"emits/consumes"| node_contractsevents
node_webhooks -.->|"consumes"| node_contractsevents

click node_storefront "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/storefront-web"
click node_mobilebff "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/mobile-bff"
click node_identity "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/identity-service"
click node_catalog "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/catalog-service"
click node_basket "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/basket-service"
click node_ordering "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/ordering-service"
click node_webhooks "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/webhooks-service"
click node_graceworker "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/order-grace-worker"
click node_paymentworker "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/payment-worker"
click node_domdomains "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/domains"
click node_infraauth "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/auth"
click node_infrabus "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/event-bus-amqp"
click node_inboxoutbox "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/inbox"
click node_observability "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/observability"
click node_healthpkg "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/health"
click node_ui "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/ui"
click node_contractsapi "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/contracts/openapi"
click node_contractsevents "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/contracts/golden"
click node_contractgrpc "https://github.com/senhorrg/eshoponcontainers-nestjs/blob/main/contracts/grpc/basket.proto"
click node_grafana "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/deploy/compose/observability"
click node_deploy "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/deploy"
click node_tests "https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/tests"

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_storefront,node_mobilebff,node_identity,node_catalog,node_basket,node_ordering,node_webhooks,node_graceworker,node_paymentworker toneBlue
class node_domdomains,node_infraauth,node_infrabus,node_inboxoutbox,node_observability,node_healthpkg,node_ui toneAmber
class node_contractsapi,node_contractsevents,node_contractgrpc toneMint
class node_postgres,node_redis,node_rabbitmq,node_grafana toneRose
class node_deploy,node_tests toneIndigo
```

## Components

### Apps

Runnable services and frontends

- [Storefront](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/storefront-web): React SPA · Primary browser storefront UI with guest cart state and authenticated basket sync · `apps/storefront-web`
- [Mobile BFF](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/mobile-bff): Nest proxy · Thin consolidated entry point for mobile-style callers · `apps/mobile-bff`
- [Identity](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/identity-service): Nest auth · Authentication, account registration, alias resolution, and JWT issuance · `apps/identity-service`
- [Catalog](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/catalog-service): Nest catalog · Catalog CRUD, AI-assisted features, image serving, and order-event reactions · `apps/catalog-service`
- [Basket](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/basket-service): Nest basket · Basket state service with HTTP and gRPC access backed by Redis · `apps/basket-service`
- [Ordering](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/ordering-service): Nest workflow · Order orchestration, CQRS handlers, and lifecycle integration flows · `apps/ordering-service`
- [Webhooks](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/webhooks-service): Nest dispatch · Webhook subscription management and outbound event delivery · `apps/webhooks-service`
- [Grace Worker](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/order-grace-worker): background worker · Consumes order grace-period events and advances saga-like flows · `apps/order-grace-worker`
- [Payment Worker](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/apps/payment-worker): background worker · Handles payment-related follow-up events in ordering flows · `apps/payment-worker`

### Packages

Shared domain and infrastructure libraries

- [Domain models](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/domains): framework-free domain · Shared business rules and aggregates for basket, catalog, identity, and ordering · `packages/domains`
- [Auth pkg](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/auth): jwt/oidc auth · Shared JWT verification, claims mapping, and Nest auth helpers · `packages/infrastructure/auth`
- [Event bus](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/event-bus-amqp): RabbitMQ AMQP · Integration event transport, publisher lifecycle, and subscription registry · `packages/infrastructure/event-bus-amqp`
- [Inbox/Outbox](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/inbox): delivery guarantees · Deduplication, transactional outbox appends, and publisher support · `packages/infrastructure/inbox`
- [Observability](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/observability): otel/logging · Structured logging, tracing, correlation IDs, and HTTP app bootstrap · `packages/infrastructure/observability`
- [Health pkg](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/health): health checks · Probe controllers and Postgres, Redis, RabbitMQ indicators · `packages/infrastructure/health`
- [UI kit](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/packages/infrastructure/ui): shared UI · Reusable interface components for study and dashboard surfaces · `packages/infrastructure/ui`

### Contracts

Interop artifacts and API sources of truth

- [OpenAPI](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/contracts/openapi): API snapshots · HTTP contract snapshots used to detect service and client drift · `contracts/openapi`
- [Events](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/contracts/golden): golden JSON · Canonical integration-event examples and payload shapes · `contracts/golden`
- [Basket proto](https://github.com/senhorrg/eshoponcontainers-nestjs/blob/main/contracts/grpc/basket.proto): gRPC schema · Basket service gRPC contract · `contracts/grpc/basket.proto`

### Runtime infra

Datastores, messaging, and observability backends

- **PostgreSQL**: relational DB · Primary persistence for identity, catalog, ordering, and webhooks
- **Redis**: key-value store · Basket state and some worker coordination data
- **RabbitMQ**: event transport · Asynchronous backbone for domain integration events
- [Ops stack](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/deploy/compose/observability): observability stack · Prometheus, Loki, Jaeger, Grafana, and OTel collector for local study deployments · `deploy/compose/observability`

### Delivery

Deployment and validation tooling

- [Deploy](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/deploy): compose/helm/gitops · Docker Compose, Helm, Argo CD, k3d, and Dockerfiles for local and study deployment · `deploy`
- [Tests](https://github.com/senhorrg/eshoponcontainers-nestjs/tree/main/tests): integration/e2e · Repository-level integration, saga, smoke, and Playwright journeys · `tests`

## Connections

- Storefront → Identity: login/register · Browser auth flows call identity service
- Storefront → Catalog: browse/search · Storefront reads catalog data over HTTP
- Storefront → Basket: cart sync · Authenticated cart behavior syncs with basket service
- Storefront → Ordering: checkout · Checkout and order status flows reach ordering service
- Mobile BFF → Identity: proxy auth · Mobile callers access identity through the BFF
- Mobile BFF → Catalog: proxy catalog · Mobile callers access catalog through the BFF
- Mobile BFF → Basket: proxy basket · Mobile callers access basket through the BFF
- Mobile BFF → Ordering: proxy orders · Mobile callers access ordering through the BFF
- Basket → Basket proto: implements · Basket service exposes gRPC defined by the basket proto
- Identity → PostgreSQL: stores · Identity persists accounts and aliases in PostgreSQL
- Catalog → PostgreSQL: stores · Catalog persists catalog data and images metadata in PostgreSQL
- Ordering → PostgreSQL: stores · Ordering persists orders, workflow state, and outbox rows in PostgreSQL
- Webhooks → PostgreSQL: stores · Webhooks persists subscriptions and processed-event ledgers in PostgreSQL
- Basket → Redis: stores · Basket uses Redis as its primary state store
- Payment Worker → Redis: uses · Payment worker depends on Redis infrastructure
- Ordering → RabbitMQ: publishes/consumes · Ordering exchanges integration events through RabbitMQ
- Basket → RabbitMQ: consumes · Basket reacts to order-started events from RabbitMQ
- Catalog → RabbitMQ: consumes · Catalog reacts to ordering lifecycle events from RabbitMQ
- Webhooks → RabbitMQ: consumes · Webhooks subscribes to selected domain events from RabbitMQ
- Grace Worker → RabbitMQ: consumes · Grace worker reacts to grace-period events
- Payment Worker → RabbitMQ: consumes · Payment worker reacts to payment-related domain events
- Ordering → Inbox/Outbox: uses · Ordering relies on transactional outbox and inbox safety patterns
- Catalog → Inbox/Outbox: uses · Catalog uses inbox/processed-event handling
- Basket → Inbox/Outbox: uses · Basket uses inbox ledger deduplication
- Webhooks → Inbox/Outbox: uses · Webhooks deduplicates processed integration events
- Ordering → Domain models: uses · Ordering service builds on shared ordering domain rules
- Catalog → Domain models: uses · Catalog service builds on shared catalog rules
- Basket → Domain models: uses · Basket service builds on shared basket rules
- Identity → Domain models: uses · Identity service builds on shared identity rules
- Mobile BFF → Observability: uses · Proxy layer uses shared observability bootstrap and HTTP resilience
- Identity → Observability: uses · Services use shared observability bootstrap and logging
- Catalog → Observability: uses · Services use shared observability bootstrap and logging
- Basket → Observability: uses · Services use shared observability bootstrap and logging
- Ordering → Observability: uses · Services use shared observability bootstrap and logging
- Webhooks → Observability: uses · Services use shared observability bootstrap and logging
- Health pkg → PostgreSQL: checks · Health package includes Postgres probing
- Health pkg → Redis: checks · Health package includes Redis probing
- Health pkg → RabbitMQ: checks · Health package includes RabbitMQ probing
- Storefront → UI kit: consumes · Storefront reuses shared UI primitives
- Webhooks → OpenAPI: aligns · OpenAPI snapshots document the webhook HTTP surface
- Identity → OpenAPI: aligns · OpenAPI snapshots document the identity HTTP surface
- Catalog → OpenAPI: aligns · OpenAPI snapshots document the catalog HTTP surface
- Basket → OpenAPI: aligns · OpenAPI snapshots document the basket HTTP surface
- Ordering → OpenAPI: aligns · OpenAPI snapshots document the ordering HTTP surface
- Mobile BFF → OpenAPI: aligns · OpenAPI snapshots document the BFF surface
- Ordering → Events: emits/consumes · Ordering integration payloads are versioned as golden JSON
- Catalog → Events: emits/consumes · Catalog integration payloads are versioned as golden JSON
- Webhooks → Events: consumes · Webhook consumers rely on canonical event examples
