journeySafe

A full-stack travel safety platform: plan routes, discover nearby fuel stations/hospitals/restaurants/etc. along the way, read and leave reviews, report and browse community-flagged road hazards, and get an AI-powered route safety prediction before you travel.

Stack: React + Vite (frontend) · FastAPI + PostgreSQL (backend) · OpenStreetMap / Nominatim / Overpass / OSRM (maps & routing) · scikit-learn Random Forest (AI risk prediction) · Docker.

Features

• Auth — email/password signup & login, JWT sessions, forgot/reset password, protected routes, profile.
• Route planning — origin/destination autocomplete, route rendering, distance & ETA (existing frontend, backed by OSRM/Nominatim, now proxied through the backend at /api/places/*).
• Nearby places — fuel, hospitals, police, restaurants, washrooms, pharmacies, mechanics, hotels, ATMs via Overpass.
• Reviews — create/edit/delete, 1–5 star ratings, likes, average rating per place.
• Community safety reports — flag accidents, road blocks, floods, poor lighting, construction, harassment zones, animal crossings, broken roads; upvote/downvote; auto-verifies at +3 net votes, auto-rejects at -3.
• AI Route Safety Prediction — a real, trained Random Forest classifier (not a chatbot) predicts a 0–100 safety score, risk level, accident probability, a recommended travel window, and human-readable reasons and safety tips. See backend/app/ml/.
• Dashboard — trips, saved places, reviews, reports, AI prediction history, stats.
• Admin panel — manage reports (verify/reject), manage users (deactivate), platform-wide analytics.

Project structure

roadtripsafar/
  src/                 # React frontend (existing UI, preserved)
    pages/              # Home, Login, Signup, Dashboard, Admin, CommunitySafety, ...
    components/          # AIPredictionPanel, ReportForm, ReportsList, ProtectedRoute, ...
    context/AuthContext.jsx
    services/            # apiClient.js, backendService.js (new backend wrappers)
                          # + original osmService.js, placeService.js, etc.
  backend/               # FastAPI backend (new)
    app/
      routers/ services/ schemas/ models/ core/
      ml/                # train_model.py, predict.py, feature_engineering.py, ...
  sql/schema.sql          # Postgres schema (matches SQLAlchemy models)
  docs/API.md              # full endpoint reference
  docs/ARCHITECTURE.md      # system diagram + ML pipeline explanation
  docker-compose.yml         # postgres + backend + frontend

Running locally

Option A — Docker Compose (recommended, runs everything)

cd roadtripsafar
cp .env.example .env            # frontend env
cp backend/.env.example backend/.env   # backend env
docker compose up --build

• Frontend: http://localhost:5173
• Backend + docs: http://localhost:8000/docs
• Postgres: localhost:5432 (user/pass/db: journeysafe)

Option B — Run each piece manually

Backend

cd backend
python -m venv venv && source venv/bin/activate   # or venv\Scripts\activate on Windows
pip install -r requirements.txt
cp .env.example .env   # point DATABASE_URL at your local/Supabase Postgres
python -m app.ml.train_model     # trains the model, writes model.pkl (already included, but re-run any time)
uvicorn app.main:app --reload --port 8000

Frontend

npm install
cp .env.example .env   # set VITE_API_BASE_URL=http://localhost:8000
npm run dev

Using Supabase instead of local Postgres

Paste your Supabase Postgres connection string into backend/.env as DATABASE_URL (Project Settings → Database → Connection string). The FastAPI backend talks to it via plain SQLAlchemy/psycopg2 — Supabase's client SDK isn't required on the backend since it's just Postgres underneath. sql/schema.sql can also be pasted directly into the Supabase SQL editor if you'd rather provision tables by hand than rely on create_all().

AI model

cd backend
python -m app.ml.train_model

Trains a RandomForestClassifier (250 trees) on a synthetic, rule-derived labeled dataset (app/ml/sample_dataset.csv, regenerated if missing), prints a held-out classification report, and writes app/ml/model.pkl. Currently: ~85% held-out accuracy across Low/Medium/High risk classes. See docs/ARCHITECTURE.md for why the dataset is synthetic and how inference works.

What's fully wired vs. what's scaffolded

Being upfront about state, since this was built on top of an existing frontend-only project in one focused session:

Fully working, tested end-to-end (signup → review → report → AI prediction → dashboard, verified against a running server): backend auth, reviews, community reports + voting, AI prediction + history, dashboard, admin panel, the full ML training/inference pipeline.

Working but with a known gap: the "AI Route Safety Prediction" panel on the home page defaults to a placeholder distance unless you pass a real route distance in — RouteSearch doesn't yet emit its computed distance/ETA back up to Home, so wiring onRouteComputed from the actual OSRM route response into AIPredictionPanel is the one remaining integration step (currently a no-op prop). Everything downstream (the model call, storage, display) works correctly once a real number is passed.

Not yet done:

• Image upload for reviews/reports (schema and image_url fields are ready; no storage provider is wired up yet — Supabase Storage is a natural fit since @supabase/supabase-js is already a frontend dependency).
• Map visualization of community reports (they're listed, not yet plotted on the Leaflet map alongside POIs).
• Alembic migrations (schema currently managed via create_all() + sql/schema.sql for reference — appropriate for this project's scale, but a natural next step).

Environment variables

See .env.example (frontend) and backend/.env.example (backend) for the full list with comments.