# sathvik145/order-fulfillment-platform architecture

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

- Interactive diagram: https://gitdiagram.com/sathvik145/order-fulfillment-platform
- Repository: https://github.com/sathvik145/order-fulfillment-platform

## Overview

This repository implements a Spring-based commerce backend split across catalog, order, inventory, and notification services. The main workflow creates an order, looks up product details, persists the order, and publishes an order-created event; inventory reservation and notification are event-driven branches. Inventory also supports direct stock updates and records reservation outcomes through an outbox. Source excerpts establish the core order, catalog, and inventory service calls, but do not show Kafka publisher/consumer wiring in every service, so those links are marked unverified or omitted.

Main entry points: [`services/order-service/src/main/java/com/sathvik/orderservice/service/OrderService.java`](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/service/OrderService.java) (Order service), [`services/inventory-service/src/main/java/com/sathvik/inventoryservice/service/InventoryService.java`](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/service/InventoryService.java) (Inventory service), [`services/catalog-service/src/main/java/com/sathvik/catalogservice/controller/ProductController.java`](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/catalog-service/src/main/java/com/sathvik/catalogservice/controller/ProductController.java) (Product API), [`services/inventory-service/src/main/java/com/sathvik/inventoryservice/outbox/InventoryOutboxPublisher.java`](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/outbox/InventoryOutboxPublisher.java) (Outbox publisher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Product catalog"]
  node_catalog_api["Product API"]
  node_catalog_service["Product service"]
  node_product_store[("Product repository")]
end

subgraph group_orders["Order processing"]
  node_order_api["Order API"]
  node_order_service["Order service<br/>[OrderService.java]"]
  node_catalog_client["Catalog client<br/>[CatalogClient.java]"]
  node_order_store[("Order repository")]
  node_order_producer["Order event producer"]
  node_order_consumer["Inventory event consumer"]
end

subgraph group_inventory["Stock management"]
  node_inventory_api["Inventory API"]
  node_inventory_service["Inventory service"]
  node_inventory_store[("Inventory repository")]
  node_processed_store[("Processed events")]
  node_outbox_store[("Inventory outbox")]
  node_outbox_publisher["Outbox publisher"]
  node_inventory_producer["Inventory event producer"]
end

subgraph group_notifications["Notifications"]
  node_notification_consumer["Order notification consumer"]
end

node_customer(("API caller"))
node_broker["Kafka broker"]
node_catalog_external["Catalog service endpoint"]

node_customer -->|"submits orders"| node_order_api
node_order_api -->|"delegates requests"| node_order_service
node_order_service -->|"fetches products"| node_catalog_client
node_catalog_client -->|"requests product"| node_catalog_external
node_catalog_external -.->|"routes to API"| node_catalog_api
node_customer -->|"manages products"| node_catalog_api
node_catalog_api -->|"delegates requests"| node_catalog_service
node_catalog_service -->|"reads and saves"| node_product_store
node_order_service -->|"saves and reads"| node_order_store
node_order_service -->|"publishes order event"| node_order_producer
node_order_producer -.->|"sends events"| node_broker
node_broker -.->|"delivers inventory events"| node_order_consumer
node_order_consumer -.->|"updates order status"| node_order_service
node_customer -->|"updates stock"| node_inventory_api
node_inventory_api -->|"updates stock"| node_inventory_service
node_broker -.->|"delivers order events"| node_inventory_service
node_inventory_service -->|"reads and saves"| node_inventory_store
node_inventory_service -->|"checks and records"| node_processed_store
node_inventory_service -->|"writes outcomes"| node_outbox_store
node_outbox_publisher -.->|"reads pending events"| node_outbox_store
node_outbox_publisher -.->|"dispatches events"| node_inventory_producer
node_inventory_producer -.->|"sends outcomes"| node_broker
node_broker -->|"delivers order events"| node_notification_consumer

click node_catalog_api "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/catalog-service/src/main/java/com/sathvik/catalogservice/controller/ProductController.java"
click node_catalog_service "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/catalog-service/src/main/java/com/sathvik/catalogservice/service/ProductService.java"
click node_product_store "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/catalog-service/src/main/java/com/sathvik/catalogservice/repository/ProductRepository.java"
click node_order_api "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/controller/OrderController.java"
click node_order_service "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/service/OrderService.java"
click node_catalog_client "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/client/CatalogClient.java"
click node_order_store "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/repository/OrderRepository.java"
click node_order_producer "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/producer/OrderEventProducer.java"
click node_order_consumer "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/consumer/InventoryEventConsumer.java"
click node_inventory_api "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/controller/InventoryController.java"
click node_inventory_service "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/service/InventoryService.java"
click node_inventory_store "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/repository/InventoryRepository.java"
click node_processed_store "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/repository/ProcessedEventRepository.java"
click node_outbox_store "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/repository/InventoryOutboxRepository.java"
click node_outbox_publisher "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/outbox/InventoryOutboxPublisher.java"
click node_inventory_producer "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/producer/InventoryEventProducer.java"
click node_notification_consumer "https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/notification-service/src/main/java/com/sathvik/notificationservice/consumer/OrderCreatedConsumer.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_catalog_api,node_catalog_service,node_product_store toneBlue
class node_order_api,node_order_service,node_catalog_client,node_order_store,node_order_producer,node_order_consumer toneAmber
class node_inventory_api,node_inventory_service,node_inventory_store,node_processed_store,node_outbox_store,node_outbox_publisher,node_inventory_producer,node_customer toneMint
class node_notification_consumer toneRose
class node_broker,node_catalog_external toneIndigo
```

## Components

### Product catalog

- [Product API](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/catalog-service/src/main/java/com/sathvik/catalogservice/controller/ProductController.java): `services/catalog-service/src/main/java/com/sathvik/catalogservice/controller/ProductController.java`
- [Product service](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/catalog-service/src/main/java/com/sathvik/catalogservice/service/ProductService.java): `services/catalog-service/src/main/java/com/sathvik/catalogservice/service/ProductService.java`
- [Product repository](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/catalog-service/src/main/java/com/sathvik/catalogservice/repository/ProductRepository.java): `services/catalog-service/src/main/java/com/sathvik/catalogservice/repository/ProductRepository.java`

### Order processing

- [Order API](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/controller/OrderController.java): `services/order-service/src/main/java/com/sathvik/orderservice/controller/OrderController.java`
- [Order service](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/service/OrderService.java): `services/order-service/src/main/java/com/sathvik/orderservice/service/OrderService.java`
- [Catalog client](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/client/CatalogClient.java): `services/order-service/src/main/java/com/sathvik/orderservice/client/CatalogClient.java`
- [Order repository](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/repository/OrderRepository.java): `services/order-service/src/main/java/com/sathvik/orderservice/repository/OrderRepository.java`
- [Order event producer](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/producer/OrderEventProducer.java): `services/order-service/src/main/java/com/sathvik/orderservice/producer/OrderEventProducer.java`
- [Inventory event consumer](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/order-service/src/main/java/com/sathvik/orderservice/consumer/InventoryEventConsumer.java): `services/order-service/src/main/java/com/sathvik/orderservice/consumer/InventoryEventConsumer.java`

### Stock management

- [Inventory API](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/controller/InventoryController.java): `services/inventory-service/src/main/java/com/sathvik/inventoryservice/controller/InventoryController.java`
- [Inventory service](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/service/InventoryService.java): `services/inventory-service/src/main/java/com/sathvik/inventoryservice/service/InventoryService.java`
- [Inventory repository](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/repository/InventoryRepository.java): `services/inventory-service/src/main/java/com/sathvik/inventoryservice/repository/InventoryRepository.java`
- [Processed events](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/repository/ProcessedEventRepository.java): `services/inventory-service/src/main/java/com/sathvik/inventoryservice/repository/ProcessedEventRepository.java`
- [Inventory outbox](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/repository/InventoryOutboxRepository.java): `services/inventory-service/src/main/java/com/sathvik/inventoryservice/repository/InventoryOutboxRepository.java`
- [Outbox publisher](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/outbox/InventoryOutboxPublisher.java): `services/inventory-service/src/main/java/com/sathvik/inventoryservice/outbox/InventoryOutboxPublisher.java`
- [Inventory event producer](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/inventory-service/src/main/java/com/sathvik/inventoryservice/producer/InventoryEventProducer.java): `services/inventory-service/src/main/java/com/sathvik/inventoryservice/producer/InventoryEventProducer.java`

### Notifications

- [Order notification consumer](https://github.com/sathvik145/order-fulfillment-platform/blob/main/services/notification-service/src/main/java/com/sathvik/notificationservice/consumer/OrderCreatedConsumer.java): `services/notification-service/src/main/java/com/sathvik/notificationservice/consumer/OrderCreatedConsumer.java`

### Other components

- **API caller**
- **Kafka broker**
- **Catalog service endpoint**

## Connections

- API caller → Order API: submits orders (evidence: `services/order-service/src/main/java/com/sathvik/orderservice/controller/OrderController.java`)
- Order API → Order service: delegates requests (evidence: `services/order-service/src/main/java/com/sathvik/orderservice/controller/OrderController.java`)
- Order service → Catalog client: fetches products (evidence: `services/order-service/src/main/java/com/sathvik/orderservice/service/OrderService.java`)
- Catalog client → Catalog service endpoint: requests product (evidence: `services/order-service/src/main/java/com/sathvik/orderservice/client/CatalogClient.java`)
- Catalog service endpoint → Product API: routes to API
- API caller → Product API: manages products (evidence: `services/catalog-service/src/main/java/com/sathvik/catalogservice/controller/ProductController.java`)
- Product API → Product service: delegates requests (evidence: `services/catalog-service/src/main/java/com/sathvik/catalogservice/controller/ProductController.java`)
- Product service → Product repository: reads and saves (evidence: `services/catalog-service/src/main/java/com/sathvik/catalogservice/service/ProductService.java`)
- Order service → Order repository: saves and reads (evidence: `services/order-service/src/main/java/com/sathvik/orderservice/service/OrderService.java`)
- Order service → Order event producer: publishes order event (evidence: `services/order-service/src/main/java/com/sathvik/orderservice/service/OrderService.java`)
- Order event producer → Kafka broker: sends events
- Kafka broker → Inventory event consumer: delivers inventory events
- Inventory event consumer → Order service: updates order status
- API caller → Inventory API: updates stock (evidence: `services/inventory-service/src/main/java/com/sathvik/inventoryservice/controller/InventoryController.java`)
- Inventory API → Inventory service: updates stock (evidence: `services/inventory-service/src/main/java/com/sathvik/inventoryservice/controller/InventoryController.java`)
- Kafka broker → Inventory service: delivers order events
- Inventory service → Inventory repository: reads and saves (evidence: `services/inventory-service/src/main/java/com/sathvik/inventoryservice/service/InventoryService.java`)
- Inventory service → Processed events: checks and records (evidence: `services/inventory-service/src/main/java/com/sathvik/inventoryservice/service/InventoryService.java`)
- Inventory service → Inventory outbox: writes outcomes (evidence: `services/inventory-service/src/main/java/com/sathvik/inventoryservice/service/InventoryService.java`)
- Outbox publisher → Inventory outbox: reads pending events
- Outbox publisher → Inventory event producer: dispatches events
- Inventory event producer → Kafka broker: sends outcomes
- Kafka broker → Order notification consumer: delivers order events (evidence: `services/notification-service/src/main/java/com/sathvik/notificationservice/consumer/OrderCreatedConsumer.java`)
