# atifhiba/delivery-tracker architecture

> Architecture diagram of the GitHub repository atifhiba/delivery-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atifhiba/delivery-tracker
- Repository: https://github.com/atifhiba/delivery-tracker

## Overview

DeliveryTracker is a parcel-delivery and live-tracking application with customer, delivery-agent, and admin experiences. Its domain workflow covers account access, parcel registration and status history, delivery assignment and execution, then location, route, and ETA tracking. The sampled services show parcel and delivery state updates and geolocation persistence/calculation; the client tree identifies the role-based dashboards and tracking view. Wiring beyond the sampled excerpts is omitted where callers could not be verified.

Main entry points: [`client/src/App.jsx`](https://github.com/atifhiba/delivery-tracker/blob/main/client/src/App.jsx) (Role-based routing), [`Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/service/GeolocService.java`](https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/service/GeolocService.java) (Location and ETA), [`Server/livraison-service/src/main/java/com/deliverytracker/livraison/service/LivraisonService.java`](https://github.com/atifhiba/delivery-tracker/blob/main/Server/livraison-service/src/main/java/com/deliverytracker/livraison/service/LivraisonService.java) (Assignment and delivery), [`Server/auth-service/src/main/java/com/deliverytracker/auth/service/AuthService.java`](https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/service/AuthService.java) (Registration and tokens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Role-based routing<br/>[App.jsx]"]
  node_auth_pages["Login and register"]
  node_customer_pages["Customer tracking"]
  node_agent_page["Agent dashboard<br/>[AgentDashboard.jsx]"]
  node_admin_page["Admin dashboard<br/>[AdminDashboard.jsx]"]
  node_auth_service_client["Auth API client<br/>[authService.js]"]
  node_parcel_service_client["Parcel API client<br/>[parcelService.js]"]
  node_delivery_service_client["Delivery API client<br/>[deliveryService.js]"]
  node_geoloc_service_client["Geolocation API client<br/>[geolocService.js]"]
  node_websocket_client["Live updates client"]
end

subgraph group_identity["Identity and users"]
  node_auth_controller["Authentication endpoints"]
  node_user_controller["User endpoints"]
  node_auth_logic["Registration and tokens<br/>[AuthService.java]"]
  node_user_logic["User management<br/>[UserService.java]"]
  node_user_store[("Users")]
  node_refresh_store[("Refresh tokens")]
end

subgraph group_parcels["Parcel management"]
  node_parcel_controller["Parcel endpoints"]
  node_parcel_logic["Parcel lifecycle<br/>[ColisService.java]"]
  node_parcel_store[("Parcels")]
  node_history_store[("Status history")]
end

subgraph group_delivery["Delivery operations"]
  node_delivery_controller["Delivery endpoints"]
  node_delivery_logic["Assignment and delivery"]
  node_agent_logic["Agent availability"]
  node_delivery_store[("Deliveries")]
  node_agent_store[("Delivery agents")]
end

subgraph group_tracking["Live tracking"]
  node_geoloc_controller["Tracking endpoints"]
  node_geoloc_logic["Location and ETA<br/>[GeolocService.java]"]
  node_maps_logic["Route provider"]
  node_location_store[("Agent locations")]
  node_route_store[("Route cache")]
  node_eta_store[("ETA records")]
end

node_actor(("Customer, agent, admin"))
node_maps_provider["OSRM routing service"]

node_actor -->|"uses"| node_app
node_app -->|"routes to"| node_auth_pages
node_app -->|"routes to"| node_customer_pages
node_app -->|"routes to"| node_agent_page
node_app -->|"routes to"| node_admin_page
node_auth_controller -->|"delegates to"| node_auth_logic
node_user_controller -->|"delegates to"| node_user_logic
node_auth_logic -->|"reads and writes"| node_user_store
node_auth_logic -->|"uses"| node_refresh_store
node_user_logic -->|"reads and writes"| node_user_store
node_parcel_controller -->|"delegates to"| node_parcel_logic
node_parcel_logic -->|"reads and writes"| node_parcel_store
node_parcel_logic -->|"records status"| node_history_store
node_delivery_controller -->|"delegates to"| node_delivery_logic
node_delivery_logic -->|"reads and writes"| node_delivery_store
node_delivery_logic -->|"selects agent"| node_agent_logic
node_agent_logic -->|"reads and writes"| node_agent_store
node_delivery_logic -->|"updates parcel"| node_parcel_service_client
node_geoloc_controller -->|"delegates to"| node_geoloc_logic
node_geoloc_logic -->|"stores locations"| node_location_store
node_geoloc_logic -->|"caches routes"| node_route_store
node_geoloc_logic -->|"stores ETA"| node_eta_store
node_geoloc_logic -->|"requests route"| node_maps_logic
node_maps_logic -->|"requests route"| node_maps_provider

click node_app "https://github.com/atifhiba/delivery-tracker/blob/main/client/src/App.jsx"
click node_auth_pages "https://github.com/atifhiba/delivery-tracker/tree/main/client/src/pages/auth"
click node_customer_pages "https://github.com/atifhiba/delivery-tracker/tree/main/client/src/pages/customer"
click node_agent_page "https://github.com/atifhiba/delivery-tracker/blob/main/client/src/pages/agent/AgentDashboard.jsx"
click node_admin_page "https://github.com/atifhiba/delivery-tracker/blob/main/client/src/pages/admin/AdminDashboard.jsx"
click node_auth_service_client "https://github.com/atifhiba/delivery-tracker/blob/main/client/src/services/authService.js"
click node_parcel_service_client "https://github.com/atifhiba/delivery-tracker/blob/main/client/src/services/parcelService.js"
click node_delivery_service_client "https://github.com/atifhiba/delivery-tracker/blob/main/client/src/services/deliveryService.js"
click node_geoloc_service_client "https://github.com/atifhiba/delivery-tracker/blob/main/client/src/services/geolocService.js"
click node_websocket_client "https://github.com/atifhiba/delivery-tracker/blob/main/client/src/services/websocketService.js"
click node_auth_controller "https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/controller/AuthController.java"
click node_user_controller "https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/controller/UserController.java"
click node_auth_logic "https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/service/AuthService.java"
click node_user_logic "https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/service/UserService.java"
click node_user_store "https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/repository/UserRepository.java"
click node_refresh_store "https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/repository/RefreshTokenRepository.java"
click node_parcel_controller "https://github.com/atifhiba/delivery-tracker/blob/main/Server/colis-service/src/main/java/com/deliverytracker/colis/controller/ColisController.java"
click node_parcel_logic "https://github.com/atifhiba/delivery-tracker/blob/main/Server/colis-service/src/main/java/com/deliverytracker/colis/service/ColisService.java"
click node_parcel_store "https://github.com/atifhiba/delivery-tracker/blob/main/Server/colis-service/src/main/java/com/deliverytracker/colis/repository/ColisRepository.java"
click node_history_store "https://github.com/atifhiba/delivery-tracker/blob/main/Server/colis-service/src/main/java/com/deliverytracker/colis/repository/ColisStatusHistoryRepository.java"
click node_delivery_controller "https://github.com/atifhiba/delivery-tracker/blob/main/Server/livraison-service/src/main/java/com/deliverytracker/livraison/controller/LivraisonController.java"
click node_delivery_logic "https://github.com/atifhiba/delivery-tracker/blob/main/Server/livraison-service/src/main/java/com/deliverytracker/livraison/service/LivraisonService.java"
click node_agent_logic "https://github.com/atifhiba/delivery-tracker/blob/main/Server/livraison-service/src/main/java/com/deliverytracker/livraison/service/DeliveryAgentService.java"
click node_delivery_store "https://github.com/atifhiba/delivery-tracker/blob/main/Server/livraison-service/src/main/java/com/deliverytracker/livraison/repository/LivraisonRepository.java"
click node_agent_store "https://github.com/atifhiba/delivery-tracker/blob/main/Server/livraison-service/src/main/java/com/deliverytracker/livraison/repository/DeliveryAgentRepository.java"
click node_geoloc_controller "https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/controller/GeolocController.java"
click node_geoloc_logic "https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/service/GeolocService.java"
click node_maps_logic "https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/service/MapsApiService.java"
click node_location_store "https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/repository/AgentLocationRepository.java"
click node_route_store "https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/repository/RouteCacheRepository.java"
click node_eta_store "https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/repository/ETACalculationRepository.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_app,node_auth_pages,node_customer_pages,node_agent_page,node_admin_page,node_auth_service_client,node_parcel_service_client,node_delivery_service_client,node_geoloc_service_client,node_websocket_client toneBlue
class node_auth_controller,node_user_controller,node_auth_logic,node_user_logic,node_user_store,node_refresh_store toneAmber
class node_parcel_controller,node_parcel_logic,node_parcel_store,node_history_store toneMint
class node_delivery_controller,node_delivery_logic,node_agent_logic,node_delivery_store,node_agent_store toneRose
class node_geoloc_controller,node_geoloc_logic,node_maps_logic,node_location_store,node_route_store,node_eta_store,node_actor,node_maps_provider toneIndigo
```

## Components

### Web client

- [Role-based routing](https://github.com/atifhiba/delivery-tracker/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Login and register](https://github.com/atifhiba/delivery-tracker/tree/main/client/src/pages/auth): `client/src/pages/auth`
- [Customer tracking](https://github.com/atifhiba/delivery-tracker/tree/main/client/src/pages/customer): `client/src/pages/customer`
- [Agent dashboard](https://github.com/atifhiba/delivery-tracker/blob/main/client/src/pages/agent/AgentDashboard.jsx): `client/src/pages/agent/AgentDashboard.jsx`
- [Admin dashboard](https://github.com/atifhiba/delivery-tracker/blob/main/client/src/pages/admin/AdminDashboard.jsx): `client/src/pages/admin/AdminDashboard.jsx`
- [Auth API client](https://github.com/atifhiba/delivery-tracker/blob/main/client/src/services/authService.js): `client/src/services/authService.js`
- [Parcel API client](https://github.com/atifhiba/delivery-tracker/blob/main/client/src/services/parcelService.js): `client/src/services/parcelService.js`
- [Delivery API client](https://github.com/atifhiba/delivery-tracker/blob/main/client/src/services/deliveryService.js): `client/src/services/deliveryService.js`
- [Geolocation API client](https://github.com/atifhiba/delivery-tracker/blob/main/client/src/services/geolocService.js): `client/src/services/geolocService.js`
- [Live updates client](https://github.com/atifhiba/delivery-tracker/blob/main/client/src/services/websocketService.js): `client/src/services/websocketService.js`

### Identity and users

- [Authentication endpoints](https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/controller/AuthController.java): `Server/auth-service/src/main/java/com/deliverytracker/auth/controller/AuthController.java`
- [User endpoints](https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/controller/UserController.java): `Server/auth-service/src/main/java/com/deliverytracker/auth/controller/UserController.java`
- [Registration and tokens](https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/service/AuthService.java): `Server/auth-service/src/main/java/com/deliverytracker/auth/service/AuthService.java`
- [User management](https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/service/UserService.java): `Server/auth-service/src/main/java/com/deliverytracker/auth/service/UserService.java`
- [Users](https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/repository/UserRepository.java): `Server/auth-service/src/main/java/com/deliverytracker/auth/repository/UserRepository.java`
- [Refresh tokens](https://github.com/atifhiba/delivery-tracker/blob/main/Server/auth-service/src/main/java/com/deliverytracker/auth/repository/RefreshTokenRepository.java): `Server/auth-service/src/main/java/com/deliverytracker/auth/repository/RefreshTokenRepository.java`

### Parcel management

- [Parcel endpoints](https://github.com/atifhiba/delivery-tracker/blob/main/Server/colis-service/src/main/java/com/deliverytracker/colis/controller/ColisController.java): `Server/colis-service/src/main/java/com/deliverytracker/colis/controller/ColisController.java`
- [Parcel lifecycle](https://github.com/atifhiba/delivery-tracker/blob/main/Server/colis-service/src/main/java/com/deliverytracker/colis/service/ColisService.java): `Server/colis-service/src/main/java/com/deliverytracker/colis/service/ColisService.java`
- [Parcels](https://github.com/atifhiba/delivery-tracker/blob/main/Server/colis-service/src/main/java/com/deliverytracker/colis/repository/ColisRepository.java): `Server/colis-service/src/main/java/com/deliverytracker/colis/repository/ColisRepository.java`
- [Status history](https://github.com/atifhiba/delivery-tracker/blob/main/Server/colis-service/src/main/java/com/deliverytracker/colis/repository/ColisStatusHistoryRepository.java): `Server/colis-service/src/main/java/com/deliverytracker/colis/repository/ColisStatusHistoryRepository.java`

### Delivery operations

- [Delivery endpoints](https://github.com/atifhiba/delivery-tracker/blob/main/Server/livraison-service/src/main/java/com/deliverytracker/livraison/controller/LivraisonController.java): `Server/livraison-service/src/main/java/com/deliverytracker/livraison/controller/LivraisonController.java`
- [Assignment and delivery](https://github.com/atifhiba/delivery-tracker/blob/main/Server/livraison-service/src/main/java/com/deliverytracker/livraison/service/LivraisonService.java): `Server/livraison-service/src/main/java/com/deliverytracker/livraison/service/LivraisonService.java`
- [Agent availability](https://github.com/atifhiba/delivery-tracker/blob/main/Server/livraison-service/src/main/java/com/deliverytracker/livraison/service/DeliveryAgentService.java): `Server/livraison-service/src/main/java/com/deliverytracker/livraison/service/DeliveryAgentService.java`
- [Deliveries](https://github.com/atifhiba/delivery-tracker/blob/main/Server/livraison-service/src/main/java/com/deliverytracker/livraison/repository/LivraisonRepository.java): `Server/livraison-service/src/main/java/com/deliverytracker/livraison/repository/LivraisonRepository.java`
- [Delivery agents](https://github.com/atifhiba/delivery-tracker/blob/main/Server/livraison-service/src/main/java/com/deliverytracker/livraison/repository/DeliveryAgentRepository.java): `Server/livraison-service/src/main/java/com/deliverytracker/livraison/repository/DeliveryAgentRepository.java`

### Live tracking

- [Tracking endpoints](https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/controller/GeolocController.java): `Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/controller/GeolocController.java`
- [Location and ETA](https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/service/GeolocService.java): `Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/service/GeolocService.java`
- [Route provider](https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/service/MapsApiService.java): `Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/service/MapsApiService.java`
- [Agent locations](https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/repository/AgentLocationRepository.java): `Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/repository/AgentLocationRepository.java`
- [Route cache](https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/repository/RouteCacheRepository.java): `Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/repository/RouteCacheRepository.java`
- [ETA records](https://github.com/atifhiba/delivery-tracker/blob/main/Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/repository/ETACalculationRepository.java): `Server/geoloc-service/src/main/java/com/deliverytracker/geoloc/repository/ETACalculationRepository.java`

### Other components

- **Customer, agent, admin**
- **OSRM routing service**

## Connections

- Customer, agent, admin → Role-based routing: uses
- Role-based routing → Login and register: routes to
- Role-based routing → Customer tracking: routes to
- Role-based routing → Agent dashboard: routes to
- Role-based routing → Admin dashboard: routes to
- Authentication endpoints → Registration and tokens: delegates to
- User endpoints → User management: delegates to
- Registration and tokens → Users: reads and writes
- Registration and tokens → Refresh tokens: uses
- User management → Users: reads and writes
- Parcel endpoints → Parcel lifecycle: delegates to
- Parcel lifecycle → Parcels: reads and writes
- Parcel lifecycle → Status history: records status
- Delivery endpoints → Assignment and delivery: delegates to
- Assignment and delivery → Deliveries: reads and writes
- Assignment and delivery → Agent availability: selects agent
- Agent availability → Delivery agents: reads and writes
- Assignment and delivery → Parcel API client: updates parcel
- Tracking endpoints → Location and ETA: delegates to
- Location and ETA → Agent locations: stores locations
- Location and ETA → Route cache: caches routes
- Location and ETA → ETA records: stores ETA
- Location and ETA → Route provider: requests route
- Route provider → OSRM routing service: requests route