# sheldon1999/e-commerce-app architecture

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

- Interactive diagram: https://gitdiagram.com/sheldon1999/e-commerce-app
- Repository: https://github.com/sheldon1999/e-commerce-app

## Overview

1. This repository is a small e-commerce platform split into five independently built Spring Boot services plus shared container orchestration. The main architectural boundary is by business capability: catalog, inventory, orders, notifications, and edge routing.

2. The API Gateway is the single external entry point. It contains route configuration only, so its role is request forwarding and path-based routing rather than business logic. The README indicates it also aggregates Swagger/OpenAPI access for the backend services.

3. Product Service owns the product catalog. Its internal shape is a standard Spring layered service: controller → service → repository → MongoDB model/DTOs. The presence of `InventoryFeignClient` and a second inventory client package suggests it also performs synchronous calls to inventory during product-related workflows, likely to enrich responses or coordinate stock checks.

4. Inventory Service owns stock persistence and stock adjustment. It is implemented with Spring Data JPA against MySQL, uses Flyway migrations for schema setup, and has explicit domain exceptions for missing resources and insufficient stock. The `InventoryRequest`/`InventoryResponse` DTOs indicate a dedicated service API around stock operations.

5. Order Service is the orchestration point for checkout/order creation. It has a controller, service, JPA repository, and MySQL-backed `Order` model. It also depends on an inventory client, so order placement appears to synchronously verify or reserve inventory before persisting the order.

6. Order Service is also the main event producer. The `OrderPlacedEvent` class and the Avro schema under `src/main/resources/avro/order-placed.avsc` show that order creation emits a structured domain event, intended for Kafka-based asynchronous consumers.

7. Notification Service is the event-driven consumer side of the system. It has no persistence layer in the tree, which strongly suggests it reacts to order events and performs side effects such as email delivery without owning core business state.

8. The primary synchronous data flow is HTTP/REST between the gateway and the services, and service-to-service calls for inventory coordination. The primary asynchronous flow is Kafka-backed domain events from Order Service to downstream consumers such as Notification Service.

9. Persistence is polyglot and service-owned: Product Service uses MongoDB; Inventory and Order Services use MySQL; Notification Service appears stateless. Each service carries its own migration/init scripts, and the repository includes checked-in local database data directories, indicating a Dockerized development setup with persisted volumes.

10. Containerization is first-class. Every service has a Dockerfile, and there are Compose files at the repo root and in individual services. The root README confirms Docker Compose is used to bring up the full stack, including Kafka, MySQL, MongoDB, and a Kafka UI.

11. The codebase is organized for clean service boundaries: each service has its own `pom.xml`, source tree, test tree, and application bootstrap class. Testcontainers configuration classes in multiple services show that integration tests are expected to run against real backing services rather than mocks alone.

12. OpenAPI configuration exists in Product and Order Services, and the README says Swagger UI is exposed per service and through the gateway. That means documentation is a cross-cutting concern but still deployed per service, not centralized in a separate docs service.

Main entry points: [`docker-compose.yml`](https://github.com/sheldon1999/e-commerce-app/blob/main/docker-compose.yml) (Compose stack), [`api-gateway/src/main/java/com/programming/techie/api_gateway/routes/Routes.java`](https://github.com/sheldon1999/e-commerce-app/blob/main/api-gateway/src/main/java/com/programming/techie/api_gateway/routes/Routes.java) (Routes), [`order-service/src/main/java/com/techie/microservices/order/service/OrderService.java`](https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/service/OrderService.java) (Order service), [`product-service/src/main/java/com/techie/microservices/product/service/ProductService.java`](https://github.com/sheldon1999/e-commerce-app/blob/main/product-service/src/main/java/com/techie/microservices/product/service/ProductService.java) (Product service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge & orchestration"]
  node_root_compose["Compose stack<br/>docker-compose<br/>[docker-compose.yml]"]
  node_gateway_app["API gateway<br/>spring boot edge"]
  node_gateway_routes["Routes<br/>route config<br/>[Routes.java]"]
end

subgraph group_services["Business services"]
  node_product_api["Product API<br/>web controller"]
  node_product_logic["Product service<br/>catalog service"]
  node_product_repo[("Product repo<br/>mongo repository")]
  node_product_api_cfg["OpenAPI config<br/>api docs config<br/>[OpenAPIConfig.java]"]
  node_product_inventory_client["Inventory client<br/>feign client"]
  node_inventory_api["Inventory API<br/>web controller"]
  node_inventory_logic["Inventory service<br/>stock service"]
  node_inventory_repo[("Inventory repo<br/>jpa repository")]
  node_order_api["Order API<br/>web controller"]
  node_order_logic["Order service<br/>checkout service<br/>[OrderService.java]"]
  node_order_repo[("Order repo<br/>jpa repository")]
  node_order_api_cfg["OpenAPI config<br/>api docs config<br/>[OpenAPIConfig.java]"]
  node_order_inventory_client["Inventory client<br/>rest client"]
  node_order_event["Order event<br/>avro domain event"]
  node_notification_svc["Notification service<br/>event consumer"]
end

subgraph group_data["Data stores & messaging"]
  node_kafka_bus["Kafka<br/>message broker"]
  node_mysql_inventory[("Inventory MySQL<br/>mysql store")]
  node_mysql_order[("Order MySQL<br/>mysql store")]
  node_mongo_product[("Product MongoDB<br/>mongodb store")]
end

node_root_compose -->|"starts"| node_gateway_app
node_root_compose -->|"provisions"| node_mysql_inventory
node_root_compose -->|"provisions"| node_mysql_order
node_root_compose -->|"provisions"| node_mongo_product
node_gateway_app -->|"uses"| node_gateway_routes
node_gateway_routes -->|"forwards"| node_product_api
node_gateway_routes -->|"forwards"| node_inventory_api
node_gateway_routes -->|"forwards"| node_order_api
node_product_api -->|"calls"| node_product_logic
node_product_logic -->|"reads/writes"| node_product_repo
node_product_logic -->|"checks stock"| node_product_inventory_client
node_inventory_api -->|"calls"| node_inventory_logic
node_inventory_logic -->|"reads/writes"| node_inventory_repo
node_inventory_repo -->|"stores in"| node_mysql_inventory
node_order_api -->|"calls"| node_order_logic
node_order_logic -->|"verifies stock"| node_order_inventory_client
node_order_logic -->|"reads/writes"| node_order_repo
node_order_repo -->|"stores in"| node_mysql_order
node_product_repo -->|"stores in"| node_mongo_product
node_order_logic -->|"publishes"| node_order_event
node_order_event -->|"streamed on"| node_kafka_bus
node_notification_svc -->|"consumes"| node_kafka_bus
node_order_api_cfg -->|"documents"| node_order_api
node_product_api_cfg -->|"documents"| node_product_api

click node_root_compose "https://github.com/sheldon1999/e-commerce-app/blob/main/docker-compose.yml"
click node_gateway_app "https://github.com/sheldon1999/e-commerce-app/blob/main/api-gateway/src/main/java/com/programming/techie/api_gateway/ApiGatewayApplication.java"
click node_gateway_routes "https://github.com/sheldon1999/e-commerce-app/blob/main/api-gateway/src/main/java/com/programming/techie/api_gateway/routes/Routes.java"
click node_product_api "https://github.com/sheldon1999/e-commerce-app/blob/main/product-service/src/main/java/com/techie/microservices/product/controller/ProductController.java"
click node_product_logic "https://github.com/sheldon1999/e-commerce-app/blob/main/product-service/src/main/java/com/techie/microservices/product/service/ProductService.java"
click node_product_repo "https://github.com/sheldon1999/e-commerce-app/blob/main/product-service/src/main/java/com/techie/microservices/product/repository/ProductRepository.java"
click node_product_api_cfg "https://github.com/sheldon1999/e-commerce-app/blob/main/product-service/src/main/java/com/techie/microservices/product/config/OpenAPIConfig.java"
click node_product_inventory_client "https://github.com/sheldon1999/e-commerce-app/blob/main/product-service/src/main/java/com/techie/microservices/product/client/InventoryFeignClient.java"
click node_inventory_api "https://github.com/sheldon1999/e-commerce-app/blob/main/inventory-service/src/main/java/com/techie/microservices/inventory/controller/InventoryController.java"
click node_inventory_logic "https://github.com/sheldon1999/e-commerce-app/blob/main/inventory-service/src/main/java/com/techie/microservices/inventory/service/InventoryService.java"
click node_inventory_repo "https://github.com/sheldon1999/e-commerce-app/blob/main/inventory-service/src/main/java/com/techie/microservices/inventory/repository/InventoryRepository.java"
click node_order_api "https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/controller/OrderController.java"
click node_order_logic "https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/service/OrderService.java"
click node_order_repo "https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/repository/OrderRepository.java"
click node_order_api_cfg "https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/config/OpenAPIConfig.java"
click node_order_inventory_client "https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/client/InventoryClient.java"
click node_order_event "https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/event/OrderPlacedEvent.java"
click node_notification_svc "https://github.com/sheldon1999/e-commerce-app/blob/main/notification-service/src/main/java/com/techie/microservices/notification/service/NotificationService.java"
click node_mysql_inventory "https://github.com/sheldon1999/e-commerce-app/tree/main/inventory-service/docker/mysql/data"
click node_mysql_order "https://github.com/sheldon1999/e-commerce-app/tree/main/order-service/mysql"
click node_mongo_product "https://github.com/sheldon1999/e-commerce-app/tree/main/product-service/data"

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_root_compose,node_gateway_app,node_gateway_routes toneBlue
class node_product_api,node_product_logic,node_product_repo,node_product_api_cfg,node_product_inventory_client,node_inventory_api,node_inventory_logic,node_inventory_repo,node_order_api,node_order_logic,node_order_repo,node_order_api_cfg,node_order_inventory_client,node_order_event,node_notification_svc toneAmber
class node_kafka_bus,node_mysql_inventory,node_mysql_order,node_mongo_product toneMint
```

## Components

### Edge & orchestration

External entry point and local runtime stack

- [Compose stack](https://github.com/sheldon1999/e-commerce-app/blob/main/docker-compose.yml): docker-compose · Root multi-service orchestration for the full local stack · `docker-compose.yml`
- [API gateway](https://github.com/sheldon1999/e-commerce-app/blob/main/api-gateway/src/main/java/com/programming/techie/api_gateway/ApiGatewayApplication.java): spring boot edge · Single external entry point that forwards requests by route · `api-gateway/src/main/java/com/programming/techie/api_gateway/ApiGatewayApplication.java`
- [Routes](https://github.com/sheldon1999/e-commerce-app/blob/main/api-gateway/src/main/java/com/programming/techie/api_gateway/routes/Routes.java): route config · Path-based forwarding and service aggregation rules · `api-gateway/src/main/java/com/programming/techie/api_gateway/routes/Routes.java`

### Business services

Independently built Spring Boot services

- [Product API](https://github.com/sheldon1999/e-commerce-app/blob/main/product-service/src/main/java/com/techie/microservices/product/controller/ProductController.java): web controller · HTTP surface for catalog operations · `product-service/src/main/java/com/techie/microservices/product/controller/ProductController.java`
- [Product service](https://github.com/sheldon1999/e-commerce-app/blob/main/product-service/src/main/java/com/techie/microservices/product/service/ProductService.java): catalog service · Catalog workflows and inventory-aware coordination · `product-service/src/main/java/com/techie/microservices/product/service/ProductService.java`
- [Product repo](https://github.com/sheldon1999/e-commerce-app/blob/main/product-service/src/main/java/com/techie/microservices/product/repository/ProductRepository.java): mongo repository · Persistence boundary for catalog data · `product-service/src/main/java/com/techie/microservices/product/repository/ProductRepository.java`
- [OpenAPI config](https://github.com/sheldon1999/e-commerce-app/blob/main/product-service/src/main/java/com/techie/microservices/product/config/OpenAPIConfig.java): api docs config · Per-service Swagger/OpenAPI setup · `product-service/src/main/java/com/techie/microservices/product/config/OpenAPIConfig.java`
- [Inventory client](https://github.com/sheldon1999/e-commerce-app/blob/main/product-service/src/main/java/com/techie/microservices/product/client/InventoryFeignClient.java): feign client · Synchronous callout from catalog workflows to inventory · `product-service/src/main/java/com/techie/microservices/product/client/InventoryFeignClient.java`
- [Inventory API](https://github.com/sheldon1999/e-commerce-app/blob/main/inventory-service/src/main/java/com/techie/microservices/inventory/controller/InventoryController.java): web controller · HTTP surface for stock adjustment and lookup · `inventory-service/src/main/java/com/techie/microservices/inventory/controller/InventoryController.java`
- [Inventory service](https://github.com/sheldon1999/e-commerce-app/blob/main/inventory-service/src/main/java/com/techie/microservices/inventory/service/InventoryService.java): stock service · Stock persistence, validation, and adjustment logic · `inventory-service/src/main/java/com/techie/microservices/inventory/service/InventoryService.java`
- [Inventory repo](https://github.com/sheldon1999/e-commerce-app/blob/main/inventory-service/src/main/java/com/techie/microservices/inventory/repository/InventoryRepository.java): jpa repository · Persistence boundary for inventory records · `inventory-service/src/main/java/com/techie/microservices/inventory/repository/InventoryRepository.java`
- [Order API](https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/controller/OrderController.java): web controller · HTTP surface for checkout and order creation · `order-service/src/main/java/com/techie/microservices/order/controller/OrderController.java`
- [Order service](https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/service/OrderService.java): checkout service · Checkout orchestration, inventory verification, and order persistence · `order-service/src/main/java/com/techie/microservices/order/service/OrderService.java`
- [Order repo](https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/repository/OrderRepository.java): jpa repository · Persistence boundary for orders · `order-service/src/main/java/com/techie/microservices/order/repository/OrderRepository.java`
- [OpenAPI config](https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/config/OpenAPIConfig.java): api docs config · Per-service Swagger/OpenAPI setup · `order-service/src/main/java/com/techie/microservices/order/config/OpenAPIConfig.java`
- [Inventory client](https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/client/InventoryClient.java): rest client · Order-time synchronous dependency on inventory · `order-service/src/main/java/com/techie/microservices/order/client/InventoryClient.java`
- [Order event](https://github.com/sheldon1999/e-commerce-app/blob/main/order-service/src/main/java/com/techie/microservices/order/event/OrderPlacedEvent.java): avro domain event · Structured order-placed event published for async consumers · `order-service/src/main/java/com/techie/microservices/order/event/OrderPlacedEvent.java`
- [Notification service](https://github.com/sheldon1999/e-commerce-app/blob/main/notification-service/src/main/java/com/techie/microservices/notification/service/NotificationService.java): event consumer · Consumes order events and performs side effects like notifications · `notification-service/src/main/java/com/techie/microservices/notification/service/NotificationService.java`

### Data stores & messaging

Service-owned persistence and async backbone

- **Kafka**: message broker · Asynchronous event backbone for order-driven workflows
- [Inventory MySQL](https://github.com/sheldon1999/e-commerce-app/tree/main/inventory-service/docker/mysql/data): mysql store · Service-owned relational store for inventory state · `inventory-service/docker/mysql/data`
- [Order MySQL](https://github.com/sheldon1999/e-commerce-app/tree/main/order-service/mysql): mysql store · Service-owned relational store for orders · `order-service/mysql`
- [Product MongoDB](https://github.com/sheldon1999/e-commerce-app/tree/main/product-service/data): mongodb store · Service-owned document store for catalog data · `product-service/data`

## Connections

- Compose stack → API gateway: starts · Compose brings up the gateway alongside the services
- Compose stack → Inventory MySQL: provisions · Local stack includes inventory MySQL with persisted volume
- Compose stack → Order MySQL: provisions · Local stack includes order MySQL with persisted volume
- Compose stack → Product MongoDB: provisions · Local stack includes MongoDB with persisted volume
- API gateway → Routes: uses · Gateway app is driven by route definitions
- Routes → Product API: forwards · Routes expose catalog endpoints through the edge
- Routes → Inventory API: forwards · Routes expose inventory endpoints through the edge
- Routes → Order API: forwards · Routes expose order endpoints through the edge
- Product API → Product service: calls · Controller delegates catalog workflow handling
- Product service → Product repo: reads/writes · Catalog state is persisted via the repository
- Product service → Inventory client: checks stock · Catalog workflows synchronously coordinate with inventory
- Inventory API → Inventory service: calls · Controller delegates stock operations
- Inventory service → Inventory repo: reads/writes · Inventory state is persisted via the repository
- Inventory repo → Inventory MySQL: stores in · Inventory repository persists to MySQL
- Order API → Order service: calls · Controller delegates checkout orchestration
- Order service → Inventory client: verifies stock · Order placement synchronously depends on inventory
- Order service → Order repo: reads/writes · Order state is persisted via the repository
- Order repo → Order MySQL: stores in · Order repository persists to MySQL
- Product repo → Product MongoDB: stores in · Product repository persists to MongoDB
- Order service → Order event: publishes · Order creation emits a structured domain event
- Order event → Kafka: streamed on · Order events are carried on Kafka
- Notification service → Kafka: consumes · Notification service reacts to order events
- OpenAPI config → Order API: documents · OpenAPI config describes the order API
- OpenAPI config → Product API: documents · OpenAPI config describes the product API
