# sathwik-0111/last_mile_delivery architecture

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

- Interactive diagram: https://gitdiagram.com/sathwik-0111/last_mile_delivery
- Repository: https://github.com/sathwik-0111/last_mile_delivery

## Overview

Last Mile Delivery Tracker is a role-based delivery management application. Customers register, price and create orders, then track progress and notifications; administrators review orders and assign agents manually or automatically; agents manage availability and advance deliveries, including failed-delivery handling. The React application calls a FastAPI API backed by SQLAlchemy and a relational database. The README documents tracking, rescheduling, dashboards and charge calculation; several backend route and service implementations were not sampled, so their detailed call paths are not asserted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/App.jsx) (Role-based screens), [`backend/app/main.py`](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/services/assignment_service.py`](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/assignment_service.py) (Agent assignment), [`backend/app/services/rate_engine.py`](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/rate_engine.py) (Rate calculation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["Role-based screens<br/>[App.jsx]"]
  node_customer_order["Customer orders<br/>[CreateOrder.jsx]"]
  node_customer_tracking["Customer tracking<br/>[OrderTracking.jsx]"]
  node_customer_dashboard["Customer dashboard"]
  node_agent_dashboard["Agent operations<br/>[AgentDashboard.jsx]"]
  node_admin_dashboard["Admin overview<br/>[AdminDashboard.jsx]"]
  node_admin_assignment["Assignment screens<br/>[Assignment.jsx]"]
  node_web_api["HTTP API client<br/>[axios.js]"]
end

subgraph group_api["API and access"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_order_routes["Order endpoints<br/>[orders.py]"]
  node_agent_routes["Agent endpoints<br/>[agent.py]"]
  node_admin_routes["Admin endpoints<br/>[admin.py]"]
end

subgraph group_delivery["Delivery operations"]
  node_order_service["Order workflow<br/>[order_service.py]"]
  node_assignment["Agent assignment"]
  node_status["Status transitions<br/>[status_service.py]"]
  node_tracking["Tracking history"]
  node_notifications["Notifications"]
  node_pricing["Rate calculation<br/>[rate_engine.py]"]
  node_zones["Zone lookup<br/>[zone_service.py]"]
end

subgraph group_data["Persistence and pricing"]
  node_database[("SQL database<br/>[database.py]")]
  node_orders_model["Order records<br/>[order.py]"]
  node_agent_model["Agent records<br/>[agent.py]"]
  node_user_model["User records<br/>[user.py]"]
  node_rate_models["Rate configuration<br/>[rate_card.py]"]
  node_cod_model["COD charges<br/>[cod_charge.py]"]
  node_zone_model["Zones and areas<br/>[zone.py]"]
  node_tracking_model["Tracking records"]
  node_notification_model["Notification records<br/>[notification.py]"]
end

node_customers(("Customer"))
node_agents(("Delivery agent"))
node_admins(("Administrator"))

node_customers -->|"use"| node_app
node_agents -->|"use"| node_app
node_admins -->|"use"| node_app
node_app -->|"routes to"| node_customer_order
node_app -->|"routes to"| node_customer_tracking
node_app -->|"routes to"| node_customer_dashboard
node_app -->|"routes to"| node_agent_dashboard
node_app -->|"routes to"| node_admin_dashboard
node_app -->|"routes to"| node_admin_assignment
node_customer_order -->|"calls"| node_web_api
node_customer_dashboard -->|"calls"| node_web_api
node_agent_dashboard -->|"calls"| node_web_api
node_admin_dashboard -->|"calls"| node_web_api
node_web_api -->|"HTTP requests"| node_api_app
node_api_app -->|"registers router"| node_auth
node_api_app -->|"registers router"| node_order_routes
node_api_app -->|"registers router"| node_agent_routes
node_api_app -->|"registers router"| node_admin_routes
node_order_routes -.->|"delegates to"| node_order_service
node_order_routes -.->|"requests pricing"| node_pricing
node_admin_routes -.->|"requests assignment"| node_assignment
node_agent_routes -.->|"requests transitions"| node_status
node_order_service -->|"calculates charge"| node_pricing
node_order_service -->|"records event"| node_tracking
node_assignment -->|"records event"| node_tracking
node_assignment -->|"creates notification"| node_notifications
node_status -->|"records event"| node_tracking
node_status -->|"creates notification"| node_notifications
node_pricing -->|"looks up zones"| node_zones
node_pricing -->|"queries rates"| node_rate_models
node_pricing -->|"queries surcharge"| node_cod_model
node_zones -->|"reads areas"| node_zone_model
node_order_service -->|"uses records"| node_orders_model
node_assignment -->|"loads and updates"| node_orders_model
node_assignment -->|"checks availability"| node_agent_model
node_tracking -.->|"persists events"| node_tracking_model
node_notifications -.->|"persists notifications"| node_notification_model
node_auth -->|"queries users"| node_user_model
node_auth -->|"gets session"| node_database
node_database -->|"provides ORM base"| node_orders_model

click node_app "https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/App.jsx"
click node_customer_order "https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/customer/CreateOrder.jsx"
click node_customer_tracking "https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/customer/OrderTracking.jsx"
click node_customer_dashboard "https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/customer/CustomerDashboard.jsx"
click node_agent_dashboard "https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/agent/AgentDashboard.jsx"
click node_admin_dashboard "https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/admin/AdminDashboard.jsx"
click node_admin_assignment "https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/admin/Assignment.jsx"
click node_web_api "https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/api/axios.js"
click node_api_app "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/main.py"
click node_auth "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/routes/auth.py"
click node_order_routes "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/routes/orders.py"
click node_agent_routes "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/routes/agent.py"
click node_admin_routes "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/routes/admin.py"
click node_order_service "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/order_service.py"
click node_assignment "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/assignment_service.py"
click node_status "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/status_service.py"
click node_tracking "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/tracking_service.py"
click node_notifications "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/notification_service.py"
click node_pricing "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/rate_engine.py"
click node_zones "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/zone_service.py"
click node_database "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/database.py"
click node_orders_model "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/order.py"
click node_agent_model "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/agent.py"
click node_user_model "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/user.py"
click node_rate_models "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/rate_card.py"
click node_cod_model "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/cod_charge.py"
click node_zone_model "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/zone.py"
click node_tracking_model "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/tracking_history.py"
click node_notification_model "https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/notification.py"

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_customer_order,node_customer_tracking,node_customer_dashboard,node_agent_dashboard,node_admin_dashboard,node_admin_assignment,node_web_api toneBlue
class node_api_app,node_auth,node_order_routes,node_agent_routes,node_admin_routes toneAmber
class node_order_service,node_assignment,node_status,node_tracking,node_notifications,node_pricing,node_zones toneMint
class node_database,node_orders_model,node_agent_model,node_user_model,node_rate_models,node_cod_model,node_zone_model,node_tracking_model,node_notification_model toneRose
class node_customers,node_agents,node_admins toneIndigo
```

## Components

### Web application

- [Role-based screens](https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Customer orders](https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/customer/CreateOrder.jsx): `frontend/src/pages/customer/CreateOrder.jsx`
- [Customer tracking](https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/customer/OrderTracking.jsx): `frontend/src/pages/customer/OrderTracking.jsx`
- [Customer dashboard](https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/customer/CustomerDashboard.jsx): `frontend/src/pages/customer/CustomerDashboard.jsx`
- [Agent operations](https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/agent/AgentDashboard.jsx): `frontend/src/pages/agent/AgentDashboard.jsx`
- [Admin overview](https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/admin/AdminDashboard.jsx): `frontend/src/pages/admin/AdminDashboard.jsx`
- [Assignment screens](https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/pages/admin/Assignment.jsx): `frontend/src/pages/admin/Assignment.jsx`
- [HTTP API client](https://github.com/sathwik-0111/last_mile_delivery/blob/main/frontend/src/api/axios.js): `frontend/src/api/axios.js`

### API and access

- [FastAPI application](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/routes/auth.py): `backend/app/routes/auth.py`
- [Order endpoints](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/routes/orders.py): `backend/app/routes/orders.py`
- [Agent endpoints](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/routes/agent.py): `backend/app/routes/agent.py`
- [Admin endpoints](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/routes/admin.py): `backend/app/routes/admin.py`

### Delivery operations

- [Order workflow](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/order_service.py): `backend/app/services/order_service.py`
- [Agent assignment](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/assignment_service.py): `backend/app/services/assignment_service.py`
- [Status transitions](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/status_service.py): `backend/app/services/status_service.py`
- [Tracking history](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/tracking_service.py): `backend/app/services/tracking_service.py`
- [Notifications](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/notification_service.py): `backend/app/services/notification_service.py`
- [Rate calculation](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/rate_engine.py): `backend/app/services/rate_engine.py`
- [Zone lookup](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/services/zone_service.py): `backend/app/services/zone_service.py`

### Persistence and pricing

- [SQL database](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/database.py): `backend/app/database.py`
- [Order records](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/order.py): `backend/app/models/order.py`
- [Agent records](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/agent.py): `backend/app/models/agent.py`
- [User records](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Rate configuration](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/rate_card.py): `backend/app/models/rate_card.py`
- [COD charges](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/cod_charge.py): `backend/app/models/cod_charge.py`
- [Zones and areas](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/zone.py): `backend/app/models/zone.py`
- [Tracking records](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/tracking_history.py): `backend/app/models/tracking_history.py`
- [Notification records](https://github.com/sathwik-0111/last_mile_delivery/blob/main/backend/app/models/notification.py): `backend/app/models/notification.py`

### Other components

- **Customer**
- **Delivery agent**
- **Administrator**

## Connections

- Customer → Role-based screens: use (evidence: `README.md`)
- Delivery agent → Role-based screens: use (evidence: `README.md`)
- Administrator → Role-based screens: use (evidence: `README.md`)
- Role-based screens → Customer orders: routes to (evidence: `frontend/src/App.jsx`)
- Role-based screens → Customer tracking: routes to (evidence: `frontend/src/App.jsx`)
- Role-based screens → Customer dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Role-based screens → Agent operations: routes to (evidence: `frontend/src/App.jsx`)
- Role-based screens → Admin overview: routes to (evidence: `frontend/src/App.jsx`)
- Role-based screens → Assignment screens: routes to (evidence: `frontend/src/App.jsx`)
- Customer orders → HTTP API client: calls (evidence: `frontend/src/pages/customer/CreateOrder.jsx`)
- Customer dashboard → HTTP API client: calls (evidence: `frontend/src/pages/customer/CustomerDashboard.jsx`)
- Agent operations → HTTP API client: calls (evidence: `frontend/src/pages/agent/AgentDashboard.jsx`)
- Admin overview → HTTP API client: calls (evidence: `frontend/src/pages/admin/AdminDashboard.jsx`)
- HTTP API client → FastAPI application: HTTP requests (evidence: `README.md`)
- FastAPI application → Authentication: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Order endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Agent endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Admin endpoints: registers router (evidence: `backend/app/main.py`)
- Order endpoints → Order workflow: delegates to
- Order endpoints → Rate calculation: requests pricing
- Admin endpoints → Agent assignment: requests assignment
- Agent endpoints → Status transitions: requests transitions
- Order workflow → Rate calculation: calculates charge (evidence: `backend/app/services/order_service.py`)
- Order workflow → Tracking history: records event (evidence: `backend/app/services/order_service.py`)
- Agent assignment → Tracking history: records event (evidence: `backend/app/services/assignment_service.py`)
- Agent assignment → Notifications: creates notification (evidence: `backend/app/services/assignment_service.py`)
- Status transitions → Tracking history: records event (evidence: `backend/app/services/status_service.py`)
- Status transitions → Notifications: creates notification (evidence: `backend/app/services/status_service.py`)
- Rate calculation → Zone lookup: looks up zones (evidence: `backend/app/services/rate_engine.py`)
- Rate calculation → Rate configuration: queries rates (evidence: `backend/app/services/rate_engine.py`)
- Rate calculation → COD charges: queries surcharge (evidence: `backend/app/services/rate_engine.py`)
- Zone lookup → Zones and areas: reads areas (evidence: `backend/app/services/zone_service.py`)
- Order workflow → Order records: uses records (evidence: `backend/app/services/order_service.py`)
- Agent assignment → Order records: loads and updates (evidence: `backend/app/services/assignment_service.py`)
- Agent assignment → Agent records: checks availability (evidence: `backend/app/services/assignment_service.py`)
- Tracking history → Tracking records: persists events
- Notifications → Notification records: persists notifications
- Authentication → User records: queries users (evidence: `backend/app/routes/auth.py`)
- Authentication → SQL database: gets session (evidence: `backend/app/routes/auth.py`)
- SQL database → Order records: provides ORM base (evidence: `backend/app/models/order.py`)
