A travel guide for Pune where help is always one tap or one shake away, even offline. Pune Explorer merges PuneTourGuide (places, day plans, XP) with RoadSoS (SOS, live location, nearby hospitals), in two themes: Classic and Deccan.
🌐 Website: puneexplorer.dev · 📱 App: app.puneexplorer.dev (installs on your phone from the browser; Android app coming, join the waitlist on the website)
Technical Design · Feature Spec · Launch & Server Setup · Backend Architecture · Contribution Guidelines · Changelog
- 52 hand-picked places (forts, wadas, temples, gardens, food lanes), each with its nearest hospital, opening hours and the walk time to what's around it.
- Places and food nearby: every place lists up to six places and six food spots within 3 km, nearest first.
- Real photos, ratings and "open now" from Google Maps, with credit, and side quests (viewpoints, trails) you can tick off for +10 XP.
- Search and filters: category, distance, open now, free entry, wheelchair access, a hospital within 2 km.
- Two-day plan: add places to Day 1 or Day 2, or load a ready-made route.
- Optimise reorders the stops by real travel time and tells you how many minutes it saved.
- Trip mode (Start Day): next stop, directions (in the app or Google Maps), and an "You've arrived?" prompt only after you've stayed near the stop for 30 seconds. Works with no signal and syncs later.
- Share your live trip with your emergency contacts through a private link that stops when the day ends.
- SOS from any screen, or by shaking the phone: a 5-second countdown to cancel, then the phone dials 112 itself. It works logged out and offline.
- Your phone texts your emergency contacts a live-location link, a map pin and the nearest hospital, even without mobile data.
- Help nearby: about 2,600 hospitals, clinics, police and fire stations across Pune district from OpenStreetMap, refreshed every night, with one-tap calling (112, 108, 100, 1091).
- Medical info (blood group, allergies, medicines) is encrypted on the server and only shared in an SOS, if you allow it.
- Offline packs keep places, hospitals, police and emergency numbers on the phone for forts with one bar of signal.
- Stamps and XP for every place you visit (each place has its own XP), a travel passport, and levels from Newcomer to Puneri Legend.
- Two themes: Classic (plain emerald) and Deccan (Paithani plum, haldi gold, Marathi labels).
- Languages: the SOS screens are in English, मराठी, हिंदी and ગુજરાતી; the rest of the app is in English for now.
- Accounts: email and password or Sign in with Google; phone login when a server SMS provider is set up. You can delete your account and data from Settings.
| Part | What it is |
|---|---|
apps/web/ |
The app: React + Vite PWA (installable, works offline with a service worker), Leaflet maps. The same code builds the Android app with Capacitor |
apps/landing/ |
The website at puneexplorer.dev: static HTML/CSS, served by the API on the main domain |
services/tour-api/ |
Express + TypeScript API: places, plans, trip mode, accounts, SOS alerts, waitlist. Prisma on PostgreSQL + PostGIS, Redis for shared rate limits and caches, BullMQ for the SMS queue |
services/safety/ |
FastAPI service from RoadSoS: emergency-service lookup and live-location tracking over WebSockets |
deploy/ |
Production: Docker Compose, Caddy (HTTPS), server setup, nightly backup and restore drill |
design-reference/ |
Approved UI mockups for every screen in both themes, plus TECH_DESIGN.md and FEATURES.md (the source of truth) |
Data sources: OpenStreetMap (help points, routing, address search), Google Maps Platform (place photos, ratings, opening hours, side quests), a map-tile provider such as MapTiler.
Install these once:
- Node.js 20+ (with npm): https://nodejs.org
- Python 3.12+: https://www.python.org/downloads/ (on Windows, tick "Add python.exe to PATH")
- Docker Desktop, running: https://www.docker.com/products/docker-desktop/
npm run setupIt checks the tools, then:
- Settings: creates the
.envfiles, with random development secrets. - Database: starts this project's own PostgreSQL + PostGIS (port 5440) and Redis (port 6390) in Docker, applies the migrations and loads the 52 curated places.
- Safety service: builds its Python environment.
- Help points: imports Pune's real hospitals, clinics, police and fire stations from OpenStreetMap, which takes a few minutes.
It's safe to run again. Add --skip-help to skip the OpenStreetMap import, or --no-docker to use your own PostgreSQL and Redis from services/tour-api/.env.
npm run dev # starts the web app, Tour API and safety service togetherOpen http://localhost:5050. On a phone on the same Wi-Fi, open http://<your computer's IP>:5050. Location, the camera and installing the app need HTTPS on a phone, so test those on localhost or a deployed site.
- Stop: press
Ctrl+Cto stop the apps.npm run db:downstops the database and Redis;npm run db:upstarts them again (no setup needed). - No real texts are sent locally: login codes, SOS alerts and reset links are printed in the terminal (phone numbers masked), even if your
.envhas live SMS keys. SetSMS_DEV_SEND=trueonly to test one real text. - The landing page is plain files:
python -m http.server 5180insideapps/landing, then open http://localhost:5180.
| Problem | Fix |
|---|---|
Docker is not running |
Start Docker Desktop, wait for it to say "running", run npm run setup again |
Port 5050 / 3001 / 8010 is already in use |
Another copy is still running: close the other terminal, or restart the computer |
| Explore is empty | npm run seed -w services/tour-api |
| Help nearby is empty | npm run refresh:help (needs internet; the public servers are sometimes busy, so try again later) |
| Map has no streets | Your internet connection: map tiles are loaded from the tile provider |
| After pulling new code | npm install then npm run prisma:deploy |
| Command | What it does |
|---|---|
npm run setup |
One-time local setup (see above); safe to re-run |
npm run dev |
Web, Tour API and Safety service together |
npm run db:up / db:down |
Start / stop this project's PostgreSQL and Redis containers |
npm run dev:web / dev:api / dev:safety |
One of them |
npm run lint · npm run typecheck · npm test |
Checks for web + tour-api |
npm run build · npm run build:api |
Production builds |
npm run prisma:deploy |
Apply database migrations |
npm run refresh:help |
Import Pune's help points from OpenStreetMap and refresh each place's nearest hospital (a failed or partial download keeps the existing data) |
npm run cleanup -w services/tour-api |
Delete data past its retention period (add -- --dry-run to only count) |
npm run waitlist:export -w services/tour-api |
Print the Android waitlist emails not yet notified (launch day) |
npm run worker -w services/tour-api |
Dedicated SMS worker process (optional; the API runs one by default) |
npm run load-test |
Load test the read paths (Explore, place, help, health) |
npm run icons |
Regenerate every app icon (web, landing, Android) from apps/web/art/icon.svg |
npm run android:apk -w apps/web |
Android test APK (see docs/LAUNCH_SETUP.md step 23) |
- One server (Google Cloud, Mumbai) running Docker Compose: the API (which also serves the app and the website), the safety service, PostgreSQL + PostGIS, Redis and Caddy for HTTPS.
- Two addresses:
puneexplorer.devshows the website;app.puneexplorer.devis the app. Old app links on the main address forward to the app, and phones that installed the app from the old address keep an offline emergency page. - Automatic deploys from GitHub Actions on every merge into
researchormain. - Every night: database backup to Cloud Storage (02:00), help-point refresh (03:00), and deletion of data past its retention period (03:30).
- Monitoring: uptime checks, error reports (Sentry), and an alert when a nightly backup or cleanup fails.
The full step-by-step setup, with a real-world check for each service, is in docs/LAUNCH_SETUP.md.
- Every change goes on its own branch and in through a pull request into
research. Merging intoresearchdeploys to the live server. mainonly takesresearch, through a pull request merged with Create a merge commit. Nobody commits tomaindirectly.- Both branches deploy to the same server, so CI checks and GitHub rules keep them in step (details in docs/LAUNCH_SETUP.md, Part 7).
| Component | URL |
|---|---|
| Web app | http://localhost:5050 |
| Tour API | http://localhost:3001/api |
| Safety service | http://localhost:8010 (/health, /api/emergency-services, /ws/track/{id}); the web app reaches it at /safety |
| PostgreSQL + PostGIS | localhost:5440 (user postgres, password password, database Pune_Tour_Guide; development only) |
| Redis | localhost:6390 |
These ports avoid the usual ones (5432, 6379, 8000), so a PostgreSQL installed on your computer or other projects' containers never clash with this one.
A huge thank you to everyone who has given their time, knowledge and code to Pune Explorer.
- Sourav Suman (@LEVELING2108): project creator and maintainer. Architecture, the Tour API and safety integration, SOS and trip mode, deployment and security.
- Aman Kumar (@kmr26-aman): team member on Pune Explorer.
- Sanika Darekar (@sanikadarekar): the multi-container Docker Compose setup (PostgreSQL + PostGIS and Redis), the developer-first
CONTRIBUTING.md, backend schema and API specifications, and the root environment configuration.
Contributions are welcome: bug reports, Marathi, Hindi or Gujarati reviews of the translations, hidden gems of Pune, or code. Start with the Contribution Guidelines.
- Project license: ISC.
- Map data: © OpenStreetMap contributors (help points, routing via OSRM, address search via Nominatim).
- Place photos, ratings and opening hours: Google Maps Platform, shown with Google's attribution.
- Map tiles: from the configured tile provider (for example MapTiler), with its attribution on the map.