# dushi1/microservices-ecommerce architecture

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

- Interactive diagram: https://gitdiagram.com/dushi1/microservices-ecommerce
- Repository: https://github.com/dushi1/microservices-ecommerce

## Overview

This is a full-stack microservices e-commerce platform. A shopper registers or signs in, browses catalog and stock availability, manages a cart, then checks out through an order saga that reserves inventory and authorizes payment; orders can be listed, tracked, or cancelled. The storefront reaches backend services through a REST gateway, while order and product services use gRPC for inventory operations. The graph preserves the documented service capabilities; notification consumption is described as unbuilt, and some service wiring is based on the README because its source was not sampled.

Main entry points: [`ecommerce-micro/apps/product-service/src/handlers.ts`](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/product-service/src/handlers.ts) (Catalog and Search), [`ecommerce-micro/apps/order-service/src/handlers.ts`](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/order-service/src/handlers.ts) (Cart and Checkout Saga), [`ecommerce-micro/apps/api-gateway/src/routes.ts`](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/api-gateway/src/routes.ts) (Gateway Routing), [`ecommerce-micro/apps/auth-service/src/handlers.ts`](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/auth-service/src/handlers.ts) (Accounts and Tokens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_storefront_app["Storefront UI<br/>[App.tsx]"]
  node_storefront_auth["Session Context<br/>[AuthContext.tsx]"]
  node_storefront_api["API Client<br/>[client.ts]"]
end

subgraph group_edge_identity["Edge and Identity"]
  node_gateway_routes["Gateway Routing<br/>[routes.ts]"]
  node_gateway_auth["JWT Edge Auth<br/>[auth.ts]"]
  node_auth_handlers["Accounts and Tokens<br/>[handlers.ts]"]
  node_auth_db_code["Auth Persistence<br/>[db.ts]"]
end

subgraph group_commerce["Commerce Services"]
  node_product_handlers["Catalog and Search<br/>[handlers.ts]"]
  node_product_cache["Catalog Cache<br/>[cache.ts]"]
  node_product_db_code["Catalog Persistence<br/>[db.ts]"]
  node_order_handlers["Cart and Checkout Saga<br/>[handlers.ts]"]
  node_order_db_code["Order Persistence<br/>[db.ts]"]
  node_inventory_handlers["Stock Operations"]
  node_inventory_db_code["Inventory Persistence<br/>[db.ts]"]
  node_payment_handlers["Payment and Refunds"]
  node_payment_db_code["Payment Persistence<br/>[db.ts]"]
end

subgraph group_contracts_events["Contracts and Events"]
  node_grpc_contracts["gRPC Contracts<br/>[grpc.ts]"]
  node_event_publisher["Kafka Publisher<br/>[index.ts]"]
end

node_shopper(("Shopper"))
node_auth_store[("Auth Database")]
node_product_store[("Product Database")]
node_order_store[("Order Database")]
node_inventory_store[("Inventory Database")]
node_payment_store[("Payment Database")]
node_kafka["Kafka Broker"]

node_shopper -->|"uses"| node_storefront_app
node_storefront_app -->|"provides session"| node_storefront_auth
node_storefront_app -->|"requests data"| node_storefront_api
node_storefront_api -->|"sends REST"| node_gateway_routes
node_gateway_routes -->|"checks protected routes"| node_gateway_auth
node_gateway_routes -->|"proxies auth"| node_auth_handlers
node_gateway_routes -->|"proxies catalog"| node_product_handlers
node_gateway_routes -->|"proxies orders"| node_order_handlers
node_gateway_auth -->|"verifies JWT"| node_auth_handlers
node_auth_handlers -->|"queries users and tokens"| node_auth_db_code
node_auth_db_code -->|"reads and writes"| node_auth_store
node_product_handlers -->|"checks and invalidates"| node_product_cache
node_product_handlers -->|"queries catalog"| node_product_db_code
node_product_db_code -->|"reads and writes"| node_product_store
node_product_handlers -->|"gets stock via gRPC"| node_inventory_handlers
node_order_handlers -->|"stores carts and orders"| node_order_db_code
node_order_db_code -->|"reads and writes"| node_order_store
node_order_handlers -->|"fetches product details"| node_product_handlers
node_order_handlers -->|"reserves and releases stock"| node_inventory_handlers
node_order_handlers -->|"authorizes and refunds"| node_payment_handlers
node_inventory_handlers -->|"persists stock state"| node_inventory_db_code
node_inventory_db_code -->|"reads and writes"| node_inventory_store
node_payment_handlers -->|"persists payments"| node_payment_db_code
node_payment_db_code -->|"reads and writes"| node_payment_store
node_order_handlers -->|"uses RPC clients"| node_grpc_contracts
node_product_handlers -->|"uses stock RPC"| node_grpc_contracts
node_auth_handlers -.->|"publishes user events"| node_event_publisher
node_product_handlers -.->|"publishes product events"| node_event_publisher
node_event_publisher -.->|"publishes events"| node_kafka

click node_storefront_app "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/storefront/src/App.tsx"
click node_storefront_auth "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/storefront/src/auth/AuthContext.tsx"
click node_storefront_api "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/storefront/src/api/client.ts"
click node_gateway_routes "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/api-gateway/src/routes.ts"
click node_gateway_auth "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/api-gateway/src/auth.ts"
click node_auth_handlers "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/auth-service/src/handlers.ts"
click node_auth_db_code "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/auth-service/src/db.ts"
click node_product_handlers "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/product-service/src/handlers.ts"
click node_product_cache "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/product-service/src/cache.ts"
click node_product_db_code "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/product-service/src/db.ts"
click node_order_handlers "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/order-service/src/handlers.ts"
click node_order_db_code "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/order-service/src/db.ts"
click node_inventory_handlers "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/inventory-service/src/inventory-handlers.ts"
click node_inventory_db_code "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/inventory-service/src/db.ts"
click node_payment_handlers "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/payment-service/src/payment-handlers.ts"
click node_payment_db_code "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/payment-service/src/db.ts"
click node_grpc_contracts "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/packages/contracts/src/grpc.ts"
click node_event_publisher "https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/packages/events/src/index.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_storefront_app,node_storefront_auth,node_storefront_api toneBlue
class node_gateway_routes,node_gateway_auth,node_auth_handlers,node_auth_db_code,node_auth_store,node_product_store,node_order_store,node_inventory_store,node_payment_store toneAmber
class node_product_handlers,node_product_cache,node_product_db_code,node_order_handlers,node_order_db_code,node_inventory_handlers,node_inventory_db_code,node_payment_handlers,node_payment_db_code toneMint
class node_grpc_contracts,node_event_publisher toneRose
class node_shopper,node_kafka toneIndigo
```

## Components

### Storefront

- [Storefront UI](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/storefront/src/App.tsx): `ecommerce-micro/apps/storefront/src/App.tsx`
- [Session Context](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/storefront/src/auth/AuthContext.tsx): `ecommerce-micro/apps/storefront/src/auth/AuthContext.tsx`
- [API Client](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/storefront/src/api/client.ts): `ecommerce-micro/apps/storefront/src/api/client.ts`

### Edge and Identity

- [Gateway Routing](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/api-gateway/src/routes.ts): `ecommerce-micro/apps/api-gateway/src/routes.ts`
- [JWT Edge Auth](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/api-gateway/src/auth.ts): `ecommerce-micro/apps/api-gateway/src/auth.ts`
- [Accounts and Tokens](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/auth-service/src/handlers.ts): `ecommerce-micro/apps/auth-service/src/handlers.ts`
- [Auth Persistence](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/auth-service/src/db.ts): `ecommerce-micro/apps/auth-service/src/db.ts`

### Commerce Services

- [Catalog and Search](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/product-service/src/handlers.ts): `ecommerce-micro/apps/product-service/src/handlers.ts`
- [Catalog Cache](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/product-service/src/cache.ts): `ecommerce-micro/apps/product-service/src/cache.ts`
- [Catalog Persistence](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/product-service/src/db.ts): `ecommerce-micro/apps/product-service/src/db.ts`
- [Cart and Checkout Saga](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/order-service/src/handlers.ts): `ecommerce-micro/apps/order-service/src/handlers.ts`
- [Order Persistence](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/order-service/src/db.ts): `ecommerce-micro/apps/order-service/src/db.ts`
- [Stock Operations](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/inventory-service/src/inventory-handlers.ts): `ecommerce-micro/apps/inventory-service/src/inventory-handlers.ts`
- [Inventory Persistence](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/inventory-service/src/db.ts): `ecommerce-micro/apps/inventory-service/src/db.ts`
- [Payment and Refunds](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/payment-service/src/payment-handlers.ts): `ecommerce-micro/apps/payment-service/src/payment-handlers.ts`
- [Payment Persistence](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/apps/payment-service/src/db.ts): `ecommerce-micro/apps/payment-service/src/db.ts`

### Contracts and Events

- [gRPC Contracts](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/packages/contracts/src/grpc.ts): `ecommerce-micro/packages/contracts/src/grpc.ts`
- [Kafka Publisher](https://github.com/dushi1/microservices-ecommerce/blob/main/ecommerce-micro/packages/events/src/index.ts): `ecommerce-micro/packages/events/src/index.ts`

### Other components

- **Shopper**
- **Auth Database**
- **Product Database**
- **Order Database**
- **Inventory Database**
- **Payment Database**
- **Kafka Broker**

## Connections

- Shopper → Storefront UI: uses
- Storefront UI → Session Context: provides session
- Storefront UI → API Client: requests data
- API Client → Gateway Routing: sends REST
- Gateway Routing → JWT Edge Auth: checks protected routes
- Gateway Routing → Accounts and Tokens: proxies auth
- Gateway Routing → Catalog and Search: proxies catalog
- Gateway Routing → Cart and Checkout Saga: proxies orders
- JWT Edge Auth → Accounts and Tokens: verifies JWT
- Accounts and Tokens → Auth Persistence: queries users and tokens
- Auth Persistence → Auth Database: reads and writes
- Catalog and Search → Catalog Cache: checks and invalidates
- Catalog and Search → Catalog Persistence: queries catalog
- Catalog Persistence → Product Database: reads and writes
- Catalog and Search → Stock Operations: gets stock via gRPC
- Cart and Checkout Saga → Order Persistence: stores carts and orders
- Order Persistence → Order Database: reads and writes
- Cart and Checkout Saga → Catalog and Search: fetches product details
- Cart and Checkout Saga → Stock Operations: reserves and releases stock
- Cart and Checkout Saga → Payment and Refunds: authorizes and refunds
- Stock Operations → Inventory Persistence: persists stock state
- Inventory Persistence → Inventory Database: reads and writes
- Payment and Refunds → Payment Persistence: persists payments
- Payment Persistence → Payment Database: reads and writes
- Cart and Checkout Saga → gRPC Contracts: uses RPC clients
- Catalog and Search → gRPC Contracts: uses stock RPC
- Accounts and Tokens → Kafka Publisher: publishes user events
- Catalog and Search → Kafka Publisher: publishes product events
- Kafka Publisher → Kafka Broker: publishes events