# koushiksai-builds/courier-parcel-tracking architecture

> Architecture diagram of the GitHub repository koushiksai-builds/courier-parcel-tracking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/koushiksai-builds/courier-parcel-tracking
- Repository: https://github.com/koushiksai-builds/courier-parcel-tracking

## Overview

The repository implements a courier parcel-tracking system: users book parcels, follow tracking status and history, and staff manage delivery, payments, notifications, and failed events. The README describes separate services behind an API gateway, with parcel events distributed through RabbitMQ and service data held in separate MySQL schemas. Sampled controllers and services confirm the user, parcel, and tracking request paths and their repository operations. Delivery, payment, and notification internals are unsampled, so their detailed flows are represented only where the README documents them.

Main entry points: [`gateway/src/main/java/edu/vitap/gateway/GatewayApplication.java`](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/gateway/src/main/java/edu/vitap/gateway/GatewayApplication.java) (API gateway), [`common/src/main/java/edu/vitap/common/CommonSecurityConfiguration.java`](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/common/src/main/java/edu/vitap/common/CommonSecurityConfiguration.java) (Shared security), [`parcel-service/src/main/java/com/courier/parcelservice/controller/ParcelController.java`](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/parcel-service/src/main/java/com/courier/parcelservice/controller/ParcelController.java) (Parcel endpoints), [`tracking-service/src/main/java/com/courier/trackingservice/service/TrackingService.java`](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/tracking-service/src/main/java/com/courier/trackingservice/service/TrackingService.java) (Status and history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and identity"]
  node_gateway["API gateway"]
  node_user_api["User endpoints"]
  node_user_logic["User management<br/>[UserService.java]"]
  node_user_store[("User records")]
end

subgraph group_parcel["Parcel lifecycle"]
  node_parcel_api["Parcel endpoints"]
  node_parcel_logic["Booking and status<br/>[ParcelService.java]"]
  node_parcel_store[("Parcel records")]
end

subgraph group_tracking["Tracking"]
  node_tracking_api["Tracking endpoints"]
  node_tracking_logic["Status and history"]
  node_tracking_store[("Tracking records")]
  node_history_store[("Status history")]
end

subgraph group_operations["Delivery and customer operations"]
  node_delivery["Courier assignment and delivery"]
  node_notifications["Customer notifications"]
  node_email["SMTP email"]
  node_failed_events["Failed-event review and retry"]
  node_payments["Payment orders and checkout"]
end

subgraph group_platform["Shared infrastructure"]
  node_broker["RabbitMQ events"]
  node_event_contract["Parcel event contracts"]
  node_security["Shared security"]
  node_mysql[("MySQL schemas")]
end

node_customer(("Customer or staff"))

node_customer -->|"sends requests"| node_gateway
node_gateway -->|"routes requests"| node_user_api
node_gateway -->|"routes requests"| node_parcel_api
node_gateway -->|"routes requests"| node_tracking_api
node_gateway -->|"routes requests"| node_delivery
node_gateway -->|"routes requests"| node_notifications
node_gateway -->|"routes requests"| node_payments
node_user_api -->|"delegates to"| node_user_logic
node_user_logic -->|"reads and writes"| node_user_store
node_user_store -->|"persists users"| node_mysql
node_parcel_api -->|"delegates to"| node_parcel_logic
node_parcel_logic -->|"reads and writes"| node_parcel_store
node_parcel_store -->|"persists parcels"| node_mysql
node_tracking_api -->|"delegates to"| node_tracking_logic
node_tracking_logic -->|"reads and writes"| node_tracking_store
node_tracking_logic -->|"reads and writes"| node_history_store
node_tracking_store -->|"persists status"| node_mysql
node_history_store -->|"persists history"| node_mysql
node_parcel_api -.->|"publishes parcel events"| node_broker
node_broker -->|"delivers parcel events"| node_tracking_logic
node_broker -->|"delivers parcel events"| node_delivery
node_broker -->|"delivers parcel events"| node_notifications
node_broker -->|"delivers parcel events"| node_payments
node_event_contract -->|"configures exchanges"| node_broker
node_notifications -.->|"sends optional email"| node_email
node_customer -.->|"service data stored"| node_mysql
node_security -.->|"configures service security"| node_user_api
node_security -.->|"configures service security"| node_parcel_api
node_security -.->|"configures service security"| node_tracking_api
node_security -.->|"configures service security"| node_delivery
node_security -.->|"configures service security"| node_notifications
node_security -.->|"configures service security"| node_payments
node_customer -->|"requests retry"| node_failed_events

click node_gateway "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/gateway/src/main/java/edu/vitap/gateway/GatewayApplication.java"
click node_user_api "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/user-service/src/main/java/com/courier/userservice/controller/UserController.java"
click node_user_logic "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/user-service/src/main/java/com/courier/userservice/service/UserService.java"
click node_user_store "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/user-service/src/main/java/com/courier/userservice/repository/UserRepository.java"
click node_parcel_api "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/parcel-service/src/main/java/com/courier/parcelservice/controller/ParcelController.java"
click node_parcel_logic "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/parcel-service/src/main/java/com/courier/parcelservice/service/ParcelService.java"
click node_parcel_store "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/parcel-service/src/main/java/com/courier/parcelservice/repository/ParcelRepository.java"
click node_tracking_api "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/tracking-service/src/main/java/com/courier/trackingservice/controller/TrackingController.java"
click node_tracking_logic "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/tracking-service/src/main/java/com/courier/trackingservice/service/TrackingService.java"
click node_tracking_store "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/tracking-service/src/main/java/com/courier/trackingservice/repository/TrackingRecordRepository.java"
click node_history_store "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/tracking-service/src/main/java/com/courier/trackingservice/repository/TrackingHistoryRepository.java"
click node_delivery "https://github.com/koushiksai-builds/courier-parcel-tracking/tree/main/delivery-service/src/main/java/edu/vitap/delivery"
click node_notifications "https://github.com/koushiksai-builds/courier-parcel-tracking/tree/main/notification-service/src/main/java/edu/vitap/notifications"
click node_failed_events "https://github.com/koushiksai-builds/courier-parcel-tracking/tree/main/notification-service/src/main/java/edu/vitap/notifications"
click node_payments "https://github.com/koushiksai-builds/courier-parcel-tracking/tree/main/payment-service/src/main/java/edu/vitap/payments"
click node_event_contract "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/common/src/main/java/edu/vitap/common/ParcelEventConfiguration.java"
click node_security "https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/common/src/main/java/edu/vitap/common/CommonSecurityConfiguration.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_gateway,node_user_api,node_user_logic,node_user_store toneBlue
class node_parcel_api,node_parcel_logic,node_parcel_store toneAmber
class node_tracking_api,node_tracking_logic,node_tracking_store,node_history_store toneMint
class node_delivery,node_notifications,node_email,node_failed_events,node_payments toneRose
class node_broker,node_event_contract,node_security,node_mysql,node_customer toneIndigo
```

## Components

### Access and identity

- [API gateway](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/gateway/src/main/java/edu/vitap/gateway/GatewayApplication.java): `gateway/src/main/java/edu/vitap/gateway/GatewayApplication.java`
- [User endpoints](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/user-service/src/main/java/com/courier/userservice/controller/UserController.java): `user-service/src/main/java/com/courier/userservice/controller/UserController.java`
- [User management](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/user-service/src/main/java/com/courier/userservice/service/UserService.java): `user-service/src/main/java/com/courier/userservice/service/UserService.java`
- [User records](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/user-service/src/main/java/com/courier/userservice/repository/UserRepository.java): `user-service/src/main/java/com/courier/userservice/repository/UserRepository.java`

### Parcel lifecycle

- [Parcel endpoints](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/parcel-service/src/main/java/com/courier/parcelservice/controller/ParcelController.java): `parcel-service/src/main/java/com/courier/parcelservice/controller/ParcelController.java`
- [Booking and status](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/parcel-service/src/main/java/com/courier/parcelservice/service/ParcelService.java): `parcel-service/src/main/java/com/courier/parcelservice/service/ParcelService.java`
- [Parcel records](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/parcel-service/src/main/java/com/courier/parcelservice/repository/ParcelRepository.java): `parcel-service/src/main/java/com/courier/parcelservice/repository/ParcelRepository.java`

### Tracking

- [Tracking endpoints](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/tracking-service/src/main/java/com/courier/trackingservice/controller/TrackingController.java): `tracking-service/src/main/java/com/courier/trackingservice/controller/TrackingController.java`
- [Status and history](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/tracking-service/src/main/java/com/courier/trackingservice/service/TrackingService.java): `tracking-service/src/main/java/com/courier/trackingservice/service/TrackingService.java`
- [Tracking records](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/tracking-service/src/main/java/com/courier/trackingservice/repository/TrackingRecordRepository.java): `tracking-service/src/main/java/com/courier/trackingservice/repository/TrackingRecordRepository.java`
- [Status history](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/tracking-service/src/main/java/com/courier/trackingservice/repository/TrackingHistoryRepository.java): `tracking-service/src/main/java/com/courier/trackingservice/repository/TrackingHistoryRepository.java`

### Delivery and customer operations

- [Courier assignment and delivery](https://github.com/koushiksai-builds/courier-parcel-tracking/tree/main/delivery-service/src/main/java/edu/vitap/delivery): `delivery-service/src/main/java/edu/vitap/delivery`
- [Customer notifications](https://github.com/koushiksai-builds/courier-parcel-tracking/tree/main/notification-service/src/main/java/edu/vitap/notifications): `notification-service/src/main/java/edu/vitap/notifications`
- **SMTP email**
- [Failed-event review and retry](https://github.com/koushiksai-builds/courier-parcel-tracking/tree/main/notification-service/src/main/java/edu/vitap/notifications): `notification-service/src/main/java/edu/vitap/notifications`
- [Payment orders and checkout](https://github.com/koushiksai-builds/courier-parcel-tracking/tree/main/payment-service/src/main/java/edu/vitap/payments): `payment-service/src/main/java/edu/vitap/payments`

### Shared infrastructure

- **RabbitMQ events**
- [Parcel event contracts](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/common/src/main/java/edu/vitap/common/ParcelEventConfiguration.java): `common/src/main/java/edu/vitap/common/ParcelEventConfiguration.java`
- [Shared security](https://github.com/koushiksai-builds/courier-parcel-tracking/blob/main/common/src/main/java/edu/vitap/common/CommonSecurityConfiguration.java): `common/src/main/java/edu/vitap/common/CommonSecurityConfiguration.java`
- **MySQL schemas**

### Other components

- **Customer or staff**

## Connections

- Customer or staff → API gateway: sends requests
- API gateway → User endpoints: routes requests
- API gateway → Parcel endpoints: routes requests
- API gateway → Tracking endpoints: routes requests
- API gateway → Courier assignment and delivery: routes requests
- API gateway → Customer notifications: routes requests
- API gateway → Payment orders and checkout: routes requests
- User endpoints → User management: delegates to (evidence: `user-service/src/main/java/com/courier/userservice/controller/UserController.java`)
- User management → User records: reads and writes (evidence: `user-service/src/main/java/com/courier/userservice/service/UserService.java`)
- User records → MySQL schemas: persists users
- Parcel endpoints → Booking and status: delegates to (evidence: `parcel-service/src/main/java/com/courier/parcelservice/controller/ParcelController.java`)
- Booking and status → Parcel records: reads and writes (evidence: `parcel-service/src/main/java/com/courier/parcelservice/service/ParcelService.java`)
- Parcel records → MySQL schemas: persists parcels
- Tracking endpoints → Status and history: delegates to (evidence: `tracking-service/src/main/java/com/courier/trackingservice/controller/TrackingController.java`)
- Status and history → Tracking records: reads and writes (evidence: `tracking-service/src/main/java/com/courier/trackingservice/service/TrackingService.java`)
- Status and history → Status history: reads and writes (evidence: `tracking-service/src/main/java/com/courier/trackingservice/service/TrackingService.java`)
- Tracking records → MySQL schemas: persists status
- Status history → MySQL schemas: persists history
- Parcel endpoints → RabbitMQ events: publishes parcel events
- RabbitMQ events → Status and history: delivers parcel events
- RabbitMQ events → Courier assignment and delivery: delivers parcel events
- RabbitMQ events → Customer notifications: delivers parcel events
- RabbitMQ events → Payment orders and checkout: delivers parcel events
- Parcel event contracts → RabbitMQ events: configures exchanges (evidence: `common/src/main/java/edu/vitap/common/ParcelEventConfiguration.java`)
- Customer notifications → SMTP email: sends optional email
- Customer or staff → MySQL schemas: service data stored
- Shared security → User endpoints: configures service security
- Shared security → Parcel endpoints: configures service security
- Shared security → Tracking endpoints: configures service security
- Shared security → Courier assignment and delivery: configures service security (evidence: `delivery-service/src/main/java/edu/vitap/delivery/DeliveryServiceApplication.java`)
- Shared security → Customer notifications: configures service security (evidence: `notification-service/src/main/java/edu/vitap/notifications/NotificationServiceApplication.java`)
- Shared security → Payment orders and checkout: configures service security (evidence: `payment-service/src/main/java/edu/vitap/payments/PaymentServiceApplication.java`)
- Customer or staff → Failed-event review and retry: requests retry
