# mzotti/ecommerce-nestjs architecture

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

- Interactive diagram: https://gitdiagram.com/mzotti/ecommerce-nestjs
- Repository: https://github.com/mzotti/ecommerce-nestjs

## Overview

Zotti is a full-stack e-commerce platform: shoppers browse products, manage carts and accounts, and submit orders; staff manage catalogue, orders, customers, users, and analytics in the backoffice. The React SPA calls a NestJS API gateway, which routes to domain microservices communicating over RabbitMQ. The graph preserves the documented payment and analytics capabilities and the sampled service-level responsibilities. Internal links use SOURCE INDEX references or excerpts; links documented only at architecture level cite the README.

Main entry points: [`back/apps/api-gateway/src/app.module.ts`](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/api-gateway/src/app.module.ts) (Request routing), [`back/apps/orders-service/src/modules/orders/orders.service.ts`](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/orders-service/src/modules/orders/orders.service.ts) (Order lifecycle), [`front/src/routes/storeRoutes.tsx`](https://github.com/mzotti/ecommerce-nestjs/blob/master/front/src/routes/storeRoutes.tsx) (Store and backoffice UI), [`back/apps/auth-service/src/modules/customers/customers.service.ts`](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/auth-service/src/modules/customers/customers.service.ts) (Customer accounts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React storefront"]
  node_spa["Store and backoffice UI<br/>[storeRoutes.tsx]"]
  node_catalog_ui["Catalogue browsing<br/>[index.tsx]"]
  node_cart_checkout["Cart and checkout<br/>[index.tsx]"]
  node_admin_ui["Backoffice operations"]
  node_client_api["HTTP API client<br/>[api.ts]"]
end

subgraph group_gateway["API gateway"]
  node_gateway["Request routing<br/>[app.module.ts]"]
  node_gateway_auth["JWT and role guards<br/>[roles.guard.ts]"]
  node_analytics_gateway["Analytics endpoints"]
end

subgraph group_identity["Identity and accounts"]
  node_auth["Authentication and users<br/>[auth.service.ts]"]
  node_accounts["Customer accounts"]
  node_addresses["Address management"]
  node_cards["Payment cards"]
end

subgraph group_commerce["Commerce services"]
  node_products["Product catalogue and stock"]
  node_categories["Categories"]
  node_orders["Order lifecycle<br/>[orders.service.ts]"]
  node_order_items["Order items"]
  node_payments["Payment processing<br/>[payment.service.ts]"]
  node_provider_factory["Payment provider selection"]
end

subgraph group_insights["Analytics"]
  node_analytics["Order and product analytics"]
end

node_shopper(("Shopper or staff"))
node_database[("PostgreSQL data access<br/>[prisma.service.ts]")]
node_rabbit["RabbitMQ"]
node_payment_provider["External payment provider"]

node_shopper -->|"uses"| node_spa
node_spa -->|"routes to"| node_catalog_ui
node_spa -->|"routes to"| node_cart_checkout
node_spa -->|"routes to"| node_admin_ui
node_catalog_ui -.->|"requests data"| node_client_api
node_cart_checkout -.->|"submits orders"| node_client_api
node_admin_ui -.->|"requests operations"| node_client_api
node_client_api -->|"calls API"| node_gateway
node_gateway -.->|"guards access"| node_gateway_auth
node_gateway -->|"routes requests"| node_auth
node_gateway -->|"routes requests"| node_products
node_gateway -->|"routes requests"| node_orders
node_gateway -.->|"routes requests"| node_payments
node_gateway -.->|"routes requests"| node_analytics_gateway
node_analytics_gateway -.->|"requests reports"| node_analytics
node_auth -.->|"manages"| node_accounts
node_accounts -.->|"manages"| node_addresses
node_accounts -.->|"manages"| node_cards
node_products -.->|"uses"| node_categories
node_orders -->|"uses"| node_order_items
node_orders -->|"coordinates"| node_payments
node_payments -->|"selects provider"| node_provider_factory
node_provider_factory -.->|"dispatches payment"| node_payment_provider
node_products -->|"consumes order events"| node_rabbit
node_orders -->|"consumes status events"| node_rabbit
node_accounts -.->|"persists data"| node_database
node_products -.->|"persists catalogue"| node_database
node_orders -.->|"persists orders"| node_database

click node_spa "https://github.com/mzotti/ecommerce-nestjs/blob/master/front/src/routes/storeRoutes.tsx"
click node_catalog_ui "https://github.com/mzotti/ecommerce-nestjs/blob/master/front/src/pages/store/Products/index.tsx"
click node_cart_checkout "https://github.com/mzotti/ecommerce-nestjs/blob/master/front/src/pages/store/Checkout/index.tsx"
click node_admin_ui "https://github.com/mzotti/ecommerce-nestjs/blob/master/front/src/routes/backofficeRoutes.tsx"
click node_client_api "https://github.com/mzotti/ecommerce-nestjs/blob/master/front/src/services/api.ts"
click node_gateway "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/api-gateway/src/app.module.ts"
click node_gateway_auth "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/api-gateway/src/common/jwt/roles.guard.ts"
click node_auth "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/auth-service/src/modules/auth/auth.service.ts"
click node_accounts "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/auth-service/src/modules/customers/customers.service.ts"
click node_addresses "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/auth-service/src/modules/addresses/addresses.service.ts"
click node_cards "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/auth-service/src/modules/payment-cards/payment-cards.service.ts"
click node_products "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/products-service/src/modules/products/products.service.ts"
click node_categories "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/products-service/src/modules/categories/categories.service.ts"
click node_orders "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/orders-service/src/modules/orders/orders.service.ts"
click node_order_items "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/orders-service/src/modules/orders-items/orders-items.service.ts"
click node_payments "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/payments-service/src/modules/payment/payment.service.ts"
click node_provider_factory "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/payments-service/src/modules/payment/providers/payment-provider.factory.ts"
click node_analytics_gateway "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/api-gateway/src/modules/backoffice/analytics/analytics.controller.ts"
click node_analytics "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/analytics-service/src/modules/analytics/analytics.service.ts"
click node_database "https://github.com/mzotti/ecommerce-nestjs/blob/master/back/libs/database/src/prisma.service.ts"

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_spa,node_catalog_ui,node_cart_checkout,node_admin_ui,node_client_api toneBlue
class node_gateway,node_gateway_auth,node_analytics_gateway,node_database toneAmber
class node_auth,node_accounts,node_addresses,node_cards toneMint
class node_products,node_categories,node_orders,node_order_items,node_payments,node_provider_factory toneRose
class node_analytics,node_shopper,node_rabbit,node_payment_provider toneIndigo
```

## Components

### React storefront

- [Store and backoffice UI](https://github.com/mzotti/ecommerce-nestjs/blob/master/front/src/routes/storeRoutes.tsx): `front/src/routes/storeRoutes.tsx`
- [Catalogue browsing](https://github.com/mzotti/ecommerce-nestjs/blob/master/front/src/pages/store/Products/index.tsx): `front/src/pages/store/Products/index.tsx`
- [Cart and checkout](https://github.com/mzotti/ecommerce-nestjs/blob/master/front/src/pages/store/Checkout/index.tsx): `front/src/pages/store/Checkout/index.tsx`
- [Backoffice operations](https://github.com/mzotti/ecommerce-nestjs/blob/master/front/src/routes/backofficeRoutes.tsx): `front/src/routes/backofficeRoutes.tsx`
- [HTTP API client](https://github.com/mzotti/ecommerce-nestjs/blob/master/front/src/services/api.ts): `front/src/services/api.ts`

### API gateway

- [Request routing](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/api-gateway/src/app.module.ts): `back/apps/api-gateway/src/app.module.ts`
- [JWT and role guards](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/api-gateway/src/common/jwt/roles.guard.ts): `back/apps/api-gateway/src/common/jwt/roles.guard.ts`
- [Analytics endpoints](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/api-gateway/src/modules/backoffice/analytics/analytics.controller.ts): `back/apps/api-gateway/src/modules/backoffice/analytics/analytics.controller.ts`

### Identity and accounts

- [Authentication and users](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/auth-service/src/modules/auth/auth.service.ts): `back/apps/auth-service/src/modules/auth/auth.service.ts`
- [Customer accounts](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/auth-service/src/modules/customers/customers.service.ts): `back/apps/auth-service/src/modules/customers/customers.service.ts`
- [Address management](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/auth-service/src/modules/addresses/addresses.service.ts): `back/apps/auth-service/src/modules/addresses/addresses.service.ts`
- [Payment cards](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/auth-service/src/modules/payment-cards/payment-cards.service.ts): `back/apps/auth-service/src/modules/payment-cards/payment-cards.service.ts`

### Commerce services

- [Product catalogue and stock](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/products-service/src/modules/products/products.service.ts): `back/apps/products-service/src/modules/products/products.service.ts`
- [Categories](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/products-service/src/modules/categories/categories.service.ts): `back/apps/products-service/src/modules/categories/categories.service.ts`
- [Order lifecycle](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/orders-service/src/modules/orders/orders.service.ts): `back/apps/orders-service/src/modules/orders/orders.service.ts`
- [Order items](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/orders-service/src/modules/orders-items/orders-items.service.ts): `back/apps/orders-service/src/modules/orders-items/orders-items.service.ts`
- [Payment processing](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/payments-service/src/modules/payment/payment.service.ts): `back/apps/payments-service/src/modules/payment/payment.service.ts`
- [Payment provider selection](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/payments-service/src/modules/payment/providers/payment-provider.factory.ts): `back/apps/payments-service/src/modules/payment/providers/payment-provider.factory.ts`

### Analytics

- [Order and product analytics](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/apps/analytics-service/src/modules/analytics/analytics.service.ts): `back/apps/analytics-service/src/modules/analytics/analytics.service.ts`

### Other components

- **Shopper or staff**
- [PostgreSQL data access](https://github.com/mzotti/ecommerce-nestjs/blob/master/back/libs/database/src/prisma.service.ts): `back/libs/database/src/prisma.service.ts`
- **RabbitMQ**
- **External payment provider**

## Connections

- Shopper or staff → Store and backoffice UI: uses
- Store and backoffice UI → Catalogue browsing: routes to (evidence: `front/src/routes/storeRoutes.tsx`)
- Store and backoffice UI → Cart and checkout: routes to (evidence: `front/src/routes/storeRoutes.tsx`)
- Store and backoffice UI → Backoffice operations: routes to (evidence: `front/src/routes.tsx`)
- Catalogue browsing → HTTP API client: requests data
- Cart and checkout → HTTP API client: submits orders
- Backoffice operations → HTTP API client: requests operations
- HTTP API client → Request routing: calls API
- Request routing → JWT and role guards: guards access
- Request routing → Authentication and users: routes requests
- Request routing → Product catalogue and stock: routes requests
- Request routing → Order lifecycle: routes requests
- Request routing → Payment processing: routes requests (evidence: `back/apps/payments-service/src/modules/payment/payment.service.ts`)
- Request routing → Analytics endpoints: routes requests
- Analytics endpoints → Order and product analytics: requests reports
- Authentication and users → Customer accounts: manages
- Customer accounts → Address management: manages
- Customer accounts → Payment cards: manages
- Product catalogue and stock → Categories: uses
- Order lifecycle → Order items: uses (evidence: `back/apps/orders-service/src/modules/orders/orders.service.ts`)
- Order lifecycle → Payment processing: coordinates (evidence: `back/apps/orders-service/src/modules/orders/orders.service.ts`)
- Payment processing → Payment provider selection: selects provider (evidence: `back/apps/payments-service/src/modules/payment/payment.service.ts`)
- Payment provider selection → External payment provider: dispatches payment
- Product catalogue and stock → RabbitMQ: consumes order events
- Order lifecycle → RabbitMQ: consumes status events
- Customer accounts → PostgreSQL data access: persists data
- Product catalogue and stock → PostgreSQL data access: persists catalogue
- Order lifecycle → PostgreSQL data access: persists orders
