# erkutoguz/ecommerce architecture

> Architecture diagram of the GitHub repository erkutoguz/ecommerce, 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/erkutoguz/ecommerce
- Repository: https://github.com/erkutoguz/ecommerce

## Overview

This is an event-driven e-commerce backend. Customers enter through the API Gateway; registration provisions a customer asynchronously, while commerce requests validate customer and product state before cart checkout creates an order. The Order Workflow Service coordinates stock reservation and payment, then confirms or rejects the order and compensates failures. Kafka carries commands and events; services use transactional outboxes and inbox deduplication, and each business service owns its database. README documents the service topology and Stripe flows; sampled source verifies selected registration, cart, saga, stock, and payment behavior, not every listener or route.

Main entry points: [`api-gateway/src/main/java/dev/erkut/apigateway/ApiGatewayApplication.java`](https://github.com/erkutoguz/ecommerce/blob/main/api-gateway/src/main/java/dev/erkut/apigateway/ApiGatewayApplication.java) (API Gateway), [`payment-service/src/main/java/dev/erkut/paymentservice/payment/application/PaymentService.java`](https://github.com/erkutoguz/ecommerce/blob/main/payment-service/src/main/java/dev/erkut/paymentservice/payment/application/PaymentService.java) (Payment Service), [`order-service/src/main/java/dev/erkut/orderservice/order/application/OrderService.java`](https://github.com/erkutoguz/ecommerce/blob/main/order-service/src/main/java/dev/erkut/orderservice/order/application/OrderService.java) (Order Service), [`auth-service/src/main/java/dev/erkut/authservice/authentication/AuthService.java`](https://github.com/erkutoguz/ecommerce/blob/main/auth-service/src/main/java/dev/erkut/authservice/authentication/AuthService.java) (Auth Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Entry and Identity"]
  node_gateway["API Gateway"]
  node_auth["Auth Service<br/>[AuthService.java]"]
  node_tokens["JWT Issuance"]
end

subgraph group_commerce["Commerce Services"]
  node_customer["Customer Service"]
  node_product["Product Catalog"]
  node_cart["Cart Service<br/>[CartService.java]"]
  node_checkout["Checkout Service"]
  node_order["Order Service<br/>[OrderService.java]"]
end

subgraph group_workflow["Order Coordination"]
  node_saga["Order Saga"]
end

subgraph group_fulfillment["Stock and Payments"]
  node_stock["Stock Service"]
  node_payment["Payment Service"]
end

subgraph group_events["Messaging Backbone"]
  node_kafka["Kafka"]
  node_authdb[("Auth Database")]
  node_customerdb[("Customer Database")]
  node_orderdb[("Order Database")]
  node_sagadb[("Saga Database")]
  node_stockdb[("Stock Database<br/>[StockService.java]")]
  node_paymentdb[("Payment Database")]
end

node_shopper(("Client"))
node_stripe["Stripe"]

node_shopper -->|"HTTP requests"| node_gateway
node_gateway -->|"routes auth"| node_auth
node_gateway -->|"routes customer"| node_customer
node_gateway -->|"routes products"| node_product
node_gateway -->|"routes carts"| node_cart
node_gateway -->|"routes checkout"| node_checkout
node_gateway -->|"routes orders"| node_order
node_gateway -->|"routes payments"| node_payment
node_auth -->|"issues access JWT"| node_tokens
node_auth -->|"reads/writes users"| node_authdb
node_auth -->|"publishes customer command"| node_kafka
node_kafka -->|"delivers customer command"| node_customer
node_customer -->|"persists customers"| node_customerdb
node_cart -->|"validates customer"| node_customer
node_cart -->|"validates products"| node_product
node_checkout -->|"creates order"| node_order
node_order -->|"reads/writes orders"| node_orderdb
node_order -->|"publishes order events"| node_kafka
node_kafka -->|"delivers order events"| node_saga
node_saga -->|"persists saga state"| node_sagadb
node_saga -->|"publishes stock/payment/order commands"| node_kafka
node_kafka -->|"delivers stock commands"| node_stock
node_kafka -->|"delivers payment commands"| node_payment
node_stock -->|"updates inventory/reservations"| node_stockdb
node_stock -->|"publishes stock events"| node_kafka
node_payment -->|"reads/writes payments"| node_paymentdb
node_payment -.->|"creates checkout session"| node_stripe
node_stripe -.->|"forwards webhook"| node_gateway
node_payment -->|"publishes payment events"| node_kafka
node_kafka -->|"delivers stock/payment results"| node_saga
node_kafka -->|"delivers order commands"| node_order

click node_gateway "https://github.com/erkutoguz/ecommerce/blob/main/api-gateway/src/main/java/dev/erkut/apigateway/ApiGatewayApplication.java"
click node_auth "https://github.com/erkutoguz/ecommerce/blob/main/auth-service/src/main/java/dev/erkut/authservice/authentication/AuthService.java"
click node_tokens "https://github.com/erkutoguz/ecommerce/blob/main/auth-service/src/main/java/dev/erkut/authservice/token/AccessTokenService.java"
click node_customer "https://github.com/erkutoguz/ecommerce/blob/main/customer-service/src/main/java/dev/erkut/customerservice/customer/application/CustomerService.java"
click node_product "https://github.com/erkutoguz/ecommerce/blob/main/product-service/src/main/java/dev/erkut/productservice/product/application/ProductService.java"
click node_cart "https://github.com/erkutoguz/ecommerce/blob/main/order-service/src/main/java/dev/erkut/orderservice/cart/application/CartService.java"
click node_checkout "https://github.com/erkutoguz/ecommerce/blob/main/order-service/src/main/java/dev/erkut/orderservice/checkout/application/CheckoutService.java"
click node_order "https://github.com/erkutoguz/ecommerce/blob/main/order-service/src/main/java/dev/erkut/orderservice/order/application/OrderService.java"
click node_saga "https://github.com/erkutoguz/ecommerce/blob/main/order-workflow-service/src/main/java/dev/erkut/orderworkflowservice/saga/application/OrderSagaService.java"
click node_stock "https://github.com/erkutoguz/ecommerce/blob/main/stock-service/src/main/java/dev/erkut/stockservice/reservation/application/ReservationService.java"
click node_payment "https://github.com/erkutoguz/ecommerce/blob/main/payment-service/src/main/java/dev/erkut/paymentservice/payment/application/PaymentService.java"
click node_authdb "https://github.com/erkutoguz/ecommerce/blob/main/auth-service/src/main/java/dev/erkut/authservice/user/AuthUserRepository.java"
click node_customerdb "https://github.com/erkutoguz/ecommerce/blob/main/customer-service/src/main/java/dev/erkut/customerservice/customer/persistence/CustomerRepository.java"
click node_orderdb "https://github.com/erkutoguz/ecommerce/blob/main/order-service/src/main/java/dev/erkut/orderservice/order/persistence/OrderRepository.java"
click node_sagadb "https://github.com/erkutoguz/ecommerce/blob/main/order-workflow-service/src/main/java/dev/erkut/orderworkflowservice/saga/persistence/OrderSagaRepository.java"
click node_stockdb "https://github.com/erkutoguz/ecommerce/blob/main/stock-service/src/main/java/dev/erkut/stockservice/stock/application/StockService.java"
click node_paymentdb "https://github.com/erkutoguz/ecommerce/blob/main/payment-service/src/main/java/dev/erkut/paymentservice/payment/application/PaymentService.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_auth,node_tokens,node_shopper toneBlue
class node_customer,node_product,node_cart,node_checkout,node_order toneAmber
class node_saga toneMint
class node_stock,node_payment toneRose
class node_kafka,node_authdb,node_customerdb,node_orderdb,node_sagadb,node_stockdb,node_paymentdb,node_stripe toneIndigo
```

## Components

### Entry and Identity

- [API Gateway](https://github.com/erkutoguz/ecommerce/blob/main/api-gateway/src/main/java/dev/erkut/apigateway/ApiGatewayApplication.java): `api-gateway/src/main/java/dev/erkut/apigateway/ApiGatewayApplication.java`
- [Auth Service](https://github.com/erkutoguz/ecommerce/blob/main/auth-service/src/main/java/dev/erkut/authservice/authentication/AuthService.java): `auth-service/src/main/java/dev/erkut/authservice/authentication/AuthService.java`
- [JWT Issuance](https://github.com/erkutoguz/ecommerce/blob/main/auth-service/src/main/java/dev/erkut/authservice/token/AccessTokenService.java): `auth-service/src/main/java/dev/erkut/authservice/token/AccessTokenService.java`

### Commerce Services

- [Customer Service](https://github.com/erkutoguz/ecommerce/blob/main/customer-service/src/main/java/dev/erkut/customerservice/customer/application/CustomerService.java): `customer-service/src/main/java/dev/erkut/customerservice/customer/application/CustomerService.java`
- [Product Catalog](https://github.com/erkutoguz/ecommerce/blob/main/product-service/src/main/java/dev/erkut/productservice/product/application/ProductService.java): `product-service/src/main/java/dev/erkut/productservice/product/application/ProductService.java`
- [Cart Service](https://github.com/erkutoguz/ecommerce/blob/main/order-service/src/main/java/dev/erkut/orderservice/cart/application/CartService.java): `order-service/src/main/java/dev/erkut/orderservice/cart/application/CartService.java`
- [Checkout Service](https://github.com/erkutoguz/ecommerce/blob/main/order-service/src/main/java/dev/erkut/orderservice/checkout/application/CheckoutService.java): `order-service/src/main/java/dev/erkut/orderservice/checkout/application/CheckoutService.java`
- [Order Service](https://github.com/erkutoguz/ecommerce/blob/main/order-service/src/main/java/dev/erkut/orderservice/order/application/OrderService.java): `order-service/src/main/java/dev/erkut/orderservice/order/application/OrderService.java`

### Order Coordination

- [Order Saga](https://github.com/erkutoguz/ecommerce/blob/main/order-workflow-service/src/main/java/dev/erkut/orderworkflowservice/saga/application/OrderSagaService.java): `order-workflow-service/src/main/java/dev/erkut/orderworkflowservice/saga/application/OrderSagaService.java`

### Stock and Payments

- [Stock Service](https://github.com/erkutoguz/ecommerce/blob/main/stock-service/src/main/java/dev/erkut/stockservice/reservation/application/ReservationService.java): `stock-service/src/main/java/dev/erkut/stockservice/reservation/application/ReservationService.java`
- [Payment Service](https://github.com/erkutoguz/ecommerce/blob/main/payment-service/src/main/java/dev/erkut/paymentservice/payment/application/PaymentService.java): `payment-service/src/main/java/dev/erkut/paymentservice/payment/application/PaymentService.java`

### Messaging Backbone

- **Kafka**
- [Auth Database](https://github.com/erkutoguz/ecommerce/blob/main/auth-service/src/main/java/dev/erkut/authservice/user/AuthUserRepository.java): `auth-service/src/main/java/dev/erkut/authservice/user/AuthUserRepository.java`
- [Customer Database](https://github.com/erkutoguz/ecommerce/blob/main/customer-service/src/main/java/dev/erkut/customerservice/customer/persistence/CustomerRepository.java): `customer-service/src/main/java/dev/erkut/customerservice/customer/persistence/CustomerRepository.java`
- [Order Database](https://github.com/erkutoguz/ecommerce/blob/main/order-service/src/main/java/dev/erkut/orderservice/order/persistence/OrderRepository.java): `order-service/src/main/java/dev/erkut/orderservice/order/persistence/OrderRepository.java`
- [Saga Database](https://github.com/erkutoguz/ecommerce/blob/main/order-workflow-service/src/main/java/dev/erkut/orderworkflowservice/saga/persistence/OrderSagaRepository.java): `order-workflow-service/src/main/java/dev/erkut/orderworkflowservice/saga/persistence/OrderSagaRepository.java`
- [Stock Database](https://github.com/erkutoguz/ecommerce/blob/main/stock-service/src/main/java/dev/erkut/stockservice/stock/application/StockService.java): `stock-service/src/main/java/dev/erkut/stockservice/stock/application/StockService.java`
- [Payment Database](https://github.com/erkutoguz/ecommerce/blob/main/payment-service/src/main/java/dev/erkut/paymentservice/payment/application/PaymentService.java): `payment-service/src/main/java/dev/erkut/paymentservice/payment/application/PaymentService.java`

### Other components

- **Client**
- **Stripe**

## Connections

- Client → API Gateway: HTTP requests
- API Gateway → Auth Service: routes auth
- API Gateway → Customer Service: routes customer
- API Gateway → Product Catalog: routes products
- API Gateway → Cart Service: routes carts
- API Gateway → Checkout Service: routes checkout
- API Gateway → Order Service: routes orders
- API Gateway → Payment Service: routes payments
- Auth Service → JWT Issuance: issues access JWT
- Auth Service → Auth Database: reads/writes users
- Auth Service → Kafka: publishes customer command
- Kafka → Customer Service: delivers customer command
- Customer Service → Customer Database: persists customers
- Cart Service → Customer Service: validates customer
- Cart Service → Product Catalog: validates products
- Checkout Service → Order Service: creates order
- Order Service → Order Database: reads/writes orders
- Order Service → Kafka: publishes order events
- Kafka → Order Saga: delivers order events
- Order Saga → Saga Database: persists saga state
- Order Saga → Kafka: publishes stock/payment/order commands
- Kafka → Stock Service: delivers stock commands
- Kafka → Payment Service: delivers payment commands
- Stock Service → Stock Database: updates inventory/reservations
- Stock Service → Kafka: publishes stock events
- Payment Service → Payment Database: reads/writes payments
- Payment Service → Stripe: creates checkout session
- Stripe → API Gateway: forwards webhook
- Payment Service → Kafka: publishes payment events
- Kafka → Order Saga: delivers stock/payment results
- Kafka → Order Service: delivers order commands