# dhruv-techdev/shopsphere-microservices-e-commerce architecture

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

- Interactive diagram: https://gitdiagram.com/dhruv-techdev/shopsphere-microservices-e-commerce
- Repository: https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce
- Video tour (about a minute): https://gitdiagram.com/dhruv-techdev/shopsphere-microservices-e-commerce/video

## Overview

ShopSphere is a Java microservices e-commerce backend. A client enters through the API gateway, registers or logs in for a JWT, browses the catalog, manages a cart, and submits an order. Order creation validates cart and product data, checks inventory, persists a pending order, and clears the cart; Kafka then supports payment, stock updates, and notifications. The README documents discovery, centralized configuration, PostgreSQL, and Redis. Sampled excerpts confirm several service-level calls and event handlers; unsampled wiring is represented only where the README explicitly describes it.

Main entry points: [`shopsphere/api-gateway/src/main/java/com/shopsphere/gateway/ApiGatewayApplication.java`](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/api-gateway/src/main/java/com/shopsphere/gateway/ApiGatewayApplication.java) (API gateway), [`shopsphere/order-service/src/main/java/com/shopsphere/orderservice/service/OrderService.java`](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/order-service/src/main/java/com/shopsphere/orderservice/service/OrderService.java) (Order lifecycle), [`shopsphere/common-lib/src/main/java/com/shopsphere/common/events/Topics.java`](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/common-lib/src/main/java/com/shopsphere/common/events/Topics.java) (Kafka events), [`shopsphere/inventory-service/src/main/java/com/shopsphere/inventoryservice/service/InventoryService.java`](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/inventory-service/src/main/java/com/shopsphere/inventoryservice/service/InventoryService.java) (Stock management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["API and Identity"]
  node_gateway["API gateway"]
  node_jwt["JWT filter"]
  node_users["User and auth<br/>[AuthService.java]"]
end

subgraph group_commerce["Commerce Services"]
  node_products["Catalog and search"]
  node_categories["Categories"]
  node_cart["Cart operations<br/>[CartService.java]"]
  node_orders["Order lifecycle<br/>[OrderService.java]"]
end

subgraph group_fulfillment["Fulfillment Events"]
  node_inventory["Stock management"]
  node_payment["Payment simulation"]
  node_notify["Notifications"]
end

subgraph group_platform["Platform Infrastructure"]
  node_redis[("Cart store")]
  node_orderdb[("Order store")]
  node_inventorydb[("Inventory store")]
  node_paymentdb[("Payment store")]
  node_notifydb[("Notification store")]
  node_kafka["Kafka events<br/>[Topics.java]"]
  node_registry["Eureka registry"]
  node_config["Config server"]
  node_productdb[("Catalog store")]
  node_userdb[("User store")]
end

node_client(("Frontend client"))

node_client -->|"sends requests"| node_gateway
node_gateway -->|"validates protected routes"| node_jwt
node_gateway -->|"routes auth requests"| node_users
node_gateway -->|"routes catalog requests"| node_products
node_gateway -->|"routes cart requests"| node_cart
node_gateway -->|"routes order requests"| node_orders
node_gateway -->|"routes stock requests"| node_inventory
node_gateway -->|"routes payment requests"| node_payment
node_gateway -->|"routes notification requests"| node_notify
node_users -->|"reads and writes users"| node_userdb
node_products -->|"reads and writes catalog"| node_productdb
node_categories -->|"supports catalog categories"| node_products
node_cart -->|"fetches product details"| node_products
node_cart -->|"reads and writes carts"| node_redis
node_orders -->|"fetches and clears cart"| node_cart
node_orders -->|"fetches product details"| node_products
node_orders -->|"checks availability"| node_inventory
node_orders -->|"persists and reads orders"| node_orderdb
node_orders -->|"publishes order events"| node_kafka
node_kafka -->|"delivers order and payment events"| node_inventory
node_kafka -->|"delivers order events"| node_payment
node_payment -->|"reads and writes payments"| node_paymentdb
node_payment -->|"publishes payment outcomes"| node_kafka
node_kafka -->|"delivers order and payment events"| node_notify
node_notify -->|"checks and stores notifications"| node_notifydb
node_inventory -->|"reads and writes stock"| node_inventorydb
node_inventory -.->|"publishes stock events"| node_kafka
node_registry -.->|"supports service discovery"| node_gateway
node_config -.->|"provides configuration"| node_gateway

click node_gateway "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/api-gateway/src/main/java/com/shopsphere/gateway/ApiGatewayApplication.java"
click node_jwt "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/api-gateway/src/main/java/com/shopsphere/gateway/filter/JwtAuthenticationFilter.java"
click node_users "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/user-service/src/main/java/com/shopsphere/userservice/service/AuthService.java"
click node_products "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/product-service/src/main/java/com/shopsphere/productservice/service/ProductService.java"
click node_categories "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/product-service/src/main/java/com/shopsphere/productservice/service/CategoryService.java"
click node_cart "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/cart-service/src/main/java/com/shopsphere/cartservice/service/CartService.java"
click node_redis "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/cart-service/src/main/java/com/shopsphere/cartservice/repository/CartRepository.java"
click node_orders "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/order-service/src/main/java/com/shopsphere/orderservice/service/OrderService.java"
click node_orderdb "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/order-service/src/main/java/com/shopsphere/orderservice/repository/OrderRepository.java"
click node_inventory "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/inventory-service/src/main/java/com/shopsphere/inventoryservice/service/InventoryService.java"
click node_inventorydb "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/inventory-service/src/main/java/com/shopsphere/inventoryservice/repository/InventoryRepository.java"
click node_payment "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/payment-service/src/main/java/com/shopsphere/paymentservice/service/PaymentService.java"
click node_paymentdb "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/payment-service/src/main/java/com/shopsphere/paymentservice/repository/PaymentRepository.java"
click node_notify "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/notification-service/src/main/java/com/shopsphere/notificationservice/service/NotificationService.java"
click node_notifydb "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/notification-service/src/main/java/com/shopsphere/notificationservice/repository/NotificationRepository.java"
click node_kafka "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/common-lib/src/main/java/com/shopsphere/common/events/Topics.java"
click node_registry "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/service-registry/src/main/java/com/shopsphere/registry/ServiceRegistryApplication.java"
click node_config "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/config-service/src/main/java/com/shopsphere/configservice/ConfigServiceApplication.java"
click node_productdb "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/product-service/src/main/java/com/shopsphere/productservice/repository/ProductRepository.java"
click node_userdb "https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/user-service/src/main/java/com/shopsphere/userservice/repository/UserRepository.java"

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_gateway,node_jwt,node_users,node_client toneBlue
class node_products,node_categories,node_cart,node_orders toneAmber
class node_inventory,node_payment,node_notify toneMint
class node_redis,node_orderdb,node_inventorydb,node_paymentdb,node_notifydb,node_kafka,node_registry,node_config,node_productdb,node_userdb toneRose
```

## Components

### API and Identity

- [API gateway](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/api-gateway/src/main/java/com/shopsphere/gateway/ApiGatewayApplication.java): `shopsphere/api-gateway/src/main/java/com/shopsphere/gateway/ApiGatewayApplication.java`
- [JWT filter](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/api-gateway/src/main/java/com/shopsphere/gateway/filter/JwtAuthenticationFilter.java): `shopsphere/api-gateway/src/main/java/com/shopsphere/gateway/filter/JwtAuthenticationFilter.java`
- [User and auth](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/user-service/src/main/java/com/shopsphere/userservice/service/AuthService.java): `shopsphere/user-service/src/main/java/com/shopsphere/userservice/service/AuthService.java`

### Commerce Services

- [Catalog and search](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/product-service/src/main/java/com/shopsphere/productservice/service/ProductService.java): `shopsphere/product-service/src/main/java/com/shopsphere/productservice/service/ProductService.java`
- [Categories](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/product-service/src/main/java/com/shopsphere/productservice/service/CategoryService.java): `shopsphere/product-service/src/main/java/com/shopsphere/productservice/service/CategoryService.java`
- [Cart operations](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/cart-service/src/main/java/com/shopsphere/cartservice/service/CartService.java): `shopsphere/cart-service/src/main/java/com/shopsphere/cartservice/service/CartService.java`
- [Order lifecycle](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/order-service/src/main/java/com/shopsphere/orderservice/service/OrderService.java): `shopsphere/order-service/src/main/java/com/shopsphere/orderservice/service/OrderService.java`

### Fulfillment Events

- [Stock management](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/inventory-service/src/main/java/com/shopsphere/inventoryservice/service/InventoryService.java): `shopsphere/inventory-service/src/main/java/com/shopsphere/inventoryservice/service/InventoryService.java`
- [Payment simulation](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/payment-service/src/main/java/com/shopsphere/paymentservice/service/PaymentService.java): `shopsphere/payment-service/src/main/java/com/shopsphere/paymentservice/service/PaymentService.java`
- [Notifications](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/notification-service/src/main/java/com/shopsphere/notificationservice/service/NotificationService.java): `shopsphere/notification-service/src/main/java/com/shopsphere/notificationservice/service/NotificationService.java`

### Platform Infrastructure

- [Cart store](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/cart-service/src/main/java/com/shopsphere/cartservice/repository/CartRepository.java): `shopsphere/cart-service/src/main/java/com/shopsphere/cartservice/repository/CartRepository.java`
- [Order store](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/order-service/src/main/java/com/shopsphere/orderservice/repository/OrderRepository.java): `shopsphere/order-service/src/main/java/com/shopsphere/orderservice/repository/OrderRepository.java`
- [Inventory store](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/inventory-service/src/main/java/com/shopsphere/inventoryservice/repository/InventoryRepository.java): `shopsphere/inventory-service/src/main/java/com/shopsphere/inventoryservice/repository/InventoryRepository.java`
- [Payment store](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/payment-service/src/main/java/com/shopsphere/paymentservice/repository/PaymentRepository.java): `shopsphere/payment-service/src/main/java/com/shopsphere/paymentservice/repository/PaymentRepository.java`
- [Notification store](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/notification-service/src/main/java/com/shopsphere/notificationservice/repository/NotificationRepository.java): `shopsphere/notification-service/src/main/java/com/shopsphere/notificationservice/repository/NotificationRepository.java`
- [Kafka events](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/common-lib/src/main/java/com/shopsphere/common/events/Topics.java): `shopsphere/common-lib/src/main/java/com/shopsphere/common/events/Topics.java`
- [Eureka registry](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/service-registry/src/main/java/com/shopsphere/registry/ServiceRegistryApplication.java): `shopsphere/service-registry/src/main/java/com/shopsphere/registry/ServiceRegistryApplication.java`
- [Config server](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/config-service/src/main/java/com/shopsphere/configservice/ConfigServiceApplication.java): `shopsphere/config-service/src/main/java/com/shopsphere/configservice/ConfigServiceApplication.java`
- [Catalog store](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/product-service/src/main/java/com/shopsphere/productservice/repository/ProductRepository.java): `shopsphere/product-service/src/main/java/com/shopsphere/productservice/repository/ProductRepository.java`
- [User store](https://github.com/dhruv-techdev/shopsphere-microservices-e-commerce/blob/main/shopsphere/user-service/src/main/java/com/shopsphere/userservice/repository/UserRepository.java): `shopsphere/user-service/src/main/java/com/shopsphere/userservice/repository/UserRepository.java`

### Other components

- **Frontend client**

## Connections

- Frontend client → API gateway: sends requests
- API gateway → JWT filter: validates protected routes
- API gateway → User and auth: routes auth requests
- API gateway → Catalog and search: routes catalog requests
- API gateway → Cart operations: routes cart requests
- API gateway → Order lifecycle: routes order requests
- API gateway → Stock management: routes stock requests
- API gateway → Payment simulation: routes payment requests
- API gateway → Notifications: routes notification requests
- User and auth → User store: reads and writes users
- Catalog and search → Catalog store: reads and writes catalog
- Categories → Catalog and search: supports catalog categories
- Cart operations → Catalog and search: fetches product details
- Cart operations → Cart store: reads and writes carts
- Order lifecycle → Cart operations: fetches and clears cart
- Order lifecycle → Catalog and search: fetches product details
- Order lifecycle → Stock management: checks availability
- Order lifecycle → Order store: persists and reads orders
- Order lifecycle → Kafka events: publishes order events
- Kafka events → Stock management: delivers order and payment events
- Kafka events → Payment simulation: delivers order events
- Payment simulation → Payment store: reads and writes payments
- Payment simulation → Kafka events: publishes payment outcomes
- Kafka events → Notifications: delivers order and payment events
- Notifications → Notification store: checks and stores notifications
- Stock management → Inventory store: reads and writes stock
- Stock management → Kafka events: publishes stock events
- Eureka registry → API gateway: supports service discovery
- Config server → API gateway: provides configuration