RoutePulse — Campus Transport Planning Demo 🚌

RoutePulse is an open-source starter project for planning campus transport under realistic constraints. It goes beyond displaying bus locations: the demo forecasts arrival windows from simulated GPS traces, flags capacity pressure, checks a backup-bus recommendation, and compares the proposed plan with a documented baseline.

Scope: This repository is a reproducible student MVP using synthetic data and a transparent ETA heuristic. It is not a live fleet system, and it does not yet use a trained machine-learning model.

What works in this demo

• Three repeatable scenarios: normal morning, a demand spike, and an unavailable spare bus.
• ETA windows: a simple trend heuristic uses the latest two simulated GPS observations and reports a predicted arrival plus/minus two minutes.
• Capacity handling: the planner does not allocate more passengers to a vehicle than its capacity; unmet demand remains visible.
• Constraint checks: spare vehicle availability, vehicle capacity, busy-time conflicts, route duration, and the fixed evaluation window.
• Baseline comparison: passengers served, unmet demand, vehicles used, and ETA mean absolute error (MAE).
• Usable browser dashboard: choose a scenario and inspect arrival estimates, issues, proposed changes, passed/failed checks, and results.
• Automated tests: verify the main scenario, demand spike, bus unavailability, ETA evaluation, and schedule conflicts.

Quick start

Python 3.10+ is required. From this repository folder:

Windows PowerShell

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
uvicorn app.main:app --reload

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
uvicorn app.main:app --reload

Open http://127.0.0.1:8000 for the dashboard or http://127.0.0.1:8000/docs for interactive API docs. Run tests with:

pytest -q

How the system works

flowchart TD
    A[Simulated routes, stops, timetables, vehicles, GPS and demand] --> B[Validate scenario data]
    B --> C[Estimate ETA windows from observed GPS delay trend]
    B --> D[Read passenger demand and available vehicle capacities]
    C --> E[Detect delays and capacity shortfall]
    D --> E
    E --> F[Generate a backup-vehicle candidate]
    F --> G{Capacity, availability, travel time and timetable all pass?}
    G -- No --> H[Report failed checks and remaining unmet demand]
    G -- Yes --> I[Return a feasible adjustment and trade-off]
    H --> J[Compare baseline and proposed plan]
    I --> J
    J --> K[Show ETA, alerts, constraints and measurable outcomes]

Loading

Four team workstreams

Workstream	Main files	Responsibility
1. Frontend	app/static/	Dashboard, scenario selector, ETA display, warnings, recommendation, metric comparison.
2. Backend	app/main.py	FastAPI routes, scenario loading, validation errors and API responses.
3. AI & optimization	app/services/planner.py	ETA heuristic, capacity analysis, candidate generation, feasibility checks and trade-off explanation.
4. Data, simulation & testing	data/scenarios/, tests/	Synthetic GPS traces, passenger counts, disruption cases, evaluation ground truth, and reproducibility tests.

See docs/ARCHITECTURE.md for interfaces and extension ideas.

API endpoints

• GET /health — basic service health.
• GET /api/scenarios — list available scenarios.
• GET /api/summary?scenario=campus_morning — full analysis for a scenario.
• GET /docs — interactive API documentation.

Valid scenario IDs: campus_morning, demand_spike, spare_unavailable.

What the starter demonstrates—and what it does not

The normal scenario has 68 passengers, a 50-seat assigned bus, and a 40-seat spare bus. The baseline serves at most 50 passengers. If the backup bus is available and every hard constraint passes, RoutePulse assigns up to 18 additional passengers to it. The demand-spike scenario has 95 passengers and only 90 combined seats, so the demo must show 5 passengers of unmet demand rather than claiming it solved everything. If the spare is unavailable or conflicts with a busy interval, the engine must not recommend that assignment.

The ETA method is deliberately explainable and small enough for contributors to replace. The ground-truth arrival times are included in scenario files only for offline evaluation; they represent simulated actual outcomes, not information available to a live passenger. All baseline/optimized comparisons use the same scenario and evaluation window.

Contributing

Contributions are welcome! Start with CONTRIBUTING.md. Public repository visitors usually contribute through a fork and pull request. Direct branch pushes require repository write permission; public visibility alone does not grant it.

Good first issues: add a new disruption scenario, improve input validation, make the ETA method configurable, add a proper demand forecasting model, add accessibility-aware routing, or improve dashboard accessibility.

Project status

Demo / hackathon starter — not production ready. Before any real deployment, add rigorous schema validation, live-data security, authentication and authorization, operational monitoring, privacy protections, realistic vehicle-and-driver constraints, and independent safety review.

License

MIT. See LICENSE.