# saurabh240/courier-saas-portal architecture

> Architecture diagram of the GitHub repository saurabh240/courier-saas-portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saurabh240/courier-saas-portal
- Repository: https://github.com/saurabh240/courier-saas-portal

## Overview

Courier SaaS Portal is a multi-role courier-management product: users authenticate, create and manage shipments, assign and track delivery work, and review operational results. The React app routes users to role-specific screens; the Spring backend exposes domain APIs backed by PostgreSQL, with JWT and tenant-aware user management. The tree also shows payment, proof-of-delivery, ETA, notifications, settings, reports, and audit capabilities. Some subsystem links are dashed because their implementation was not sampled; they indicate unverified relationships, not inspected call paths.

Main entry points: [`backend/src/main/java/com/courier/app/orders/service/OrderService.java`](https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/orders/service/OrderService.java) (Order lifecycle), [`frontend/src/App.jsx`](https://github.com/saurabh240/courier-saas-portal/blob/main/frontend/src/App.jsx) (Role-based app), [`backend/src/main/java/com/courier/app/usermgmt/service/UserService.java`](https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/usermgmt/service/UserService.java) (User management), [`backend/src/main/java/com/courier/app/orders/controller/OrderController.java`](https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/orders/controller/OrderController.java) (Order API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Role-based app<br/>[App.jsx]"]
  node_authstate["Auth state<br/>[AuthContext.jsx]"]
  node_roleviews["Role dashboards"]
end

subgraph group_identity["Identity and tenancy"]
  node_authapi["Login and registration"]
  node_userlogic["User management<br/>[UserService.java]"]
  node_userstore[("Users and tenants")]
  node_jwt["JWT security"]
end

subgraph group_fulfillment["Shipment fulfillment"]
  node_ordersapi["Order API"]
  node_orderlogic["Order lifecycle<br/>[OrderService.java]"]
  node_orderstore[("Order records")]
  node_status["Status audit"]
  node_tracking["Live tracking"]
  node_delivery["Delivery operations"]
  node_proof["Delivery proof"]
  node_eta["Delivery ETA"]
end

subgraph group_operations["Operations and insights"]
  node_dashboard["Dashboard metrics"]
  node_reports["Reports export"]
  node_settings["Tenant settings"]
end

subgraph group_integrations["Payments and messaging"]
  node_payments["Payment processing"]
  node_notifications["Delivery notifications"]
end

node_users(("Courier users"))

node_users -->|"uses"| node_app
node_app -->|"checks session"| node_authstate
node_app -->|"routes roles"| node_roleviews
node_authstate -.->|"signs in"| node_authapi
node_authapi -->|"delegates to"| node_userlogic
node_userlogic -->|"persists users"| node_userstore
node_userlogic -->|"sends account email"| node_notifications
node_users -.->|"manages shipments"| node_ordersapi
node_ordersapi -->|"delegates to"| node_orderlogic
node_orderlogic -->|"reads and writes"| node_orderstore
node_orderlogic -.->|"updates status"| node_status
node_users -.->|"tracks delivery"| node_tracking
node_users -.->|"handles delivery"| node_delivery
node_delivery -.->|"records proof"| node_proof
node_tracking -.->|"informs estimate"| node_eta
node_dashboard -->|"queries orders"| node_orderstore
node_dashboard -->|"queries payments"| node_payments
node_users -.->|"reviews metrics"| node_dashboard
node_users -.->|"requests reports"| node_reports
node_users -.->|"configures tenant"| node_settings
node_ordersapi -.->|"initiates payment"| node_payments
node_orderlogic -.->|"publishes order events"| node_notifications
node_users -.->|"authenticates"| node_jwt

click node_app "https://github.com/saurabh240/courier-saas-portal/blob/main/frontend/src/App.jsx"
click node_authstate "https://github.com/saurabh240/courier-saas-portal/blob/main/frontend/src/context/AuthContext.jsx"
click node_roleviews "https://github.com/saurabh240/courier-saas-portal/tree/main/frontend/src/pages"
click node_authapi "https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/usermgmt/controller/UserController.java"
click node_userlogic "https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/usermgmt/service/UserService.java"
click node_userstore "https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/usermgmt"
click node_jwt "https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/config"
click node_ordersapi "https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/orders/controller/OrderController.java"
click node_orderlogic "https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/orders/service/OrderService.java"
click node_orderstore "https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/orders/repository/OrderRepository.java"
click node_status "https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/status/service/ManualStatusUpdateService.java"
click node_tracking "https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/tracking"
click node_delivery "https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/delivery"
click node_proof "https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/proof"
click node_eta "https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/eta"
click node_dashboard "https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/dashboard/service/DashboardService.java"
click node_reports "https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/reports"
click node_settings "https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/settings"
click node_payments "https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/payment"
click node_notifications "https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/notification"

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_app,node_authstate,node_roleviews,node_users toneBlue
class node_authapi,node_userlogic,node_userstore,node_jwt toneAmber
class node_ordersapi,node_orderlogic,node_orderstore,node_status,node_tracking,node_delivery,node_proof,node_eta toneMint
class node_dashboard,node_reports,node_settings toneRose
class node_payments,node_notifications toneIndigo
```

## Components

### Web client

- [Role-based app](https://github.com/saurabh240/courier-saas-portal/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth state](https://github.com/saurabh240/courier-saas-portal/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Role dashboards](https://github.com/saurabh240/courier-saas-portal/tree/main/frontend/src/pages): `frontend/src/pages`

### Identity and tenancy

- [Login and registration](https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/usermgmt/controller/UserController.java): `backend/src/main/java/com/courier/app/usermgmt/controller/UserController.java`
- [User management](https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/usermgmt/service/UserService.java): `backend/src/main/java/com/courier/app/usermgmt/service/UserService.java`
- [Users and tenants](https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/usermgmt): `backend/src/main/java/com/courier/app/usermgmt`
- [JWT security](https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/config): `backend/src/main/java/com/courier/app/config`

### Shipment fulfillment

- [Order API](https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/orders/controller/OrderController.java): `backend/src/main/java/com/courier/app/orders/controller/OrderController.java`
- [Order lifecycle](https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/orders/service/OrderService.java): `backend/src/main/java/com/courier/app/orders/service/OrderService.java`
- [Order records](https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/orders/repository/OrderRepository.java): `backend/src/main/java/com/courier/app/orders/repository/OrderRepository.java`
- [Status audit](https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/status/service/ManualStatusUpdateService.java): `backend/src/main/java/com/courier/app/status/service/ManualStatusUpdateService.java`
- [Live tracking](https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/tracking): `backend/src/main/java/com/courier/app/tracking`
- [Delivery operations](https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/delivery): `backend/src/main/java/com/courier/app/delivery`
- [Delivery proof](https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/proof): `backend/src/main/java/com/courier/app/proof`
- [Delivery ETA](https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/eta): `backend/src/main/java/com/courier/app/eta`

### Operations and insights

- [Dashboard metrics](https://github.com/saurabh240/courier-saas-portal/blob/main/backend/src/main/java/com/courier/app/dashboard/service/DashboardService.java): `backend/src/main/java/com/courier/app/dashboard/service/DashboardService.java`
- [Reports export](https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/reports): `backend/src/main/java/com/courier/app/reports`
- [Tenant settings](https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/settings): `backend/src/main/java/com/courier/app/settings`

### Payments and messaging

- [Payment processing](https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/payment): `backend/src/main/java/com/courier/app/payment`
- [Delivery notifications](https://github.com/saurabh240/courier-saas-portal/tree/main/backend/src/main/java/com/courier/app/notification): `backend/src/main/java/com/courier/app/notification`

### Other components

- **Courier users**

## Connections

- Courier users → Role-based app: uses (evidence: `README.md`)
- Role-based app → Auth state: checks session (evidence: `frontend/src/App.jsx`)
- Role-based app → Role dashboards: routes roles (evidence: `frontend/src/App.jsx`)
- Auth state → Login and registration: signs in
- Login and registration → User management: delegates to (evidence: `backend/src/main/java/com/courier/app/usermgmt/controller/UserController.java`)
- User management → Users and tenants: persists users (evidence: `backend/src/main/java/com/courier/app/usermgmt/service/UserService.java`)
- User management → Delivery notifications: sends account email (evidence: `backend/src/main/java/com/courier/app/usermgmt/service/UserService.java`)
- Courier users → Order API: manages shipments
- Order API → Order lifecycle: delegates to (evidence: `backend/src/main/java/com/courier/app/orders/controller/OrderController.java`)
- Order lifecycle → Order records: reads and writes (evidence: `backend/src/main/java/com/courier/app/orders/service/OrderService.java`)
- Order lifecycle → Status audit: updates status
- Courier users → Live tracking: tracks delivery
- Courier users → Delivery operations: handles delivery
- Delivery operations → Delivery proof: records proof
- Live tracking → Delivery ETA: informs estimate
- Dashboard metrics → Order records: queries orders (evidence: `backend/src/main/java/com/courier/app/dashboard/service/DashboardService.java`)
- Dashboard metrics → Payment processing: queries payments (evidence: `backend/src/main/java/com/courier/app/dashboard/service/DashboardService.java`)
- Courier users → Dashboard metrics: reviews metrics
- Courier users → Reports export: requests reports
- Courier users → Tenant settings: configures tenant
- Order API → Payment processing: initiates payment
- Order lifecycle → Delivery notifications: publishes order events
- Courier users → JWT security: authenticates
