CairoFlow

CairoFlow is a CSE112 transportation optimization project for Greater Cairo. It demonstrates graph routing, infrastructure design, traffic optimization, emergency preemption, and public transit planning through a FastAPI backend and a React/Leaflet frontend.

The project has two data modes:

• Limited academic graph: curated CSV graph used for the PDF-required algorithms and visualizations.
• Real Cairo graph: large CSV graph from all_nodes.csv and expanded_roads.csv, currently wired for real Dijkstra and real A* route demos only.

Real-graph MST is intentionally not implemented. The MST/infrastructure feature always uses the limited academic graph.

Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• Git

Install

git clone https://github.com/Seif-Elkerdany/CairoFlow.git
cd CairoFlow

pip install -r requirements.txt

cd frontend
npm install
cd ..

Run Locally

Terminal 1:

cd backend
python -m uvicorn app:app --host 0.0.0.0 --port 8002 --reload

Terminal 2:

cd frontend
npm run dev

Open http://localhost:5173. The Vite dev proxy targets http://localhost:8002 by default. To bypass the proxy, set VITE_API_URL=http://localhost:8002.

Helper Scripts

python scripts/run_server.py
python scripts/run_all.py
python scripts/test_api.py
python scripts/test_all.py
python scripts/test_routes.py
python scripts/test_algo.py

On Windows:

scripts\run_server.bat

Docker

docker-compose up --build

Docker Compose exposes:

• Frontend: http://localhost:3010
• Backend API: http://localhost:8010
• Swagger Docs: http://localhost:8010/docs

Project Structure

backend/
  app.py                         FastAPI app entrypoint
  server.py                      Local server helper
  routes/                        API route modules
  controllers/                   Controller layer calling src algorithms
  services/                      Cache, Valhalla client, OSRM client
  models/database.py             SQLite/database manager

src/
  core/graph/                    Graph models, loader, BFS/DFS/bidirectional/random walk
  infrastructure/network_design.py
  traffic_flow/                  Dijkstra/time-dependent routing, greedy signals, analysis
  emergency_response/            A* emergency routing and preemption
  public_transit/                DP scheduling, allocation, memoized transit routing

frontend/
  src/App.jsx                    React/Leaflet/Plotly visualization UI
  vite.config.js                 Local dev proxy

data/
  neighborhoods.csv
  facilities.csv
  existing_roads.csv
  potential_roads.csv
  traffic_flow.csv
  public_transit_demand.csv
  bus_routes.csv
  metro_lines.csv
  all_nodes.csv
  expanded_roads.csv
  cairoflow.db

tests/
  unit/
  integration/
  stress/

What It Does

1. Loads graph and transit data from CSV files, with SQLite used by the backend graph/database layer.
2. Lets the frontend choose an algorithm, time slot, data source, and optional scenario settings.
3. Calls FastAPI wrappers under /api/*, which delegate to controllers and then to src/ algorithms.
4. Draws routes, MST edges, transit schedules, maintenance decisions, traffic signals, and emergency preemption results on the map.

Algorithms

Area	Algorithms
Shortest path	Dijkstra, A*, time-dependent Dijkstra, time-dependent A*, BFS, DFS, bidirectional search, random walk
Infrastructure	Kruskal-style weighted MST/forest with priority nodes, construction costs, and optional budget cap
Public transit	Dynamic programming scheduling, DP resource/maintenance allocation, memoized transit routing
Traffic flow	Greedy traffic signal optimization and greedy optimal/suboptimal route analysis
Emergency response	A* emergency routing and greedy emergency preemption

Real Cairo data mode supports only real Dijkstra and real A* variants. BFS, DFS, random walk, memoized routing, DP, greedy features, and MST remain limited-graph course demonstrations unless separately implemented for the full graph.

The OSRMService file exists as a service client, but there is no current runtime API path that exposes OSRM routing from the UI.

Bonus Features

Implemented bonus-facing features:

• ML traffic prediction: scikit-learn RandomForestRegressor trained from traffic_flow.csv, exposed at /api/traffic/prediction.
• Side-by-side visualizer: Dijkstra vs A* race mode, exposed at /api/route/compare and available in the map UI.
• Containerization: Dockerfiles and docker-compose.yml run backend + frontend together.
• Demo/repo polish: see docs/BONUS_DEMO_CHECKLIST.md and docs/LINKEDIN_POST_DRAFT.md.

Live deployment is intentionally not included yet.

Adding or Updating an Algorithm

1. Implement the algorithm in the relevant src/ subsystem.
2. Add or update the controller method under backend/controllers/.
3. Expose it through the relevant router under backend/routes/.
4. If it is frontend-facing, add a /api/* wrapper in backend/routes/frontendRoutes/frontend_routes.py and update frontend/src/App.jsx.
5. Add focused unit/integration coverage under tests/.

Tests

Install test dependencies if needed:

pip install -r tests/requirements.txt

Run the course test suite:

python run_all_tests.py

Useful direct checks:

python tests/unit/test_signal_optimizer.py
python tests/unit/test_greedy_analysis.py
python tests/integration/test_full_system.py

cd frontend
npm run build

Architecture Docs

See docs/architecture_design.md for the fuller architecture notes.