GovRide AI — Backend Setup & Execution Guide

This document is the complete guide for getting the GovRide AI backend running from scratch. It covers prerequisites, database setup, data seeding, AI model training, and running the API server.

---

What Is In This Package

backend/
├── main.py                          ← FastAPI entry point (all routers registered)
├── requirements.txt                 ← All Python dependencies
├── .env                             ← Database connection string (edit this)
├── docker-compose.yml               ← PostgreSQL + pgAdmin (optional, for local dev)
├── alembic/                         ← Database migration scripts
│   └── versions/d5f3e6738497_initial_schema.py
├── seed_data/                       ← 15 CSV files with real Lesotho fleet data
│   ├── ministries.csv               (19 ministries)
│   ├── users.csv                    (10,000 users across all roles)
│   ├── vehicles.csv                 (10,000 government vehicles)
│   ├── drivers.csv                  (10,000 drivers)
│   ├── trip_requests.csv            (10,000 trips)
│   ├── billing_records.csv          (10,000 billing records)
│   ├── maintenance_tasks.csv        (10,000 maintenance tasks)
│   ├── maintenance_records.csv      (10,000 completed maintenance records)
│   ├── trip_tokens.csv              (10,000 auth tokens)
│   ├── notification_logs.csv        (10,000 notifications)
│   ├── report_records.csv           (10,000 trip reports)
│   ├── terrain_responses.csv        (10,000 GIS terrain records)
│   ├── ministry_budgets.csv         (38 budget periods)
│   ├── lesotho_event_calendar.csv   (31 public holidays)
│   └── dataset_manifest.csv
├── database/
│   ├── schema.py                    ← All SQLAlchemy ORM models
│   ├── crud.py                      ← CRUD helpers
│   ├── db_loaders.py                ← DB ↔ Pydantic bridge for fleet engines
│   └── seed_csv_data.py             ← CSV → PostgreSQL seeder (auto-runs on startup)
└── services/
    ├── ai_demand_forecasting/       ← AI Intelligence Module
    │   ├── model_registry/          ← Pre-trained model artifacts (included)
    │   │   ├── demand_model.pkl     ← Gradient Boosting demand forecaster
    │   │   ├── demand_scaler.pkl
    │   │   ├── demand_meta.json     ← Training metadata (MAE, version, features)
    │   │   ├── anomaly_model.pkl    ← Isolation Forest fuel anomaly detector
    │   │   ├── anomaly_scaler.pkl
    │   │   └── anomaly_meta.json
    │   ├── engines/
    │   │   ├── feature_engineering.py    ← Feature transforms for both models
    │   │   ├── demand_forecasting_engine.py
    │   │   ├── fuel_anomaly_engine.py
    │   │   └── training_pipeline.py      ← CLI retraining script
    │   ├── api/ai_api.py            ← All AI REST endpoints
    │   └── models.py                ← Pydantic request/response schemas
    ├── fleet_management/            ← Trip lifecycle, allocation, tokens
    ├── billing_service/             ← CPK billing engine
    ├── maintenance_service/         ← Maintenance scheduling
    ├── gis_service/                 ← Terrain analysis
    ├── notification_service/        ← SMS/email/in-app alerts
    ├── report_service/              ← PDF report generation
    ├── hr_service/                  ← HR employee management
    └── auth/                        ← JWT authentication

---

Prerequisites

Requirement	Version	Notes
Python	3.10+	3.11 recommended
PostgreSQL	14+	Must be running before starting the app
pip	Latest	pip install --upgrade pip

No Docker required. The app connects to any standard PostgreSQL instance. docker-compose.yml is provided as a convenience for local dev only.

---

Step 1 — Set Up PostgreSQL

Option A: Use the included Docker Compose (easiest for local dev)

# From the backend/ directory:
docker compose up -d postgres

This starts PostgreSQL on port 5432 with:

• Database: govride_db
• User: govride_user
• Password: govride_pass

Step 2 — Configure the Environment

Edit .env in the backend/ directory:

DATABASE_URL=postgresql://govride_user:govride_pass@localhost:5432/govride_db

If your PostgreSQL is on a different host, port, or has different credentials, update this string accordingly. The format is:

postgresql://USERNAME:PASSWORD@HOST:PORT/DATABASE_NAME

---

Step 3 — Install Python Dependencies

cd backend/
pip install -r requirements.txt

This installs FastAPI, SQLAlchemy, Alembic, scikit-learn, pandas, and all other required packages. First install takes 2–3 minutes.

---

Step 4 — Run Database Migrations

cd backend/
alembic upgrade head

This creates all 16 tables in PostgreSQL: ministries, ministry_budgets, users, vehicles, drivers, trips, trip_tokens, billing_records, maintenance_tasks, maintenance_records, standby_providers, notification_logs, ai_predictions, audit_log, elevation_tokens, trip_reports

If you see Target database is not up to date, run alembic upgrade head again.

---

Step 5 — Start the Application

cd backend/
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

What happens on first startup:

1. Verifies all tables exist (creates any missing ones)
2. Detects the database is empty
3. Automatically seeds all 15 CSV files into PostgreSQL — this takes 60–120 seconds on first run
4. Loads the pre-trained AI models from model_registry/ into memory
5. API is ready to accept requests

You will see log output like:

INFO  [GovRide DB] Tables verified / created.
INFO  [GovRide Seed] Starting CSV seed...
INFO    Loaded ministries.csv: 19 rows
INFO    Loaded users.csv: 10000 rows
INFO    ✓ ministries: 19
INFO    ✓ ministry_budgets: 38
INFO    ✓ drivers: 10000
INFO    ✓ vehicles: 10000
INFO    ✓ users: 10000
INFO    ✓ trips: 10000
...
INFO  [GovRide Seed] ✅ All CSV data committed successfully.
INFO  [DemandModel] Loaded v20260422_1747  MAE=8.35 trips/day
INFO  [AnomalyModel] Loaded v20260422_1747  contamination=0.0200
INFO  Application startup complete.

Subsequent startups skip seeding (data is already in the DB) and load in under 5 seconds.

---

Step 6 — Verify Everything Is Working

Open your browser or use curl:

# API documentation (interactive Swagger UI)
http://localhost:8000/docs

# Health check
curl http://localhost:8000/health