smart delivery dispatch system

README.md

@@ -1,18 +1,77 @@
 # Smart Delivery Dispatch System
 
 ## Team Information
-- **Team Name**: [Team Name]
-- **Year**: [Year]
-- **All-Female Team**: [Yes/No]
+- **Team Name**: ByteForge
+- **Year**: 2nd Year
+- **All-Female Team**: No
 
-## Architecture Overview
+---
 
-#### Describe your approach here. Keep it short and clear.
+# Architecture Overview
 
-    - What is your dispatch strategy?
-    - How do you score agents for incoming orders?
-    - How do you manage SLA deadlines, priority orders, and agent capacity?
-    - What are the main steps in your pipeline?
+The Smart Delivery Dispatch System is a modular backend platform designed for intelligent real time delivery assignment and optimization. The architecture follows an event driven workflow where orders, agents, and routing information are continuously processed to support efficient dispatch decisions. Orders are maintained in a priority queue and assigned through a weighted scoring algorithm based on travel distance, SLA urgency, workload balance, order priority, agent availability, and delivery ratings.
 
+The platform uses Floyd Warshall shortest path computation to estimate travel times between locations efficiently. Pending orders remain queued until agents become available, ensuring continuous scheduling without blocking execution. State transitions are centrally managed to maintain consistency between order status and agent workload during assignment and delivery completion.
 
-**Note:** Please do not change the format or spelling of anything in this README. The fields are extracted using a script, so any changes to the structure or formatting may break the extraction process.
+The architecture is divided into specialized modules for data loading, graph routing, assignment logic, state management, simulation handling, and performance analytics. The system supports SLA aware scheduling, workload fairness, batch delivery optimization, GPS aware tracking, and real time monitoring. Final operational metrics and delivery statistics are exported in structured JSON format for reporting, evaluation, and performance analysis purposes efficiently.
+
+---
+# System Workflow
+
+1. Load orders, agents, and environment graph data from CSV files.
+2. Validate records and remove invalid entries.
+3. Build the routing graph and compute shortest paths.
+4. Insert incoming orders into the priority queue.
+5. Generate feasible delivery agent candidates.
+6. Score candidates using distance, SLA urgency, workload, availability, and ratings.
+7. Assign the best agent to the order.
+8. Update order and agent states in real time.
+9. Simulate delivery completion and SLA tracking.
+10. Calculate metrics and export final reports in JSON format.
+---
+
+# Core Modules
+
+| Module | Purpose |
+|---|---|
+| `loaders.py` | Load and validate CSV data |
+| `graph.py` | Route and shortest-path calculations |
+| `assignment.py` | Assignment scoring and dispatch |
+| `state.py` | Manage order and agent states |
+| `simulator.py` | Event-driven simulation engine |
+| `metrics.py` | SLA and performance analytics |
+
+---
+
+# Technologies Used
+
+- Python 3.10+
+- Pandas
+- Heapq
+- JSON
+
+---
+
+# Key Features
+
+- Real-time dispatching
+- SLA-aware scheduling
+- Workload balancing
+- Priority-based assignment
+- Route optimization
+- Batch delivery support
+- GPS-aware tracking
+- JSON performance reports
+
+---
+
+# Output Metrics
+
+The system tracks:
+- SLA compliance rate
+- Average delivery time
+- Agent utilization
+- Pending and failed orders
+- Workload fairness statistics
+
+Reports are exported in JSON format.