SafeRoute
Full project documentation & report. Everything in this file: what the app does, a screenshot tour of every screen (desktop and mobile, captured with Playwright from the real running app), what every option on every page is for, how to run it on any PC, the database, the free APIs, the PWA, and troubleshooting.
- Language
- JavaScript
- Stars
- 0
- Last updated
From the README
π£οΈ SafeRoute β Smart Road-Trip Planner & Ride Platform
Full project documentation & report. Everything in this file: what the app does, a screenshot tour of every screen (desktop and mobile, captured with Playwright from the real running app), what every option on every page is for, how to run it on any PC, the database, the free APIs, the PWA, and troubleshooting.
SafeRoute is a full-stack travel platform: plan road trips on real driving routes with automatic safety-risk scoring, run live GPS journeys with voice guidance, book rides in a customer/driver marketplace, explore any city in the world with real photos, get AI outfit advice from live weather, and manage it all from a powerful admin panel β wrapped in a modern dark-violet UI that installs as a PWA on your phone.
π Table of Contents
- Quick Start (run on any PC)
- Screenshot Tour β every screen explained
- Mobile Experience
- PWA β install it like a real app
- Every Page & Option Reference
- Tech Stack & Free APIs
- Database (Supabase)
- Admin Guide
- Project Structure
- Scripts
- Deploying to the Internet
- Troubleshooting
- Security Notes
π Quick Start β run on any PC
This zip includes the .env file, so the app is pre-connected to its Supabase backend. You only need Node.js.
- Install Node.js 18+ β https://nodejs.org (LTS). Verify:
node -v - Unzip this project anywhere.
- Double-click
start.bat(Windows) or run./start.sh(Mac/Linux). It installs dependencies on first run and starts the app automatically. Manual way:npm installthennpm run dev. - Open the printed URL (usually http://localhost:5173).
- Register an account β confirm the email Supabase sends β Sign in. Done.
π‘ The database schema is already applied to the connected Supabase project. If you ever connect a fresh Supabase project, run
supabase/schema.sqlin its SQL Editor first (it's idempotent β safe to re-run anytime).
πΈ Screenshot Tour β every screen explained
All screenshots below were captured with Playwright from the real running app (viewport 1440Γ900 desktop, 390Γ844 mobile).
π Login
Email + password sign-in (Supabase Auth). Forgot password? sends a real reset email. Create one free β registration with name, email, password + confirmation. New signups automatically get a profile and settings row via a database trigger.
π Dashboard β your command center
- Admin broadcast banner (the yellow strip) β announcements published from the Admin Panel appear here for every user.
- Quick-action tiles β jump to Start Journey, New Trip, Tourism, Risk Analysis.
- Live KPIs β total trips, distance, average risk, safety score, all from your saved data.
- Quick Plan β type From/To with real city autocomplete (or tap the GPS button), or use a popular-route chip β opens the New Trip planner and runs the analysis automatically.
- Recent Trips, Driver Profile, live Weather (with what-to-wear advice + link to Smart Outfit), Risk Distribution donut, 6-month Activity chart, latest-trip route drawn on the map, Tourism highlights with real photos, and Live Hazards derived from real weather.
πΊοΈ New Trip β plan with real routes
Search real cities (Open-Meteo geocoding autocomplete, GPS button for your position). Set preferences: travel style, driver profile, road type, season, difficulty, weather. Find Safe Routes fetches up to 3 real driving routes from OSRM (true distance, duration, geometry drawn on the map β selected route solid, alternatives dashed). Each route gets a risk score computed from real speed/distance plus your conditions, and a traffic label from actual average speed. Then Save to History or Start Live Journey.
π°οΈ Live Journey β GPS trip mode
Pick a start (GPS button) and destination β Start Journey opens a split screen: live map with a pulsing you-are-here marker following your real GPS, and a panel with progress bar, km remaining, live speed, ETA, elapsed time, voice announcements (start, every 25%, arrival β mutable), weather + outfit advice for your destination, and real photos of landmarks around your current position that refresh as you move. Arrival is detected automatically and the trip saves to History. No GPS on a desktop? Demo Drive simulates driving along the real route.
π Rides β customer & driver marketplace
Real two-sided ride system, like ride-hailing apps:
- Customers: pickup (GPS) + destination β Get Fare shows an up-front price from real road distance (Rs. 200 base + Rs. 45/km) with ETA β Request Ride β live status: Finding driver β Driver on the way β Completed, with cancel.
- Drivers (switch in Profile β Account Type): earnings dashboard, incoming request feed with Accept (race-safe), Complete rides to earn. The sidebar renames itself Book a Ride β Driver Hub based on your account type.
ποΈ Tourism Hub β explore any city on Earth
- Explore β search any city worldwide β real documented places within 10 km, each with a real photo, description, distance from center, Wikipedia link, open-in-maps, and Add to Itinerary.
- Scenic Routes / Hotels / Attractions β curated Pakistani picks with real photos; scenic routes have full detail pages.
- Itinerary β persistent day plan: numbered stops, durations, Optimize, Clear, total-hours summary. Saved automatically.
π Smart Outfit β ML weather classifier + your closet
A decision-tree model (ported from a Python/scikit-learn project) classifies live weather into Cold / Mild / Hot / Rainy β the animated hero banner changes its gradient and floating emojis per category. It recommends outfits from your own closet first, then generic suggestions. Manage your Closet & Wishlist: add items (auto-categorized + emoji), move wishlistβcloset, all saved per user. Check any city, or use GPS.
π Subscription β Free / Pro / Fleet
Three plans with feature lists and up-front pricing. Free keeps all core planning; Pro unlocks CSV export & advanced extras; Fleet targets teams. Choosing a plan saves to your profile (demo billing β no real charge) and feeds the Admin Revenue dashboard. Free users hitting a Pro feature (e.g. CSV export) get a friendly upgrade prompt.
π‘οΈ Admin Panel β run the whole platform
Six tabs (admin accounts only): Overview (recent signups/trips), Users (search/filter/sort/paginate, edit roleΒ·planΒ·safety score, drill-down per user, delete user data, CSV), Trips (moderate all trips), Analytics (signup & trip charts, platform risk donut, top destinations), Revenue (MRR, annual run-rate, conversion %, plan donut, subscriber list), Broadcast (publish announcements typed info/success/warning/danger β they appear on every user's dashboard + notification bell; hide or delete anytime). Eight KPI cards on top.
β οΈ Risk Analysis
Your risk mix (donut), 6-month risk trend, highest-risk trips ranked with bars, personalized recommendations from your own data β plus an interactive Pre-Trip Safety Checklist (10 practical checks, progress bar goes green on 10/10, persisted).
Also in the app (not pictured)
History β searchable/sortable trip table, edit status & notes, view any trip's route on a map, Plan Again, Start Journey, CSV export (Pro), confirm-delete. Statistics & Analytics β distance/hours/cities, efficiency score, monthly charts, top destinations. Profile β personal details, emergency contact, vehicle, Customer/Driver account type. My Account β overview + plan card. Settings β language/units, notification toggles, theme picker (5 dark themes) + compact density, change password, export my data (JSON), delete account. 404 page for wrong turns.
π± Mobile Experience
Fully responsive, captured at 390Γ844:
| Dashboard on mobile | Collapsible drawer menu | Smart Outfit on mobile |
|---|---|---|
![]() |
![]() |
![]() |
- The sidebar becomes an off-canvas drawer β hidden by default, opened with the β° button in the topbar, slides over the content with a blurred backdrop, closes on backdrop tap or navigation. On desktop the same β° collapses the sidebar to an icon rail for more workspace.
- All grids reflow (4β2β1 columns), tables scroll horizontally, the journey split-screen stacks map-over-panel, modals fit the screen, and touch targets stay comfortable.
π² PWA β install it like a real app
SafeRoute is a Progressive Web App:
- Install it: open the site in Chrome/Edge β click the Install icon in the address bar (desktop), or menu β Add to Home Screen (Android), or Share β Add to Home Screen (iOS Safari). It launches standalone β no browser chrome β with its own violet icon and splash.
- App shortcuts: long-press the installed icon β jump straight to Start Journey or Plan New Trip.
- Offline app shell: a service worker (
public/sw.js) caches the app shell, so the UI loads even offline (live data like routes/weather still needs a connection β API calls are deliberately never cached so data stays fresh). - Configured via
public/manifest.webmanifest(name, icons 192/512,display: standalone, theme color#7c5cfc); the worker registers only in production builds so it never interferes with development. - Requirements: PWA install + GPS need HTTPS or localhost. When you deploy (see below), both work automatically.
π§ Every Page & Option Reference
| Page (route) | What it's for | Key options |
|---|---|---|
Login /login |
Sign in | Email, password, forgot-password reset email, link to register |
Register /register |
Create account | Name, email, password Γ2 (min 6 chars) |
Dashboard / |
Overview & quick actions | Quick Plan (autocomplete + GPS), popular-route chips, KPIs, recent trips, weather + outfit link, charts, map, tourism tiles, hazards, admin broadcasts |
New Trip /new-trip |
Route planning | City autocomplete Γ2, GPS start, 6 preference selects, Find Safe Routes, route cards (time/km/risk/traffic), map with alternatives, Save to History, Start Live Journey |
Start Journey /journey |
Live GPS trip | GPS start, voice toggle, Start Journey, split-screen live map, progress/speed/ETA, photos around you, outfit for destination, Demo Drive, End & Save |
Rides /rides |
Ride marketplace | Customer: pickup/destination, Get Fare, Request, cancel. Driver: Accept, Complete, earnings KPIs, Refresh |
History /history |
Trip records | Search, risk filter chips, sortable columns, view-route modal (map + Plan Again + Start Journey), edit status/notes, delete, CSV export (Pro) |
Tourism /tourism |
Explore & plan visits | Explore-any-city search, place cards (photo/distance/wiki/maps), Scenic/Hotels/Attractions tabs, persistent Itinerary (add/remove/optimize/clear) |
Smart Outfit /outfit |
What to wear | Animated category hero, city search + GPS, closet matches, suggestions, Closet/Wishlist manager |
Statistics /statistics |
Your numbers | Distance/hours/cities/trips, risk breakdown bars, recent activity |
Risk Analysis /risk-analysis |
Safety insights | Risk KPIs, donut + trend charts, riskiest trips, recommendations, pre-trip checklist |
Analytics /analytics |
Behavior trends | Trips/month, efficiency score, risk trend, top destinations |
Profile /profile |
Your identity | Name/email/phone, emergency contact, vehicle + plate, Customer/Driver switch |
My Account /account |
Account overview | Usage stats, account details, plan card β Manage Plan, quick links, sign out |
Subscription /subscription |
Plans | Free/Pro/Fleet cards, upgrade/downgrade with confirm |
Settings /settings |
Preferences | Language, units, notification toggles, theme picker + density, change password, download my data, delete account, sign out |
Admin /admin |
Platform control | Overview / Users / Trips / Analytics / Revenue / Broadcast (admins only) |
| Topbar (everywhere) | Global chrome | β° sidebar toggle, page title, global trip search, π¨ theme menu, π notifications (broadcasts + trip alerts), user menu |
π§° Tech Stack & Free APIs
Frontend: React 19 Β· Vite 7 Β· React Router 7 Β· Leaflet/React-Leaflet Β· Font Awesome Β· Inter + Quicksand fonts
Backend: Supabase (PostgreSQL + Auth + Row-Level Security) β connected via .env
Quality: ESLint 9 Β· Playwright MCP (used to capture the screenshots in this doc)
Free APIs (no keys, already wired):
| Purpose | Service |
|---|---|
| City search & geocoding | Open-Meteo Geocoding |
| Live weather + forecast | Open-Meteo Forecast |
| Real driving routes | OSRM (2 public hosts + offline estimate fallback) |
| Map tiles | OpenStreetMap |
| Place photos & nearby landmarks | Wikipedia REST + geosearch APIs |
| GPS β place name | BigDataCloud reverse geocoding |
| Voice guidance | Browser SpeechSynthesis |
| Live position | Browser Geolocation API |
ποΈ Database (Supabase)
All in supabase/schema.sql β idempotent, run it whole in the SQL Editor for any new project.
| Table | Purpose |
|---|---|
profiles |
Extends auth users: name, phone, vehicle, emergency contact, role (user/admin), plan (Free/Pro/Fleet), user_type (customer/driver), safety score |
trips |
Saved trips: locations, distance, duration, risk score/level, status, notes |
user_settings |
Preferences & notification toggles |
announcements |
Admin broadcasts (title, message, type, active) |
rides |
Marketplace: customer, driver, pickup/destination, distance, fare, status |
Row-Level Security everywhere: users only see their own data; open ride requests are visible to signed-in users so drivers can accept; admins (via a recursion-safe is_admin() function) manage everything. A signup trigger auto-creates each user's profile + settings.
π‘οΈ Admin Guide
- Register normally, then in Supabase β Table Editor β profiles β set your row's
roletoadmin. - Refresh the app β Admin Panel appears in the sidebar.
- From there you can: manage every user (role, plan, safety score, delete), moderate all trips, watch platform analytics & revenue (MRR from Pro/Fleet plans), and broadcast announcements to all users' dashboards & notification bells.
ποΈ Project Structure
saferoute/
ββ start.bat / start.sh # one-click run (install + dev server)
ββ .env # Supabase connection (INCLUDED in this package)
ββ .mcp.json # Playwright MCP for browser automation in Claude Code
ββ index.html # fonts, manifest, meta
ββ public/
β ββ manifest.webmanifest # PWA manifest (icons, shortcuts, theme)
β ββ sw.js # service worker (offline app shell)
β ββ icons/ # app icons (192/512)
ββ supabase/schema.sql # full database schema + RLS (idempotent)
ββ docs/screenshots/ # all screenshots used in this README
ββ src/
ββ context/ # Auth (incl. dev demo mode), Theme, Toast providers
ββ lib/supabase.js # Supabase client
ββ components/ # Topbar, Sidebar, RouteMap, LocationInput, Charts,
β # Modal/Confirm, PlaceImage, Weather, Tourism cards...
ββ pages/ # 19 routed pages (see reference table above)
ββ styles/ # variables (design tokens) / components / animations / responsive
ββ utils/ # geo (routing+GPS), weather (+outfit advice), photos,
# outfitModel (ML port), csv, helpers, tourismAPI
π¦ Scripts
| Command | What it does |
|---|---|
start.bat / ./start.sh |
Install (first run) + start dev server |
npm run dev |
Dev server with hot reload |
npm run build |
Production build β dist/ |
npm run preview |
Serve the production build locally |
npm run lint |
ESLint |
Dev demo mode (browse the UI without signing in β used for these screenshots): open DevTools console β localStorage.setItem('sr_demo','1') β refresh. Remove with localStorage.removeItem('sr_demo'). Dev-only; production builds ignore it.
π Deploying to the Internet
- Push to GitHub β import in Vercel or Netlify.
- Build command
npm run build, outputdist. - Add env vars
VITE_SUPABASE_URL+VITE_SUPABASE_ANON_KEYin the host dashboard. - In Supabase β Authentication β URL Configuration β set your deployed URL (so email links work).
- Done β HTTPS enables PWA install + GPS automatically.
π οΈ Troubleshooting
| Problem | Fix |
|---|---|
| Blank page / "supabaseUrl is required" | .env missing β it's included in this zip; make sure it's next to package.json, then restart npm run dev |
| Can't log in after registering | Email confirmation is ON β click the link Supabase emailed you, then sign in |
| "column plan / user_type does not exist" or rides/announcements errors | Connected a fresh Supabase project β run all of supabase/schema.sql in its SQL Editor |
| Routes say "estimated" | Public OSRM was unreachable; app fell back to a straight-line estimate from real coordinates β retry later |
| GPS button does nothing | Allow location permission; GPS needs HTTPS or localhost |
| No photos for a place | It has no documented Wikipedia imagery β a placeholder is shown |
| Admin Panel missing | Set profiles.role = 'admin' for your user in Supabase, refresh |
| PWA install icon missing | Use Chrome/Edge on HTTPS/localhost; visit a couple of pages first |
| Port 5173 busy | Vite auto-picks the next port β read the terminal for the URL |
π Security Notes
- This package includes
.envon purpose so it runs instantly on your other PC. Theanonkey inside is designed to be public for browser apps β all real protection is enforced by Row-Level Security in the database. Still, don't publish this zip or the repo publicly with.envinside (.gitignorealready excludes it from git). - Never put the Supabase service_role key in this project.
- Subscription billing is a demo β plans are saved, no money moves.
Documentation generated with the app running β screenshots captured live via Playwright browser automation. Made with β€οΈ for safer roads.




