# triramisu/shop architecture

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

- Interactive diagram: https://gitdiagram.com/triramisu/shop
- Repository: https://github.com/triramisu/shop

## Overview

Shop is a Java/Spring modular-monolith e-commerce application, currently adding hosted payment. Its documented product spans identity, catalog, inventory, cart/checkout/order, and payment. The principal flow is a customer managing a cart, requesting checkout, and progressing through order and inventory reservation toward payment; administration and storefront catalog access are separate capabilities. The README documents module boundaries, while sampled source confirms authentication/CAPTCHA, catalog persistence, cart transactions, and inventory-orchestration state. Unsampled payment and some integration details are represented only at documented module level.

Main entry points: [`src/main/java/com/shop/order/internal/checkout/controller/CheckoutController.java`](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/checkout/controller/CheckoutController.java) (Checkout API), [`src/main/java/com/shop/order/internal/checkout/service/OrderCreationService.java`](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/checkout/service/OrderCreationService.java) (Order creation), [`src/main/java/com/shop/identity/internal/controller/AuthenticationController.java`](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/identity/internal/controller/AuthenticationController.java) (Authentication API), [`src/main/java/com/shop/identity/internal/service/AuthenticationService.java`](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/identity/internal/service/AuthenticationService.java) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_auth_api["Authentication API"]
  node_auth_service["Authentication"]
  node_captcha["Adaptive CAPTCHA"]
  node_identity_admin["User and role admin"]
end

subgraph group_catalog["Catalog and storefront"]
  node_catalog_admin["Catalog administration"]
  node_catalog_service["Catalog products"]
  node_catalog_store["Storefront catalog"]
  node_catalog_images["Product images"]
  node_catalog_data[("Catalog persistence")]
end

subgraph group_order["Cart and orders"]
  node_cart_api["Cart API"]
  node_cart_tx["Cart transactions"]
  node_checkout_api["Checkout API"]
  node_pricing["Checkout pricing"]
  node_order_create["Order creation"]
  node_inventory_orch["Reservation orchestration"]
end

subgraph group_inventory["Stock management"]
  node_inventory_admin["Inventory administration"]
  node_reservation["Stock reservations"]
  node_stock_target["Stock target lookup"]
  node_stock_data[("Inventory persistence")]
end

subgraph group_payment["Payment"]
  node_payment_init["Payment initiation"]
  node_hosted_return["Hosted checkout return"]
  node_payment_data[("Payment attempts")]
end

node_customer(("Customer"))
node_admin(("Administrator"))

node_customer -->|"authenticates"| node_auth_api
node_auth_api -.->|"handles requests"| node_auth_service
node_auth_service -->|"verifies challenge"| node_captcha
node_admin -.->|"administers users"| node_identity_admin
node_admin -.->|"manages catalog"| node_catalog_admin
node_customer -.->|"browses catalog"| node_catalog_store
node_catalog_admin -.->|"manages products"| node_catalog_service
node_catalog_service -->|"reads and writes"| node_catalog_data
node_customer -.->|"updates cart"| node_cart_api
node_cart_api -.->|"handles cart"| node_cart_tx
node_customer -.->|"requests checkout"| node_checkout_api
node_checkout_api -.->|"quotes checkout"| node_pricing
node_checkout_api -.->|"creates order"| node_order_create
node_order_create -.->|"coordinates stock"| node_inventory_orch
node_inventory_orch -.->|"requests reservation"| node_reservation
node_inventory_admin -.->|"manages stock"| node_stock_data
node_reservation -->|"resolves target"| node_stock_target
node_stock_target -->|"looks up item"| node_stock_data
node_order_create -.->|"initiates payment"| node_payment_init
node_payment_init -.->|"records attempt"| node_payment_data
node_customer -.->|"returns from checkout"| node_hosted_return

click node_auth_api "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/identity/internal/controller/AuthenticationController.java"
click node_auth_service "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/identity/internal/service/AuthenticationService.java"
click node_captcha "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/identity/internal/captcha/service/AdaptiveCaptchaService.java"
click node_identity_admin "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/identity/internal/administration/service/SystemUserAdministrationService.java"
click node_catalog_admin "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/catalog/internal/controller/CatalogAdministrationController.java"
click node_catalog_service "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/catalog/internal/service/CatalogProductService.java"
click node_catalog_store "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/catalog/internal/storefront/service/StorefrontCatalogService.java"
click node_catalog_images "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/catalog/internal/image/service/ProductImageService.java"
click node_catalog_data "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/catalog/internal/repository/ProductRepository.java"
click node_cart_api "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/controller/CartController.java"
click node_cart_tx "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/service/CartTransactionService.java"
click node_checkout_api "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/checkout/controller/CheckoutController.java"
click node_pricing "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/checkout/service/CheckoutPricingService.java"
click node_order_create "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/checkout/service/OrderCreationService.java"
click node_inventory_orch "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/checkout/orchestration/OrderInventoryOrchestration.java"
click node_inventory_admin "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/inventory/internal/controller/InventoryAdministrationController.java"
click node_reservation "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/inventory/internal/service/StockReservationService.java"
click node_stock_target "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/inventory/internal/service/StockReservationTargetQueryService.java"
click node_stock_data "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/inventory/internal/repository/StockItemRepository.java"
click node_payment_init "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/payment/internal/service/PaymentInitiationService.java"
click node_hosted_return "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/payment/internal/checkout/HostedCheckoutReturnController.java"
click node_payment_data "https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/payment/internal/repository/PaymentAttemptRepository.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_auth_api,node_auth_service,node_captcha,node_identity_admin toneBlue
class node_catalog_admin,node_catalog_service,node_catalog_store,node_catalog_images,node_catalog_data toneAmber
class node_cart_api,node_cart_tx,node_checkout_api,node_pricing,node_order_create,node_inventory_orch toneMint
class node_inventory_admin,node_reservation,node_stock_target,node_stock_data toneRose
class node_payment_init,node_hosted_return,node_payment_data,node_customer,node_admin toneIndigo
```

## Components

### Identity and access

- [Authentication API](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/identity/internal/controller/AuthenticationController.java): `src/main/java/com/shop/identity/internal/controller/AuthenticationController.java`
- [Authentication](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/identity/internal/service/AuthenticationService.java): `src/main/java/com/shop/identity/internal/service/AuthenticationService.java`
- [Adaptive CAPTCHA](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/identity/internal/captcha/service/AdaptiveCaptchaService.java): `src/main/java/com/shop/identity/internal/captcha/service/AdaptiveCaptchaService.java`
- [User and role admin](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/identity/internal/administration/service/SystemUserAdministrationService.java): `src/main/java/com/shop/identity/internal/administration/service/SystemUserAdministrationService.java`

### Catalog and storefront

- [Catalog administration](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/catalog/internal/controller/CatalogAdministrationController.java): `src/main/java/com/shop/catalog/internal/controller/CatalogAdministrationController.java`
- [Catalog products](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/catalog/internal/service/CatalogProductService.java): `src/main/java/com/shop/catalog/internal/service/CatalogProductService.java`
- [Storefront catalog](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/catalog/internal/storefront/service/StorefrontCatalogService.java): `src/main/java/com/shop/catalog/internal/storefront/service/StorefrontCatalogService.java`
- [Product images](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/catalog/internal/image/service/ProductImageService.java): `src/main/java/com/shop/catalog/internal/image/service/ProductImageService.java`
- [Catalog persistence](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/catalog/internal/repository/ProductRepository.java): `src/main/java/com/shop/catalog/internal/repository/ProductRepository.java`

### Cart and orders

- [Cart API](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/controller/CartController.java): `src/main/java/com/shop/order/internal/controller/CartController.java`
- [Cart transactions](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/service/CartTransactionService.java): `src/main/java/com/shop/order/internal/service/CartTransactionService.java`
- [Checkout API](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/checkout/controller/CheckoutController.java): `src/main/java/com/shop/order/internal/checkout/controller/CheckoutController.java`
- [Checkout pricing](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/checkout/service/CheckoutPricingService.java): `src/main/java/com/shop/order/internal/checkout/service/CheckoutPricingService.java`
- [Order creation](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/checkout/service/OrderCreationService.java): `src/main/java/com/shop/order/internal/checkout/service/OrderCreationService.java`
- [Reservation orchestration](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/order/internal/checkout/orchestration/OrderInventoryOrchestration.java): `src/main/java/com/shop/order/internal/checkout/orchestration/OrderInventoryOrchestration.java`

### Stock management

- [Inventory administration](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/inventory/internal/controller/InventoryAdministrationController.java): `src/main/java/com/shop/inventory/internal/controller/InventoryAdministrationController.java`
- [Stock reservations](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/inventory/internal/service/StockReservationService.java): `src/main/java/com/shop/inventory/internal/service/StockReservationService.java`
- [Stock target lookup](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/inventory/internal/service/StockReservationTargetQueryService.java): `src/main/java/com/shop/inventory/internal/service/StockReservationTargetQueryService.java`
- [Inventory persistence](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/inventory/internal/repository/StockItemRepository.java): `src/main/java/com/shop/inventory/internal/repository/StockItemRepository.java`

### Payment

- [Payment initiation](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/payment/internal/service/PaymentInitiationService.java): `src/main/java/com/shop/payment/internal/service/PaymentInitiationService.java`
- [Hosted checkout return](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/payment/internal/checkout/HostedCheckoutReturnController.java): `src/main/java/com/shop/payment/internal/checkout/HostedCheckoutReturnController.java`
- [Payment attempts](https://github.com/triramisu/shop/blob/main/src/main/java/com/shop/payment/internal/repository/PaymentAttemptRepository.java): `src/main/java/com/shop/payment/internal/repository/PaymentAttemptRepository.java`

### Other components

- **Customer**
- **Administrator**

## Connections

- Customer → Authentication API: authenticates
- Authentication API → Authentication: handles requests
- Authentication → Adaptive CAPTCHA: verifies challenge (evidence: `src/main/java/com/shop/identity/internal/service/AuthenticationService.java`)
- Administrator → User and role admin: administers users
- Administrator → Catalog administration: manages catalog
- Customer → Storefront catalog: browses catalog
- Catalog administration → Catalog products: manages products
- Catalog products → Catalog persistence: reads and writes (evidence: `src/main/java/com/shop/catalog/internal/service/CatalogProductService.java`)
- Customer → Cart API: updates cart
- Cart API → Cart transactions: handles cart
- Customer → Checkout API: requests checkout
- Checkout API → Checkout pricing: quotes checkout
- Checkout API → Order creation: creates order
- Order creation → Reservation orchestration: coordinates stock
- Reservation orchestration → Stock reservations: requests reservation
- Inventory administration → Inventory persistence: manages stock
- Stock reservations → Stock target lookup: resolves target (evidence: `src/main/java/com/shop/inventory/internal/service/StockReservationTargetQueryService.java`)
- Stock target lookup → Inventory persistence: looks up item (evidence: `src/main/java/com/shop/inventory/internal/service/StockReservationTargetQueryService.java`)
- Order creation → Payment initiation: initiates payment
- Payment initiation → Payment attempts: records attempt
- Customer → Hosted checkout return: returns from checkout
