# vvr-vikram/enterprise-order-system architecture

> Architecture diagram of the GitHub repository vvr-vikram/enterprise-order-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vvr-vikram/enterprise-order-system
- Repository: https://github.com/vvr-vikram/enterprise-order-system

## Overview

#### Purpose and Runtime
A single-process Spring Boot enterprise order system consolidates user, order, payment, and inventory domains. It exposes HTTP APIs on port 8080 and uses local MySQL ACID transactions rather than Kafka, an API gateway, or distributed sagas. Main entry point: `enterprise-order-system/src/main/java/com/enterprise/order/EnterpriseOrderApplication.java`.

#### HTTP and API Boundary
REST controllers are the external boundary for user lookup, order creation/status, and direct payment processing:
- `enterprise-order-system/src/main/java/com/enterprise/order/controller/OrderController.java`
- `enterprise-order-system/src/main/java/com/enterprise/order/controller/PaymentController.java`
- `enterprise-order-system/src/main/java/com/enterprise/order/controller/UserController.java`

Order request/response contracts reside in `enterprise-order-system/src/main/java/com/enterprise/order/common/OrderRequest.java` and `enterprise-order-system/src/main/java/com/enterprise/order/common/OrderResponse.java`. Cross-cutting API error translation is centralized in `enterprise-order-system/src/main/java/com/enterprise/order/common/GlobalExceptionHandler.java`.

#### Order Orchestration and Transaction Boundary
`OrderService` is the primary business-process coordinator:
- `enterprise-order-system/src/main/java/com/enterprise/order/order/OrderService.java`
- `enterprise-order-system/src/main/java/com/enterprise/order/order/Order.java`
- `enterprise-order-system/src/main/java/com/enterprise/order/order/OrderRepository.java`

For `POST /orders`, it handles the client `Idempotency-Key`, creates a pending order, invokes payment processing and inventory reservation in-process, then marks the order completed. Failure in payment or stock reservation propagates through the local transaction, rolling back order, payment, and inventory changes together. Persisted orders also provide the status-query source of truth.

#### Payment Domain
Payment is a local service dependency of order creation and is also directly callable through its controller. The domain records simulated payment debits/logs via:
- `enterprise-order-system/src/main/java/com/enterprise/order/payment/PaymentService.java`
- `enterprise-order-system/src/main/java/com/enterprise/order/payment/Payment.java`
- `enterprise-order-system/src/main/java/com/enterprise/order/payment/PaymentRepository.java`

Its failure conditions, such as a payment limit being exceeded, are transaction-significant: they abort the enclosing order workflow rather than triggering compensating messages.

#### Inventory Domain
Inventory owns stock state and reservation records:
- `enterprise-order-system/src/main/java/com/enterprise/order/inventory/InventoryService.java`
- `enterprise-order-system/src/main/java/com/enterprise/order/inventory/Inventory.java`
- `enterprise-order-system/src/main/java/com/enterprise/order/inventory/OrderReservation.java`

During order creation, reservation decrements available product stock. Insufficient inventory throws an error and relies on the same database transaction rollback to restore all affected state. Reservation persistence is separated through `OrderReservationRepository.java`.

#### User Domain
User data is a supporting validation/read domain used by the application’s user endpoint and order-related business validation:
- `enterprise-order-system/src/main/java/com/enterprise/order/user/UserService.java`
- `enterprise-order-system/src/main/java/com/enterprise/order/user/User.java`
- `enterprise-order-system/src/main/java/com/enterprise/order/user/UserRepository.java`

#### Persistence and Infrastructure
The sole material external service is local MySQL, expected as `enterprise_order_db` on port 3306. Spring Boot/JPA-style repositories form the persistence boundary; schema and initial mock data are supplied in:
- `enterprise-order-system/src/main/resources/application.properties`
- `enterprise-order-system/src/main/resources/sql/schema.sql`
- `enterprise-order-system/src/main/resources/sql/seed-data.sql`

The Maven build is defined by `enterprise-order-system/pom.xml`; Java 17+ is required.

Main entry points: [`enterprise-order-system/src/main/java/com/enterprise/order/order/OrderService.java`](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/order/OrderService.java) (Order Service), [`enterprise-order-system/src/main/java/com/enterprise/order/controller/OrderController.java`](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/controller/OrderController.java) (Order Controller), [`enterprise-order-system/src/main/java/com/enterprise/order/EnterpriseOrderApplication.java`](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/EnterpriseOrderApplication.java) (Spring Boot App), [`enterprise-order-system/src/main/java/com/enterprise/order/payment/PaymentService.java`](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/payment/PaymentService.java) (Payment Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_order_controller["Order Controller<br/>REST controller"]
  node_payment_controller["Payment Controller<br/>REST controller"]
  node_user_controller["User Controller<br/>REST controller"]
  node_order_contracts["Order API Contracts<br/>DTOs<br/>[OrderRequest.java]"]
  node_exception_handler["Global Error Handler<br/>API error handling"]
end

subgraph group_services["Application Services"]
  node_order_service["Order Service<br/>workflow coordinator<br/>[OrderService.java]"]
  node_payment_service["Payment Service<br/>domain service"]
  node_inventory_service["Inventory Service<br/>domain service"]
  node_user_service["User Service<br/>domain service<br/>[UserService.java]"]
end

subgraph group_persistence["Persistence"]
  node_order_repository["Order Repository<br/>JPA repository"]
  node_payment_repository["Payment Repository<br/>JPA repository"]
  node_reservation_repository["Reservation Repository<br/>JPA repository"]
  node_user_repository["User Repository<br/>JPA repository"]
  node_mysql[("MySQL<br/>local database")]
end

node_app{{"Spring Boot App<br/>runtime"}}

node_app -->|"serves"| node_order_controller
node_app -->|"serves"| node_payment_controller
node_app -->|"serves"| node_user_controller
node_order_controller -->|"uses"| node_order_contracts
node_order_controller -->|"create / status"| node_order_service
node_payment_controller -->|"process payment"| node_payment_service
node_user_controller -->|"lookup"| node_user_service
node_exception_handler -.->|"translates errors for"| node_order_controller
node_order_service -->|"validates user"| node_user_service
node_order_service -->|"processes payment"| node_payment_service
node_order_service -->|"reserves stock"| node_inventory_service
node_order_service -->|"persists order"| node_order_repository
node_payment_service -->|"persists debit"| node_payment_repository
node_inventory_service -->|"persists reservation"| node_reservation_repository
node_user_service -->|"reads users"| node_user_repository
node_order_repository -->|"JPA"| node_mysql
node_payment_repository -->|"JPA"| node_mysql
node_reservation_repository -->|"JPA"| node_mysql
node_user_repository -->|"JPA"| node_mysql

click node_app "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/EnterpriseOrderApplication.java"
click node_order_controller "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/controller/OrderController.java"
click node_payment_controller "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/controller/PaymentController.java"
click node_user_controller "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/controller/UserController.java"
click node_order_contracts "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/common/OrderRequest.java"
click node_exception_handler "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/common/GlobalExceptionHandler.java"
click node_order_service "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/order/OrderService.java"
click node_payment_service "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/payment/PaymentService.java"
click node_inventory_service "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/inventory/InventoryService.java"
click node_user_service "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/user/UserService.java"
click node_order_repository "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/order/OrderRepository.java"
click node_payment_repository "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/payment/PaymentRepository.java"
click node_reservation_repository "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/inventory/OrderReservationRepository.java"
click node_user_repository "https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/user/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_order_controller,node_payment_controller,node_user_controller,node_order_contracts,node_exception_handler toneBlue
class node_order_service,node_payment_service,node_inventory_service,node_user_service toneAmber
class node_order_repository,node_payment_repository,node_reservation_repository,node_user_repository,node_mysql toneMint
class node_app toneNeutral
```

## Components

### HTTP API

- [Order Controller](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/controller/OrderController.java): REST controller · `enterprise-order-system/src/main/java/com/enterprise/order/controller/OrderController.java`
- [Payment Controller](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/controller/PaymentController.java): REST controller · `enterprise-order-system/src/main/java/com/enterprise/order/controller/PaymentController.java`
- [User Controller](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/controller/UserController.java): REST controller · `enterprise-order-system/src/main/java/com/enterprise/order/controller/UserController.java`
- [Order API Contracts](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/common/OrderRequest.java): DTOs · Order request and response payloads. · `enterprise-order-system/src/main/java/com/enterprise/order/common/OrderRequest.java`
- [Global Error Handler](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/common/GlobalExceptionHandler.java): API error handling · `enterprise-order-system/src/main/java/com/enterprise/order/common/GlobalExceptionHandler.java`

### Application Services

- [Order Service](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/order/OrderService.java): workflow coordinator · Owns idempotent order creation, status, and the local transaction. · `enterprise-order-system/src/main/java/com/enterprise/order/order/OrderService.java`
- [Payment Service](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/payment/PaymentService.java): domain service · Records simulated payment debits and logs. · `enterprise-order-system/src/main/java/com/enterprise/order/payment/PaymentService.java`
- [Inventory Service](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/inventory/InventoryService.java): domain service · Reserves stock and decrements availability. · `enterprise-order-system/src/main/java/com/enterprise/order/inventory/InventoryService.java`
- [User Service](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/user/UserService.java): domain service · Supports user lookup and order validation. · `enterprise-order-system/src/main/java/com/enterprise/order/user/UserService.java`

### Persistence

- [Order Repository](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/order/OrderRepository.java): JPA repository · Persists orders and serves status queries. · `enterprise-order-system/src/main/java/com/enterprise/order/order/OrderRepository.java`
- [Payment Repository](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/payment/PaymentRepository.java): JPA repository · `enterprise-order-system/src/main/java/com/enterprise/order/payment/PaymentRepository.java`
- [Reservation Repository](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/inventory/OrderReservationRepository.java): JPA repository · Persists inventory reservation records. · `enterprise-order-system/src/main/java/com/enterprise/order/inventory/OrderReservationRepository.java`
- [User Repository](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/user/UserRepository.java): JPA repository · `enterprise-order-system/src/main/java/com/enterprise/order/user/UserRepository.java`
- **MySQL**: local database · enterprise_order_db on port 3306.

### Other components

- [Spring Boot App](https://github.com/vvr-vikram/enterprise-order-system/blob/master/enterprise-order-system/src/main/java/com/enterprise/order/EnterpriseOrderApplication.java): runtime · Single-process application on port 8080. · `enterprise-order-system/src/main/java/com/enterprise/order/EnterpriseOrderApplication.java`

## Connections

- Spring Boot App → Order Controller: serves
- Spring Boot App → Payment Controller: serves
- Spring Boot App → User Controller: serves
- Order Controller → Order API Contracts: uses
- Order Controller → Order Service: create / status
- Payment Controller → Payment Service: process payment
- User Controller → User Service: lookup
- Global Error Handler → Order Controller: translates errors for
- Order Service → User Service: validates user
- Order Service → Payment Service: processes payment · Part of the order ACID transaction.
- Order Service → Inventory Service: reserves stock · Part of the order ACID transaction.
- Order Service → Order Repository: persists order
- Payment Service → Payment Repository: persists debit
- Inventory Service → Reservation Repository: persists reservation
- User Service → User Repository: reads users
- Order Repository → MySQL: JPA
- Payment Repository → MySQL: JPA
- Reservation Repository → MySQL: JPA
- User Repository → MySQL: JPA