# guru173/courier-logistics-management architecture

> Architecture diagram of the GitHub repository guru173/courier-logistics-management, 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/guru173/courier-logistics-management
- Repository: https://github.com/guru173/courier-logistics-management

## Overview

This is a Spring-based courier logistics API. Clients create and query shipments, which are associated with customers, packages, payments, warehouses, and delivery agents; shipment assignment and tracking history support fulfillment. Controllers expose domain operations, services enforce rules and coordinate repositories, and JPA entities represent persisted records. The graph retains the distinct customer, package, payment, warehouse, agent, shipment, and tracking areas. Some controllers and services were not excerpted, so their internal calls are omitted where the index does not establish them.

Main entry points: [`src/main/java/courier/logistics/repository`](https://github.com/guru173/courier-logistics-management/tree/main/src/main/java/courier/logistics/repository) (JPA Repositories), [`src/main/java/courier/logistics/service/ShipmentService.java`](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/ShipmentService.java) (Shipment Service), [`src/main/java/courier/logistics/service/DeliveryAgentService.java`](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/DeliveryAgentService.java) (Agent Service), [`src/main/java/courier/logistics/service/WarehouseService.java`](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/WarehouseService.java) (Warehouse Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_customer_api["Customer API"]
  node_agent_api["Agent API"]
  node_package_api["Package API"]
  node_payment_api["Payment API"]
  node_shipment_api["Shipment API"]
  node_tracking_api["Tracking API"]
  node_warehouse_api["Warehouse API"]
end

subgraph group_services["Domain Services"]
  node_customer_svc["Customer Service"]
  node_agent_svc["Agent Service"]
  node_package_svc["Package Service"]
  node_payment_svc["Payment Service"]
  node_shipment_svc["Shipment Service"]
  node_tracking_svc["Tracking Service"]
  node_warehouse_svc["Warehouse Service"]
end

subgraph group_persistence["Persistence Model"]
  node_repositories["JPA Repositories"]
  node_entities["Logistics Entities"]
end

subgraph group_shared["Shared Handling"]
  node_response["Response Envelope"]
  node_exceptions["Domain Exceptions"]
  node_exception_handler["Exception Mapper"]
end

node_client(("API Client"))

node_client -->|"requests"| node_shipment_api
node_client -->|"requests"| node_agent_api
node_client -->|"requests"| node_warehouse_api
node_client -->|"requests"| node_package_api
node_client -->|"requests"| node_payment_api
node_client -->|"requests"| node_tracking_api
node_shipment_api -->|"delegates to"| node_shipment_svc
node_agent_api -->|"delegates to"| node_agent_svc
node_warehouse_api -->|"delegates to"| node_warehouse_svc
node_package_api -->|"delegates to"| node_package_svc
node_payment_api -->|"delegates to"| node_payment_svc
node_tracking_api -->|"delegates to"| node_tracking_svc
node_shipment_svc -->|"queries and saves"| node_repositories
node_customer_svc -->|"uses repository"| node_repositories
node_agent_svc -->|"uses repository"| node_repositories
node_package_svc -->|"uses repository"| node_repositories
node_payment_svc -->|"uses repository"| node_repositories
node_warehouse_svc -->|"uses repository"| node_repositories
node_shipment_svc -->|"looks up customer"| node_customer_svc
node_shipment_svc -->|"looks up warehouse"| node_warehouse_svc
node_shipment_svc -->|"coordinates agent"| node_agent_svc
node_entities -.-> node_response
node_exception_handler -->|"handles failures"| node_exceptions

click node_customer_api "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/CustomerController.java"
click node_agent_api "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/DeliveryAgentController.java"
click node_package_api "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/PackageController.java"
click node_payment_api "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/PaymentController.java"
click node_shipment_api "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/ShipmentController.java"
click node_tracking_api "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/TrackingHistoryController.java"
click node_warehouse_api "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/WarehouseController.java"
click node_customer_svc "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/CustomerService.java"
click node_agent_svc "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/DeliveryAgentService.java"
click node_package_svc "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/PackageService.java"
click node_payment_svc "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/PaymentService.java"
click node_shipment_svc "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/ShipmentService.java"
click node_tracking_svc "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/TrackingHistoryService.java"
click node_warehouse_svc "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/WarehouseService.java"
click node_repositories "https://github.com/guru173/courier-logistics-management/tree/main/src/main/java/courier/logistics/repository"
click node_entities "https://github.com/guru173/courier-logistics-management/tree/main/src/main/java/courier/logistics/entity"
click node_response "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/dto/ResponseStructure.java"
click node_exceptions "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/exception/InvalidInputException.java"
click node_exception_handler "https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/exception/GlobalExceptionHandler.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_api,node_agent_api,node_package_api,node_payment_api,node_shipment_api,node_tracking_api,node_warehouse_api,node_client toneBlue
class node_customer_svc,node_agent_svc,node_package_svc,node_payment_svc,node_shipment_svc,node_tracking_svc,node_warehouse_svc toneAmber
class node_repositories,node_entities toneMint
class node_response,node_exceptions,node_exception_handler toneRose
```

## Components

### REST API

- [Customer API](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/CustomerController.java): `src/main/java/courier/logistics/controller/CustomerController.java`
- [Agent API](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/DeliveryAgentController.java): `src/main/java/courier/logistics/controller/DeliveryAgentController.java`
- [Package API](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/PackageController.java): `src/main/java/courier/logistics/controller/PackageController.java`
- [Payment API](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/PaymentController.java): `src/main/java/courier/logistics/controller/PaymentController.java`
- [Shipment API](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/ShipmentController.java): `src/main/java/courier/logistics/controller/ShipmentController.java`
- [Tracking API](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/TrackingHistoryController.java): `src/main/java/courier/logistics/controller/TrackingHistoryController.java`
- [Warehouse API](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/controller/WarehouseController.java): `src/main/java/courier/logistics/controller/WarehouseController.java`

### Domain Services

- [Customer Service](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/CustomerService.java): `src/main/java/courier/logistics/service/CustomerService.java`
- [Agent Service](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/DeliveryAgentService.java): `src/main/java/courier/logistics/service/DeliveryAgentService.java`
- [Package Service](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/PackageService.java): `src/main/java/courier/logistics/service/PackageService.java`
- [Payment Service](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/PaymentService.java): `src/main/java/courier/logistics/service/PaymentService.java`
- [Shipment Service](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/ShipmentService.java): `src/main/java/courier/logistics/service/ShipmentService.java`
- [Tracking Service](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/TrackingHistoryService.java): `src/main/java/courier/logistics/service/TrackingHistoryService.java`
- [Warehouse Service](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/service/WarehouseService.java): `src/main/java/courier/logistics/service/WarehouseService.java`

### Persistence Model

- [JPA Repositories](https://github.com/guru173/courier-logistics-management/tree/main/src/main/java/courier/logistics/repository): `src/main/java/courier/logistics/repository`
- [Logistics Entities](https://github.com/guru173/courier-logistics-management/tree/main/src/main/java/courier/logistics/entity): `src/main/java/courier/logistics/entity`

### Shared Handling

- [Response Envelope](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/dto/ResponseStructure.java): `src/main/java/courier/logistics/dto/ResponseStructure.java`
- [Domain Exceptions](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/exception/InvalidInputException.java): `src/main/java/courier/logistics/exception/InvalidInputException.java`
- [Exception Mapper](https://github.com/guru173/courier-logistics-management/blob/main/src/main/java/courier/logistics/exception/GlobalExceptionHandler.java): `src/main/java/courier/logistics/exception/GlobalExceptionHandler.java`

### Other components

- **API Client**

## Connections

- API Client → Shipment API: requests
- API Client → Agent API: requests
- API Client → Warehouse API: requests
- API Client → Package API: requests
- API Client → Payment API: requests
- API Client → Tracking API: requests
- Shipment API → Shipment Service: delegates to (evidence: `src/main/java/courier/logistics/controller/ShipmentController.java`)
- Agent API → Agent Service: delegates to (evidence: `src/main/java/courier/logistics/controller/DeliveryAgentController.java`)
- Warehouse API → Warehouse Service: delegates to (evidence: `src/main/java/courier/logistics/controller/WarehouseController.java`)
- Package API → Package Service: delegates to (evidence: `src/main/java/courier/logistics/controller/PackageController.java`)
- Payment API → Payment Service: delegates to (evidence: `src/main/java/courier/logistics/controller/PaymentController.java`)
- Tracking API → Tracking Service: delegates to (evidence: `src/main/java/courier/logistics/controller/TrackingHistoryController.java`)
- Shipment Service → JPA Repositories: queries and saves (evidence: `src/main/java/courier/logistics/service/ShipmentService.java`)
- Customer Service → JPA Repositories: uses repository (evidence: `src/main/java/courier/logistics/service/CustomerService.java`)
- Agent Service → JPA Repositories: uses repository (evidence: `src/main/java/courier/logistics/service/DeliveryAgentService.java`)
- Package Service → JPA Repositories: uses repository (evidence: `src/main/java/courier/logistics/service/PackageService.java`)
- Payment Service → JPA Repositories: uses repository (evidence: `src/main/java/courier/logistics/service/PaymentService.java`)
- Warehouse Service → JPA Repositories: uses repository (evidence: `src/main/java/courier/logistics/service/WarehouseService.java`)
- Shipment Service → Customer Service: looks up customer (evidence: `src/main/java/courier/logistics/service/ShipmentService.java`)
- Shipment Service → Warehouse Service: looks up warehouse (evidence: `src/main/java/courier/logistics/service/ShipmentService.java`)
- Shipment Service → Agent Service: coordinates agent (evidence: `src/main/java/courier/logistics/service/ShipmentService.java`)
- Logistics Entities → Response Envelope
- Exception Mapper → Domain Exceptions: handles failures (evidence: `src/main/java/courier/logistics/exception/GlobalExceptionHandler.java`)
