How senhorrg/eshoponcontainers-nestjs works
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: catalog-service Catalog · basket-service Basket · ordering-service Ordering · mobile-bff Mobile BFF
Components 25
Apps
Runnable services and frontends
- Storefront · Primary browser storefront UI with guest cart state and authenticated basket sync
apps/storefront-web - Mobile BFF · Thin consolidated entry point for mobile-style callers
apps/mobile-bff - Identity · Authentication, account registration, alias resolution, and JWT issuance
apps/identity-service - Catalog · Catalog CRUD, AI-assisted features, image serving, and order-event reactions
apps/catalog-service - Basket · Basket state service with HTTP and gRPC access backed by Redis
apps/basket-service - Ordering · Order orchestration, CQRS handlers, and lifecycle integration flows
apps/ordering-service - Webhooks · Webhook subscription management and outbound event delivery
apps/webhooks-service - Grace Worker · Consumes order grace-period events and advances saga-like flows
apps/order-grace-worker - Payment Worker · Handles payment-related follow-up events in ordering flows
apps/payment-worker
Packages
Shared domain and infrastructure libraries
- Domain models · Shared business rules and aggregates for basket, catalog, identity, and ordering
packages/domains - Auth pkg · Shared JWT verification, claims mapping, and Nest auth helpers
packages/infrastructure/auth - Event bus · Integration event transport, publisher lifecycle, and subscription registry
packages/infrastructure/event-bus-amqp - Inbox/Outbox · Deduplication, transactional outbox appends, and publisher support
packages/infrastructure/inbox - Observability · Structured logging, tracing, correlation IDs, and HTTP app bootstrap
packages/infrastructure/observability - Health pkg · Probe controllers and Postgres, Redis, RabbitMQ indicators
packages/infrastructure/health - UI kit · Reusable interface components for study and dashboard surfaces
packages/infrastructure/ui
Contracts
Interop artifacts and API sources of truth
- OpenAPI · HTTP contract snapshots used to detect service and client drift
contracts/openapi - Events · Canonical integration-event examples and payload shapes
contracts/golden - Basket proto · Basket service gRPC contract
contracts/grpc/basket.proto
Runtime infra
Datastores, messaging, and observability backends
- PostgreSQL · Primary persistence for identity, catalog, ordering, and webhooks
- Redis · Basket state and some worker coordination data
- RabbitMQ · Asynchronous backbone for domain integration events
- Ops stack · Prometheus, Loki, Jaeger, Grafana, and OTel collector for local study deployments
deploy/compose/observability
Connections 48
- 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