# abrashee/kml architecture

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

## Overview

KML is an educational logistics platform spanning customer and staff interfaces and independently running backend services. Users browse/search products, manage accounts, place orders, and track shipments; staff manage inventory, warehouses, orders, shipments, and users. The README describes an API gateway, per-service persistence, and brokered domain events. The graph preserves those documented capabilities and the inventory search/projection behavior visible in sampled source; frontend-to-API wiring and detailed gateway routing were not sampled, so those links are shown only at the documented boundary.

Main entry points: [`services/api-gateway/src/main/java/com/kml/services/gateway/ApiGatewayApplication.java`](https://github.com/abrashee/kml/blob/main/services/api-gateway/src/main/java/com/kml/services/gateway/ApiGatewayApplication.java) (API gateway), [`services/inventory-service/src/main/java/com/kml/services/inventory/controller/InventoryController.java`](https://github.com/abrashee/kml/blob/main/services/inventory-service/src/main/java/com/kml/services/inventory/controller/InventoryController.java) (Inventory), [`services/shipment-service/src/main/java/com/kml/services/shipment/controller/ShipmentController.java`](https://github.com/abrashee/kml/blob/main/services/shipment-service/src/main/java/com/kml/services/shipment/controller/ShipmentController.java) (Shipments), [`services/common/src/main/java/com/kml/services/common/events/OrderPlacedEvent.java`](https://github.com/abrashee/kml/blob/main/services/common/src/main/java/com/kml/services/common/events/OrderPlacedEvent.java) (Shared security/events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_customer["Customer UI<br/>[App.tsx]"]
  node_admin["Admin UI<br/>[app.routes.ts]"]
end

subgraph group_edge["API edge"]
  node_gateway["API gateway"]
end

subgraph group_domains["Logistics services"]
  node_user["User and auth"]
  node_orders["Orders"]
  node_inventory["Inventory"]
  node_products["Product catalog"]
  node_warehouses["Warehouses"]
  node_shipments["Shipments"]
end

subgraph group_shared["Shared runtime"]
  node_common["Shared security/events"]
end

subgraph group_integrations["External systems"]
  node_userdb[("User data")]
  node_orderdb[("Order data")]
  node_inventorydb[("Inventory data")]
  node_warehousedb[("Warehouse data")]
  node_shipmentdb[("Shipment data")]
  node_broker["Event broker"]
  node_opensearch[("OpenSearch")]
end

node_customer_actor(("Customer"))
node_staff_actor(("Staff"))

node_customer_actor -->|"uses"| node_customer
node_staff_actor -->|"uses"| node_admin
node_customer -->|"API requests"| node_gateway
node_admin -->|"API requests"| node_gateway
node_gateway -->|"routes requests"| node_user
node_gateway -->|"routes requests"| node_orders
node_gateway -->|"routes requests"| node_inventory
node_gateway -->|"routes requests"| node_products
node_gateway -->|"routes requests"| node_warehouses
node_gateway -->|"routes requests"| node_shipments
node_user -->|"reads/writes"| node_userdb
node_orders -->|"reads/writes"| node_orderdb
node_inventory -->|"reads/writes"| node_inventorydb
node_products -->|"projects catalog"| node_inventorydb
node_warehouses -->|"reads/writes"| node_warehousedb
node_shipments -->|"reads/writes"| node_shipmentdb
node_inventory -->|"indexes/searches"| node_opensearch
node_products -->|"indexes/searches"| node_opensearch
node_orders -->|"publishes order events"| node_broker
node_broker -->|"delivers order events"| node_inventory
node_inventory -.->|"publishes stock events"| node_broker
node_broker -->|"delivers reservation events"| node_shipments
node_shipments -.->|"publishes shipment events"| node_broker
node_common -->|"provides shared auth"| node_user
node_common -->|"provides shared auth"| node_orders
node_common -->|"provides shared auth"| node_inventory
node_common -->|"provides shared auth"| node_shipments

click node_customer "https://github.com/abrashee/kml/blob/main/frontend/customer-frontend/src/App.tsx"
click node_admin "https://github.com/abrashee/kml/blob/main/frontend/admin-frontend/src/app/app.routes.ts"
click node_gateway "https://github.com/abrashee/kml/blob/main/services/api-gateway/src/main/java/com/kml/services/gateway/ApiGatewayApplication.java"
click node_user "https://github.com/abrashee/kml/blob/main/services/user-service/src/main/java/com/kml/user/controller/UserController.java"
click node_orders "https://github.com/abrashee/kml/blob/main/services/order-service/src/main/java/com/kml/services/order/controller/OrderController.java"
click node_inventory "https://github.com/abrashee/kml/blob/main/services/inventory-service/src/main/java/com/kml/services/inventory/controller/InventoryController.java"
click node_products "https://github.com/abrashee/kml/blob/main/services/inventory-service/src/main/java/com/kml/services/inventory/product/ProductController.java"
click node_warehouses "https://github.com/abrashee/kml/blob/main/services/warehouse-service/src/main/java/com/kml/services/warehouse/controller/WarehouseController.java"
click node_shipments "https://github.com/abrashee/kml/blob/main/services/shipment-service/src/main/java/com/kml/services/shipment/controller/ShipmentController.java"
click node_common "https://github.com/abrashee/kml/blob/main/services/common/src/main/java/com/kml/services/common/events/OrderPlacedEvent.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_customer,node_admin toneBlue
class node_gateway toneAmber
class node_user,node_orders,node_inventory,node_products,node_warehouses,node_shipments toneMint
class node_common toneRose
class node_userdb,node_orderdb,node_inventorydb,node_warehousedb,node_shipmentdb,node_broker,node_opensearch,node_customer_actor,node_staff_actor toneIndigo
```

## Components

### User interfaces

- [Customer UI](https://github.com/abrashee/kml/blob/main/frontend/customer-frontend/src/App.tsx): `frontend/customer-frontend/src/App.tsx`
- [Admin UI](https://github.com/abrashee/kml/blob/main/frontend/admin-frontend/src/app/app.routes.ts): `frontend/admin-frontend/src/app/app.routes.ts`

### API edge

- [API gateway](https://github.com/abrashee/kml/blob/main/services/api-gateway/src/main/java/com/kml/services/gateway/ApiGatewayApplication.java): `services/api-gateway/src/main/java/com/kml/services/gateway/ApiGatewayApplication.java`

### Logistics services

- [User and auth](https://github.com/abrashee/kml/blob/main/services/user-service/src/main/java/com/kml/user/controller/UserController.java): `services/user-service/src/main/java/com/kml/user/controller/UserController.java`
- [Orders](https://github.com/abrashee/kml/blob/main/services/order-service/src/main/java/com/kml/services/order/controller/OrderController.java): `services/order-service/src/main/java/com/kml/services/order/controller/OrderController.java`
- [Inventory](https://github.com/abrashee/kml/blob/main/services/inventory-service/src/main/java/com/kml/services/inventory/controller/InventoryController.java): `services/inventory-service/src/main/java/com/kml/services/inventory/controller/InventoryController.java`
- [Product catalog](https://github.com/abrashee/kml/blob/main/services/inventory-service/src/main/java/com/kml/services/inventory/product/ProductController.java): `services/inventory-service/src/main/java/com/kml/services/inventory/product/ProductController.java`
- [Warehouses](https://github.com/abrashee/kml/blob/main/services/warehouse-service/src/main/java/com/kml/services/warehouse/controller/WarehouseController.java): `services/warehouse-service/src/main/java/com/kml/services/warehouse/controller/WarehouseController.java`
- [Shipments](https://github.com/abrashee/kml/blob/main/services/shipment-service/src/main/java/com/kml/services/shipment/controller/ShipmentController.java): `services/shipment-service/src/main/java/com/kml/services/shipment/controller/ShipmentController.java`

### Shared runtime

- [Shared security/events](https://github.com/abrashee/kml/blob/main/services/common/src/main/java/com/kml/services/common/events/OrderPlacedEvent.java): `services/common/src/main/java/com/kml/services/common/events/OrderPlacedEvent.java`

### External systems

- **User data**
- **Order data**
- **Inventory data**
- **Warehouse data**
- **Shipment data**
- **Event broker**
- **OpenSearch**

### Other components

- **Customer**
- **Staff**

## Connections

- Customer → Customer UI: uses
- Staff → Admin UI: uses
- Customer UI → API gateway: API requests
- Admin UI → API gateway: API requests
- API gateway → User and auth: routes requests
- API gateway → Orders: routes requests
- API gateway → Inventory: routes requests
- API gateway → Product catalog: routes requests
- API gateway → Warehouses: routes requests
- API gateway → Shipments: routes requests
- User and auth → User data: reads/writes
- Orders → Order data: reads/writes
- Inventory → Inventory data: reads/writes
- Product catalog → Inventory data: projects catalog
- Warehouses → Warehouse data: reads/writes
- Shipments → Shipment data: reads/writes
- Inventory → OpenSearch: indexes/searches
- Product catalog → OpenSearch: indexes/searches
- Orders → Event broker: publishes order events
- Event broker → Inventory: delivers order events
- Inventory → Event broker: publishes stock events
- Event broker → Shipments: delivers reservation events
- Shipments → Event broker: publishes shipment events
- Shared security/events → User and auth: provides shared auth
- Shared security/events → Orders: provides shared auth
- Shared security/events → Inventory: provides shared auth
- Shared security/events → Shipments: provides shared auth