Skip to content

README.md

Latest commit

 

History

History
192 lines (129 loc) · 7.45 KB

README.md

File metadata and controls

192 lines (129 loc) · 7.45 KB
Raw

🏰 Pune Explorer

A modern, high-performance tour guide web application for Pune, featuring interactive maps, dynamic itinerary planning, OpenStreetMap auto-discovery, weather-adaptive routing, and gamification.

Backend Architecture · Contribution Guidelines · Changelog

Version React Node.js TypeScript PostgreSQL Redis Docker Vite PWA Ready

✨ Core Features

  • 📱 Immediate Dashboard Access: Direct entry to the main dashboard without mandatory authentication barriers.
  • ⚡ Route Sequence Optimization (OSRM Trip API): Solves the Traveling Salesperson Problem (TSP) on the fly for active itinerary stops, ordering them by the shortest physical distance.
  • ⛶ Interactive Map UI/UX: Full-screen Leaflet integration with customizable pin badges (①, ②, ③), category filtering, and turn-by-turn routing polylines.
  • 📋 Turn-by-Turn Routing & Directions: Step-by-step navigation instructions from OSRM displayed directly inside the app, localized in 15+ languages.
  • 🏆 Persistent Gamification & Punekar Levels: Tracks XP (+50 XP per stop, +10 XP per saved spot) and ranks users with titles such as Navin Punekar, Shiledar, and Puneri Legend.
  • 🌲 OpenStreetMap (OSRM & Overpass) Sourcing: Queries live tourist destinations (Heritage, Nature, Temple, Food, Wellness) with strict negative filtering against non-tourist locations.
  • 📱 Progressive Web App (PWA) Support: Service worker caching, offline capability, standalone mobile app layout, and brand icons.
  • 🌐 Multilingual Localization: Full translation support for English, Marathi (मराठी), Hindi, Gujarati, Tamil, Telugu, and 9+ regional languages.

🛠️ Local Setup Guide

Follow these steps to run Pune Explorer locally on your development machine.

📋 Prerequisites

Ensure you have the following installed on your system:

  • Node.js (v18.0 or higher) & npm
  • Git
  • Docker & Docker Compose (Recommended for instant Postgres + Redis setup), OR:
    • PostgreSQL database (v14+ with PostGIS extension enabled)
    • Redis server (optional, used for Overpass API rate-limit caching)

1️⃣ Clone the Repository

git clone https://github.com/LEVELING2108/PuneTourGuide.git
cd PuneTourGuide

2️⃣ Environment Variables Setup

Frontend (.env)

Create a .env file in the root project directory (or copy .env.example):

cp .env.example .env
# API URL pointing to the local Node/Express server
VITE_API_BASE_URL=http://localhost:3001/api

Backend (backend/.env)

Create a .env file inside the backend/ directory (or copy backend/.env.example):

cp backend/.env.example backend/.env
# Database connection string (PostgreSQL with PostGIS)
DATABASE_URL="postgresql://postgres:password@localhost:5432/Pune_Tour_Guide?schema=public"

# Server Port
PORT=3001

# Secret key for JWT signing
JWT_SECRET="pune_explorer_super_secret_key"

# Redis connection URL (optional for caching)
REDIS_URL="redis://127.0.0.1:6379"

3️⃣ Start Database Services (Optional via Docker)

If you use Docker, start PostgreSQL (with PostGIS) and Redis with one command:

docker compose up -d

4️⃣ Backend Setup & Database Migration

Navigate to the backend directory, install dependencies, run Prisma migrations, and seed initial data:

# Navigate to backend
cd backend

# Install node dependencies
npm install

# Generate Prisma Client & Apply Database Migrations
npx prisma generate
npx prisma migrate deploy

# Seed database with initial tourist places, events, and default itineraries
npx ts-node src/seed.ts

# Start backend server in development mode (with nodemon)
npm run dev

The backend server will run on http://localhost:3001.

5️⃣ Frontend Setup & Execution

Open a new terminal window in the project root directory and start the Vite dev server:

# From project root directory
npm install

# Start Vite dev server
npm run dev

The frontend application will open on http://localhost:5173.

6️⃣ Quick Verification & Scripts

You can also run all-in-one scripts from the root directory:

Command Description
npm run dev Starts Vite frontend dev server
npm run build Builds production frontend bundle (dist/)
npm run build:backend Compiles backend TypeScript to JavaScript (backend/dist/)
npm run build:all Installs, generates Prisma client, and builds both backend & frontend
npm run prisma:generate Generates Prisma client inside backend/
npm run prisma:deploy Deploys Prisma migrations to database

🌐 API Ports & Services Summary

Component URL / Address Description
Frontend Web App http://localhost:5173 React 18 + Vite local UI
Backend Express API http://localhost:3001/api REST API Endpoints
PostgreSQL Database localhost:5432 Main database (pune_tour_guide)
Redis Cache localhost:6379 Key-value store (prefix places:v5:)

🤝 Contributors & Special Thanks

A huge thank you to all contributors who have dedicated their time, knowledge, and code to making Pune Explorer an open-source, tourist-first platform!

🌟 Project Contributors

  • Sourav Suman (@LEVELING2108) — Project creator & maintainer: core architecture, live OpenStreetMap viewport discovery engine, dual node/way spatial centroid processing, strict negative keyword filtering, itinerary TSP optimization, and security hardening.
  • Sanika Darekar (@sanikadarekar) — Key contributor: Multi-container Docker Compose setup (PostgreSQL + PostGIS & Redis), developer-first CONTRIBUTING.md guidelines, synchronized backend schemas & API endpoint specifications, and root environment configurations.

We warmly welcome all contributions! Whether reporting bugs, refining Marathi/Hindi translations, adding hidden gems of Pune, or writing code, check out our Contribution Guidelines and Changelog.

📜 License & Sourcing

  • Map & Geocoding Data: OpenStreetMap via Overpass API & OSRM.
  • Project License: Open-source under ISC License.