Pothole detection and road repair optimization system for the city of Cotonou.

• Citizen reporting (/) — upload a road photo, run YOLOv8 pothole detection, click the map for GPS, save a report
• Mayor dashboard (/dashboard) — reports ranked by danger score, zone heatmap, optimized repair route
• Danger score per report and zone: number of potholes × average bounding-box area (px²)
• Repair route — greedy priority algorithm (high danger ÷ distance to next stop)

RoadAI/
├── backend/
│   ├── main.py           # FastAPI app, HF model load, /api/detect
│   ├── detection.py      # Box parsing, red annotations, danger score
│   ├── database.py       # SQLite reports
│   ├── optimization.py   # Greedy repair route
│   ├── zones.py          # Cotonou 5×5 zone grid
│   ├── uploads/          # Original images (gitignored)
│   ├── annotated/        # Annotated images (gitignored)
│   └── models/           # Optional local weights (see models/README.md)
├── frontend/
│   └── src/
│       ├── pages/        # ReportPage, DashboardPage
│       ├── components/   # CotonouMap, Layout
│       └── api.ts        # API client (port 8001)
├── start-backend.ps1
├── start-frontend.ps1
└── README.md

At startup, main.py downloads and loads the pothole model from Hugging Face:

from huggingface_hub import hf_hub_download
from ultralytics import YOLO

model_path = hf_hub_download(
    repo_id="keremberke/yolov8n-pothole-segmentation",
    filename="best.pt",
)
model = YOLO(model_path)

Weights are cached by huggingface_hub after the first download. Internet access is required on first backend start.

Configured in main.py:

Flow:

1. Image saved under backend/uploads/
2. model.predict(...) runs in main.py
3. print(results[0].boxes) logs detections to the server console (debug)
4. detection.py builds the JSON response and draws red bounding boxes to backend/annotated/

• Python 3.10+ (3.13 supported)
• Node.js 18+ and npm
• Network access for Hugging Face model download (first run)

See backend/requirements.txt: FastAPI, Ultralytics, OpenCV, huggingface_hub, aiosqlite, etc.

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn main:app --reload --host 127.0.0.1 --port 8001

From project root:

.\start-backend.ps1

API docs: http://127.0.0.1:8001/docs

cd frontend
npm install
npm run dev

From project root:

.\start-frontend.ps1

App: http://localhost:5173

The frontend uses http://127.0.0.1:8001 (frontend/src/api.ts). Vite proxies /api to the same port during development (frontend/vite.config.ts).

• UI language: French
• Colors: red #c41e3a and white
• Map: OpenStreetMap tiles centered on Cotonou

MIT — See LICENSE

Hackathon project — educational and demonstration use.