🐜 SwarmLogistics

Pheromone-guided delivery route optimization for the Philippines

A full-stack logistics platform powered by Ant Colony Optimization (ACO) with real road routing via self-hosted OSRM, service zone management, live vehicle tracking, and statistical route health analytics.

---

Features

Route Optimization

• Ant Colony Optimization (ACO) — solves the Vehicle Routing Problem with pheromone-guided path selection
• Real road routing via OSRM — self-hosted OpenStreetMap routing engine using Philippines map data, with automatic haversine fallback
• Time window constraints — per-stop earliest/latest delivery deadlines enforced as hard constraints
• Route duration caps — per-vehicle maximum route duration, with automatic stop shedding when exceeded
• Capacity-aware bin packing — priority-based stop assignment across vehicles
• Multi-vehicle dispatch — auto-distributes stops across the full fleet in one click

Map & Visualization

• Dark map dashboard powered by Leaflet.js + CartoDB
• Road-following animated polylines (dashed trail) when OSRM is active
• Numbered stop markers in optimized order
• Depot diamonds, live vehicle markers, saved location pins
• Routing engine badge (OSRM vs haversine indicator)

Service Zones

• Draw polygon zones on the map with Leaflet.draw
• New stops auto-tagged to zones via ray-casting point-in-polygon detection
• Zone-level efficiency analytics

Live Vehicle Tracking

• WebSocket endpoint for real-time driver position updates
• HTTP ping fallback for simpler clients
• Fleet overview map panel showing all on-route vehicles

Route Health Analytics (Data Science Layer)

• Compares estimated vs actual route durations across completed routes
• Anomaly detection — z-score method (n ≥ 10 routes) with IQR/Tukey fence fallback for smaller samples
• Zone efficiency table — avg deviation, on-time rate, avg distance per zone
• Vehicle efficiency table — total km, anomaly count, avg deviation per vehicle
• Overall KPIs — completed routes, avg deviation %, on-time rate

Other

• Saved locations — quick-pick named places (warehouses, hubs, depots)
• Map-click depot picker for vehicles
• JWT authentication with first-user-becomes-admin
• CSV and PDF export (ReportLab)
• Route history with actual vs estimated deviation

---

Tech Stack

Layer	Technology
Backend	FastAPI 0.136+
Database	PostgreSQL + SQLAlchemy 2.0 + Alembic
Auth	JWT (python-jose) + passlib/bcrypt
Optimizer	Custom ACO engine (app/optimizer/aco.py)
Road routing	OSRM (self-hosted via Docker, Philippines OSM data)
Analytics	Custom z-score/IQR anomaly detection (app/analytics/route_health.py)
Frontend	Vanilla JS + Leaflet.js + Leaflet.draw (single-file SPA)
Export	ReportLab (PDF), csv module

---

Setup

Prerequisites

• Python 3.9+
• PostgreSQL
• Docker Desktop (for OSRM real road routing — optional but recommended)

1. Clone and install

git clone https://github.com/PoorProgrammer0A33/SwarmLogistics.git
cd SwarmLogistics
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Linux/Mac
pip install -r requirements.txt

2. Configure environment

Copy .env.example to .env and fill in your values:

DATABASE_URL=postgresql://user:password@localhost:5432/swarmlogistics
SECRET_KEY=your-secret-key-here
```S

### 3. Run migrations

```bash
alembic upgrade head

4. Start the app

uvicorn app.main:app --reload

Open http://127.0.0.1:8000 in your browser.

---

OSRM Setup (Real Road Routing)

OSRM provides real driving distances and road-following route geometry using Philippines OpenStreetMap data. Without it, the app falls back to straight-line haversine estimation automatically.

1. Download the Philippines map extract

Download philippines-latest.osm.pbf from Geofabrik:

https://download.geofabrik.de/asia/philippines.html

Place it in osrm-data/philippines-latest.osm.pbf.

2. Pre-process the map (one time, ~5–15 minutes)

docker compose -f docker-compose.osrm.yml run --rm osrm-extract
docker compose -f docker-compose.osrm.yml run --rm osrm-partition
docker compose -f docker-compose.osrm.yml run --rm osrm-customize

3. Start the routing server

docker compose -f docker-compose.osrm.yml up -d osrm-routed

OSRM runs on http://localhost:5000. The app detects it automatically — the badge in the top right of the dashboard switches from "📐 Haversine" to "🛣 OSRM (real roads)".

See docs/OSRM_SETUP.md for the full walkthrough.

---

Project Structure

app/
├── api/routes/          # FastAPI routers
│   ├── auth.py
│   ├── vehicles.py
│   ├── stops.py
│   ├── routes.py        # optimize + dispatch endpoints
│   ├── zones.py         # service zone CRUD
│   ├── locations.py     # saved locations CRUD
│   ├── tracking.py      # WebSocket + HTTP live tracking
│   ├── analytics.py     # route health + OSRM status
│   └── export.py
├── analytics/
│   └── route_health.py  # z-score/IQR anomaly detection
├── models/
│   └── logistics.py     # SQLAlchemy ORM models
├── optimizer/
│   └── aco.py           # Ant Colony Optimization engine
├── schemas/
│   └── logistics.py     # Pydantic request/response schemas
├── services/
│   ├── logistics.py     # business logic layer
│   ├── osrm.py          # OSRM client with haversine fallback
│   └── auth.py
├── static/
│   └── index.html       # full frontend (Leaflet.js SPA)
└── main.py
alembic/versions/        # database migrations
docs/
└── OSRM_SETUP.md
docker-compose.osrm.yml

---

API Documentation

Interactive API docs available at http://127.0.0.1:8000/docs when the server is running.

Key endpoints:

• POST /api/routes/optimize — single vehicle ACO optimization
• POST /api/routes/dispatch — multi-vehicle auto dispatch
• GET /api/analytics/route-health — anomaly detection + efficiency stats
• GET /api/analytics/osrm-status — check if OSRM is active
• WS /api/tracking/ws/{vehicle_id} — WebSocket live position updates
• GET /api/tracking/live — all on-route vehicles with last known position

---

License

MIT