# mario-pv/e-commerce-modular-monolith architecture

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

- Interactive diagram: https://gitdiagram.com/mario-pv/e-commerce-modular-monolith
- Repository: https://github.com/mario-pv/e-commerce-modular-monolith

## Overview

This is a single-deployment e-commerce modular monolith with a React storefront and Spring backend. Shoppers browse live stock, build a cart or simulate competing purchases, then submit checkout; the order service deducts inventory and persists orders transactionally, while post-commit events feed notifications. Order history and the notification feed are exposed through the observability view. The README documents the transactional outbox, locking strategies, and pagination; unsampled implementation details are represented only where documented, and edge evidence is limited to shown excerpts, indexed references, or the README.

Main entry points: [`frontend/src/App.jsx`](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/App.jsx) (Storefront app), [`frontend/src/api/client.js`](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/api/client.js) (API client), [`src/main/java/com/portfolio/modulith/inventory/InventoryService.java`](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/InventoryService.java) (Inventory service), [`src/main/java/com/portfolio/modulith/order/OrderService.java`](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/order/OrderService.java) (Order service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_app["Storefront app<br/>[App.jsx]"]
  node_catalog_ui["Product catalog<br/>[Catalog.jsx]"]
  node_product_actions["Product actions<br/>[ProductActions.jsx]"]
  node_cart["Cart checkout UI<br/>[Cart.jsx]"]
  node_rush["Rush simulator<br/>[RushSimulator.jsx]"]
  node_observability_ui["Observability UI<br/>[Observability.jsx]"]
  node_api_client["API client<br/>[client.js]"]
end

subgraph group_catalog["Catalog and inventory"]
  node_product_api["Product API"]
  node_inventory_api["Inventory API"]
  node_inventory_service["Inventory service"]
  node_stock_view["Stock view DTO<br/>[StockView.java]"]
  node_stock_repository["Stock repository"]
  node_stock_entity["Stock entity<br/>[Stock.java]"]
end

subgraph group_orders["Checkout and orders"]
  node_order_api["Order API"]
  node_order_service["Order service<br/>[OrderService.java]"]
  node_order_repository["Order repository"]
  node_order_entity["Order entity<br/>[Order.java]"]
  node_order_event["Order-created event"]
  node_outbox[("Event publication outbox")]
end

subgraph group_activity["Notifications and activity"]
  node_notification_listener["Notification listener"]
  node_notification_api["Notification API"]
end

node_shopper(("Shopper"))
node_mysql[("MySQL database")]

node_shopper -->|"uses"| node_app
node_app -->|"renders"| node_catalog_ui
node_app -->|"renders"| node_cart
node_app -->|"opens"| node_rush
node_app -->|"renders"| node_observability_ui
node_app -->|"calls"| node_api_client
node_catalog_ui -->|"renders"| node_product_actions
node_product_actions -.->|"invokes callbacks"| node_app
node_cart -.->|"submits checkout"| node_app
node_rush -.->|"simulates requests"| node_api_client
node_observability_ui -->|"fetches activity"| node_api_client
node_api_client -.->|"requests products"| node_product_api
node_api_client -.->|"requests orders"| node_order_api
node_api_client -.->|"requests notifications"| node_notification_api
node_product_api -->|"reads stock"| node_inventory_service
node_inventory_api -->|"delegates to"| node_inventory_service
node_inventory_service -->|"reads and writes"| node_stock_repository
node_inventory_service -->|"uses"| node_stock_entity
node_inventory_service -->|"maps to"| node_stock_view
node_stock_repository -->|"persists"| node_stock_entity
node_stock_repository -.->|"reads and writes"| node_mysql
node_order_api -->|"delegates to"| node_order_service
node_order_service -->|"deducts stock"| node_inventory_service
node_order_service -->|"saves and queries"| node_order_repository
node_order_repository -->|"persists"| node_order_entity
node_order_repository -.->|"reads and writes"| node_mysql
node_order_service -->|"publishes"| node_order_event
node_order_event -->|"records transactionally"| node_outbox
node_outbox -->|"dispatches after commit"| node_notification_listener
node_notification_listener -->|"handles"| node_order_event
node_notification_api -->|"reads feed"| node_notification_listener

click node_app "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/App.jsx"
click node_catalog_ui "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/Catalog.jsx"
click node_product_actions "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/ProductActions.jsx"
click node_cart "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/Cart.jsx"
click node_rush "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/RushSimulator.jsx"
click node_observability_ui "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/Observability.jsx"
click node_api_client "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/api/client.js"
click node_product_api "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/ProductController.java"
click node_inventory_api "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/InventoryController.java"
click node_inventory_service "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/InventoryService.java"
click node_stock_view "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/StockView.java"
click node_stock_repository "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/internal/StockRepository.java"
click node_stock_entity "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/internal/Stock.java"
click node_order_api "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/order/OrderController.java"
click node_order_service "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/order/OrderService.java"
click node_order_repository "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/order/OrderRepository.java"
click node_order_entity "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/order/Order.java"
click node_order_event "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/order/OrderCreatedEvent.java"
click node_outbox "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/resources/db/migration/V2__modulith_publication_lifecycle.sql"
click node_notification_listener "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/notification/NotificationListener.java"
click node_notification_api "https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/notification/NotificationController.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_app,node_catalog_ui,node_product_actions,node_cart,node_rush,node_observability_ui,node_api_client toneBlue
class node_product_api,node_inventory_api,node_inventory_service,node_stock_view,node_stock_repository,node_stock_entity,node_mysql toneAmber
class node_order_api,node_order_service,node_order_repository,node_order_entity,node_order_event,node_outbox toneMint
class node_notification_listener,node_notification_api toneRose
class node_shopper toneIndigo
```

## Components

### Storefront

- [Storefront app](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Product catalog](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/Catalog.jsx): `frontend/src/Catalog.jsx`
- [Product actions](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/ProductActions.jsx): `frontend/src/ProductActions.jsx`
- [Cart checkout UI](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/Cart.jsx): `frontend/src/Cart.jsx`
- [Rush simulator](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/RushSimulator.jsx): `frontend/src/RushSimulator.jsx`
- [Observability UI](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/Observability.jsx): `frontend/src/Observability.jsx`
- [API client](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Catalog and inventory

- [Product API](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/ProductController.java): `src/main/java/com/portfolio/modulith/inventory/ProductController.java`
- [Inventory API](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/InventoryController.java): `src/main/java/com/portfolio/modulith/inventory/InventoryController.java`
- [Inventory service](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/InventoryService.java): `src/main/java/com/portfolio/modulith/inventory/InventoryService.java`
- [Stock view DTO](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/StockView.java): `src/main/java/com/portfolio/modulith/inventory/StockView.java`
- [Stock repository](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/internal/StockRepository.java): `src/main/java/com/portfolio/modulith/inventory/internal/StockRepository.java`
- [Stock entity](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/inventory/internal/Stock.java): `src/main/java/com/portfolio/modulith/inventory/internal/Stock.java`

### Checkout and orders

- [Order API](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/order/OrderController.java): `src/main/java/com/portfolio/modulith/order/OrderController.java`
- [Order service](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/order/OrderService.java): `src/main/java/com/portfolio/modulith/order/OrderService.java`
- [Order repository](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/order/OrderRepository.java): `src/main/java/com/portfolio/modulith/order/OrderRepository.java`
- [Order entity](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/order/Order.java): `src/main/java/com/portfolio/modulith/order/Order.java`
- [Order-created event](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/order/OrderCreatedEvent.java): `src/main/java/com/portfolio/modulith/order/OrderCreatedEvent.java`
- [Event publication outbox](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/resources/db/migration/V2__modulith_publication_lifecycle.sql): `src/main/resources/db/migration/V2__modulith_publication_lifecycle.sql`

### Notifications and activity

- [Notification listener](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/notification/NotificationListener.java): `src/main/java/com/portfolio/modulith/notification/NotificationListener.java`
- [Notification API](https://github.com/mario-pv/e-commerce-modular-monolith/blob/main/src/main/java/com/portfolio/modulith/notification/NotificationController.java): `src/main/java/com/portfolio/modulith/notification/NotificationController.java`

### Other components

- **Shopper**
- **MySQL database**

## Connections

- Shopper → Storefront app: uses (evidence: `README.md`)
- Storefront app → Product catalog: renders (evidence: `frontend/src/App.jsx`)
- Storefront app → Cart checkout UI: renders (evidence: `frontend/src/App.jsx`)
- Storefront app → Rush simulator: opens (evidence: `frontend/src/App.jsx`)
- Storefront app → Observability UI: renders (evidence: `frontend/src/App.jsx`)
- Storefront app → API client: calls (evidence: `frontend/src/App.jsx`)
- Product catalog → Product actions: renders (evidence: `frontend/src/Catalog.jsx`)
- Product actions → Storefront app: invokes callbacks (evidence: `frontend/src/App.jsx`)
- Cart checkout UI → Storefront app: submits checkout (evidence: `frontend/src/App.jsx`)
- Rush simulator → API client: simulates requests
- Observability UI → API client: fetches activity (evidence: `frontend/src/Observability.jsx`)
- API client → Product API: requests products (evidence: `README.md`)
- API client → Order API: requests orders (evidence: `README.md`)
- API client → Notification API: requests notifications (evidence: `README.md`)
- Product API → Inventory service: reads stock (evidence: `src/main/java/com/portfolio/modulith/inventory/ProductController.java`)
- Inventory API → Inventory service: delegates to (evidence: `src/main/java/com/portfolio/modulith/inventory/InventoryController.java`)
- Inventory service → Stock repository: reads and writes (evidence: `src/main/java/com/portfolio/modulith/inventory/InventoryService.java`)
- Inventory service → Stock entity: uses (evidence: `src/main/java/com/portfolio/modulith/inventory/InventoryService.java`)
- Inventory service → Stock view DTO: maps to (evidence: `src/main/java/com/portfolio/modulith/inventory/InventoryService.java`)
- Stock repository → Stock entity: persists (evidence: `src/main/java/com/portfolio/modulith/inventory/internal/StockRepository.java`)
- Stock repository → MySQL database: reads and writes
- Order API → Order service: delegates to (evidence: `src/main/java/com/portfolio/modulith/order/OrderController.java`)
- Order service → Inventory service: deducts stock (evidence: `src/main/java/com/portfolio/modulith/order/OrderService.java`)
- Order service → Order repository: saves and queries (evidence: `src/main/java/com/portfolio/modulith/order/OrderService.java`)
- Order repository → Order entity: persists (evidence: `src/main/java/com/portfolio/modulith/order/OrderRepository.java`)
- Order repository → MySQL database: reads and writes
- Order service → Order-created event: publishes (evidence: `src/main/java/com/portfolio/modulith/order/OrderService.java`)
- Order-created event → Event publication outbox: records transactionally (evidence: `README.md`)
- Event publication outbox → Notification listener: dispatches after commit (evidence: `README.md`)
- Notification listener → Order-created event: handles (evidence: `src/main/java/com/portfolio/modulith/notification/NotificationListener.java`)
- Notification API → Notification listener: reads feed (evidence: `src/main/java/com/portfolio/modulith/notification/NotificationController.java`)
