🌍 Wanderlust - Travel Experience Sharing Platform

A full-stack web application to explore, share, and review travel destinations. Built with MongoDB, Express.js, Node.js, and EJS.

🔗 Live Preview

📊 Project Insights

🌟 Stars	🍴 Forks	🐛 Issues	🔔 Open PRs	🔕 Closed PRs	🛠️ Languages	👥 Contributors

🚀 Features

Core Features

• 🌐 Browse Destinations - Explore amazing travel locations with detailed information
• 📝 Add New Places - Share your favorite destinations with photos and descriptions
• ⭐ Reviews & Ratings - Rate and review places you've visited (1-5 stars)
• 🗺️ Interactive Maps - Powered by Mapbox with precise location markers
• 📸 Photo Uploads - Upload multiple images via Cloudinary integration
• 📱 Responsive Design - Fully optimized for desktop, tablet, and mobile devices
• 🔐 User Authentication - Secure login/signup system with Passport.js
• ✏️ Full CRUD Operations - Create, Read, Update, Delete listings and reviews

Advanced Features

• 🤖 AI-Powered Packing List Generator - Smart travel packing lists with weather integration
• 🌤️ Real-Time Weather Integration - Live weather data for all destinations
• 📅 Holiday Calendar & Travel Planner - Smart vacation planning with global holidays
• 🎯 Best Time to Visit Recommendations - Country-specific travel season suggestions
• 🔍 Smart Search & Filters - Find destinations by location, price, or features
• 💾 Data Caching - Optimized performance with 10-minute weather caching
• 🌍 Multi-Country Support - Global destinations with localized information
• 📊 Admin Analytics Dashboard - Comprehensive platform metrics and insights

🌟 GSSoC 2025 Participation

🚀 This project is now an official part of GirlScript Summer of Code – GSSoC'25! We're thrilled to welcome contributors from all over India and beyond to collaborate, build, and grow WanderLust together!

👩‍💻 GSSoC is one of India's largest 3-month-long open-source programs that encourages developers of all levels to contribute to real-world projects while learning, collaborating, and growing together.

🛠 Tech Stack

• Backend: Node.js, Express.js
• Frontend: EJS, HTML, CSS, Bootstrap
• Database: MongoDB (Mongoose ODM)
• Cloud Storage: Cloudinary (for image uploads)
• Maps: Mapbox API
• Authentication: Passport.js
• Analytics: Chart.js (for admin dashboard)
• Data Visualization: Interactive charts and real-time metrics

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v14 or higher)
• MongoDB (local or Atlas account)
• Git

🔧 Environment Variables Setup

This project requires several external services. Follow this guide to set up all required environment variables:

Step 1: Create your .env file

cp .env.example .env

☁️ Cloudinary Setup (Image Upload Service)

1. Create Account: Go to Cloudinary and sign up for free
2. Get Your Credentials: After login, go to your Dashboard and find the Account Details section
3. Add to .env:

   CLOUD_NAME=your_cloudinary_name
   CLOUD_API_KEY=your_cloudinary_api_key
   CLOUD_API_SECRET=your_cloudinary_api_secret

🗺️ Mapbox Setup (Maps Service)

1. Create Account: Go to Mapbox and sign up for free
2. Get Access Token: Go to Account → Access Tokens and copy your Default Public Token
3. Add to .env:

   MAP_TOKEN=your_mapbox_access_token

🗄️ MongoDB Atlas Setup (Database Service)

1. Create Account: Go to MongoDB Atlas and sign up for free
2. Create Cluster: Choose the Free Tier (M0 Sandbox)
3. Create Database User: Set up username and password with read/write permissions
4. Allow Network Access: Add your IP address or allow access from anywhere for development
5. Get Connection String: Replace username and password in the connection string
6. Add to .env:

   ATLAS_DB_URL=mongodb+srv://username:password@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority&appName=Cluster0

🌤️ OpenWeatherMap API Setup (Weather Service)

1. Create Account: Go to OpenWeatherMap and sign up for free
2. Get API Key: After login, go to API Keys section and copy your key
3. Add to .env:

   WEATHER_API_KEY=your_openweathermap_api_key

🤖 OpenAI API Setup (Required - for AI Packing List Generator)

1. Create Account: Go to OpenAI and sign up for an account
2. Get API Key: After login, go to API Keys section and create a new secret key
3. Add to .env:

   OPENAI_API_KEY=your_openai_api_key

📅 Holiday API Setup (Optional - for Holiday Calendar)

1. Create Account: Go to Calendarific for holiday data
2. Get API Key: Copy your API key from dashboard
3. Add to .env:

   HOLIDAY_API_KEY=your_holiday_api_key

🔐 Session Secret Setup

Generate a strong random string for session encryption:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Add to .env:

SECRET=your_super_secret_session_key_here_make_it_long_and_random

Final .env Example:

CLOUD_NAME=your_cloudinary_name
CLOUD_API_KEY=your_cloudinary_api_key
CLOUD_API_SECRET=your_cloudinary_api_secret

MAP_TOKEN=pk.eyJ1IjoieW91cl91c2VybmFtZSIsImEiOiJjbTls...

ATLAS_DB_URL=mongodb+srv://username:password@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority&appName=Cluster0

WEATHER_API_KEY=your_openweathermap_api_key
OPENAI_API_KEY=your_openai_api_key
HOLIDAY_API_KEY=your_holiday_api_key

SECRET=your_super_secret_session_key_here_make_it_long_and_random

⚠️ Security Notes:

• Never commit your .env file to GitHub
• Keep all credentials private and secure
• The .env file is already in .gitignore

📂 Installation & Setup

1. Fork & Clone

1. Fork this repository by clicking the "Fork" button at the top right
2. Clone your fork to your local machine:

   git clone https://github.com/YOUR-USERNAME/WanderLust.git
   cd WanderLust

2. Install Dependencies

npm install

3. Set Up Environment Variables

Follow the environment variables setup guide above.

4. Run the Project

# Development mode (with nodemon)
npm run dev

# Or standard mode
npm start

🎉 Your app should now be running at: http://localhost:8080

📁 Project Structure

WanderLust/
├── models/          # Database models (Listing, Review, User)
├── routes/          # Express routes (including admin analytics)
├── views/           # EJS templates
│   └── admin/       # Admin dashboard views
├── public/          # Static files (CSS, JS, images)
│   ├── CSS/         # Stylesheets (including admin-dashboard.css)
│   └── JS/          # JavaScript files (including admin-dashboard.js)
├── middleware/      # Custom middleware functions
├── utils/           # Utility functions
├── init/            # Database initialization
├── docs/            # Documentation (including ADMIN_DASHBOARD.md)
├── .env.example     # Environment variables template
├── createAdmin.js   # Admin user creation script
└── app.js           # Main application file

📝 Available Scripts

npm start                    # Start the application
npm run dev                  # Start with nodemon (auto-restart)
npm test                     # Run tests (if available)
node createAdmin.js          # Create admin user for dashboard access
node test-admin-dashboard.js # Test admin dashboard functionality

🤝 Contributing

We welcome contributions! Follow these steps:

🏷️ Understanding Our Auto-Labeling System

Before contributing, please read our Labeling Guide to understand how Issues and Pull Requests are automatically assigned complexity levels:

• 🌱 Level1: Beginner-friendly (documentation, typos, simple styling)
• 🔧 Level2: Intermediate (features, UI/UX, components)
• ⚡ Level3: Advanced (bugs, backend, security, performance)

1. Create a Feature Branch

git checkout -b feature/your-feature-name

2. Make Your Changes

• Write clean, well-commented code
• Follow existing code style and conventions
• Test your changes locally
• Consider the complexity level when creating Issues/PRs

3. Commit Your Changes

git add .
git commit -m "Add: brief description of your changes"

4. Push to Your Fork

git push origin feature/your-feature-name

5. Create a Pull Request

1. Go to your fork on GitHub
2. Click "New Pull Request"
3. Provide a clear title and description
4. Submit the PR 🎉

🌤️ Weather Integration Details

Real-Time Weather Display

Location: Appears on listing detail pages above the map section

What You'll See:

• 🌡️ Current Temperature - Live temperature in Celsius (e.g., "24°C")
• 🌤️ Weather Condition - Clear description with emoji (☀️ sunny, 🌧️ rainy, ☁️ cloudy)
• 💨 Wind Speed - Current wind speed in m/s
• 💧 Humidity - Percentage humidity level
• 🌡️ Feels Like - Perceived temperature

Weather Icon System

• ☀️ Clear/Sunny - Perfect weather conditions
• ☁️ Cloudy - Overcast conditions
• 🌧️ Rain/Drizzle - Wet weather conditions
• ⛈️ Thunderstorms - Severe weather alerts
• ❄️ Snow - Winter conditions
• 🌫️ Mist/Fog - Low visibility conditions
• 🌤️ Mixed - Partly cloudy/default conditions

Best Time to Visit Recommendations

Country-Specific Travel Seasons:

• 🇮🇹 Italy: Spring (Apr-Jun) & Fall (Sep-Oct)
• 🇯🇵 Japan: Spring (Mar-May) & Fall (Sep-Nov) - Cherry blossoms & autumn colors
• 🇹🇭 Thailand: Cool Season (Nov-Feb) - Dry and comfortable
• 🇮🇳 India: Winter (Oct-Mar) - Pleasant temperatures
• 🇺🇸 USA: Varies by region - Spring & Fall generally ideal
• 🌍 Default: Spring & Fall seasons typically perfect for travel

Performance Optimization

• ⚡ 10-minute caching - Weather data cached for faster loading
• 🔄 Auto-refresh - Data updates every 10 minutes automatically
• 📱 Fallback system - Backup weather data when API is unavailable

🤖 AI-Powered Packing List Generator

Smart Travel Planning

Access: Available in navbar dropdown under "Travel Tools" 🛠️

Packing List Features

• 🤖 AI-Generated Lists - Personalized packing suggestions using OpenAI GPT
• 🌤️ Weather Integration - Weather-appropriate clothing and gear recommendations
• 📋 Categorized Organization - Items grouped by essentials, clothing, toiletries, etc.
• 💾 Save to Trip Plans - Store packing lists with your travel itineraries
• 📱 Interactive Checklists - Check off items as you pack
• 📄 PDF Export - Download printable packing lists

How It Works

1. Fill Out Form - Provide trip details (destination, duration, activities, weather)
2. AI Analysis - System analyzes weather data and generates personalized recommendations
3. Review & Customize - Review the AI-generated list and make adjustments
4. Save & Export - Save to your trip plans or export as PDF
5. Track Progress - Use interactive checklist during packing

AI Intelligence Features

• 🎯 Activity-Based Suggestions - Hiking, beach, city exploration, business travel
• 🌡️ Weather-Adaptive - Appropriate clothing for temperature and conditions
• 📅 Duration-Aware - Different recommendations for short vs long trips
• 🌍 Destination-Specific - Local customs, voltage requirements, cultural considerations
• 👥 Group Travel - Family, solo, couple, or group recommendations

Packing Categories

• 🧳 Essentials - Documents, money, phone, chargers
• 👕 Clothing - Weather-appropriate outfits and accessories
• 🧴 Toiletries - Personal care and hygiene items
• 💊 Health & Safety - Medications, first aid, travel insurance
• 🛠️ Electronics - Gadgets, adapters, portable chargers
• 🎒 Activity Gear - Sports equipment, special clothing
• 📚 Miscellaneous - Books, entertainment, snacks

Smart Recommendations

• ⚡ Power Adapters - Country-specific plug types and voltage
• 💉 Health Requirements - Vaccination recommendations
• 🌦️ Weather Contingency - Rain gear, layers for temperature changes
• 🎯 Activity-Specific - Hiking boots for trails, formal wear for business
• 📏 Weight Optimization - Suggestions for carry-on vs checked luggage

Integration Benefits

• 🔗 Trip Planner Sync - Connects with holiday calendar and vacation slots
• 🌤️ Weather Data - Real-time weather integration for accurate recommendations
• 💾 Persistent Storage - Save multiple lists for different trips
• 📊 Progress Tracking - Visual indicators for packing completion
• 📱 Mobile Friendly - Responsive design for on-the-go planning

📅 Holiday Calendar & Travel Planner

Smart Vacation Planning

Access: Available in navbar dropdown under "Travel Tools" 🛠️

Holiday Calendar Features

• 🗓️ Global Holidays - Public holidays for 200+ countries
• 🎉 Long Weekends - Automatic detection of extended holiday periods
• 🏖️ Vacation Slots - Mark ideal travel periods
• 📊 Peak vs Off-Peak - Travel season indicators
• 🎯 Destination Suggestions - Popular places during specific holidays

How It Works

1. Select Country - Choose your home country or destination
2. View Calendar - See upcoming holidays and long weekends
3. Plan Trips - Mark holidays as "ideal vacation slots"
4. Get Suggestions - Discover trending destinations for those dates
5. Smart Recommendations - Combine with weather data for perfect timing

Holiday Types Covered

• 🏛️ National Holidays - Official government holidays
• 🎊 Religious Festivals - Major religious celebrations
• 🎭 Cultural Events - Local festivals and celebrations
• 🏖️ School Holidays - Academic calendar breaks
• 💼 Bank Holidays - Financial sector closures

Travel Planning Benefits

• 💰 Cost Optimization - Avoid peak pricing periods
• 🎯 Perfect Timing - Travel during ideal weather + holidays
• 📈 Trend Analysis - See popular destinations by season
• 🗓️ Calendar Integration - Export to Google Calendar/iCal
• 🌍 Multi-Country Planning - Compare holidays across regions

📊 Admin Analytics Dashboard

Quick Setup

1. Create Admin User

   node createAdmin.js

2. Access Dashboard

   URL: http://localhost:8080/admin/dashboard
   Username: admin
   Password: admin123
   

3. Test Dashboard

   node test-admin-dashboard.js

Dashboard Features

• 📈 User Growth Trends - Track new user registrations over time
• ⭐ Top Rated Destinations - Highest rated locations by users
• 🥇 Most Active Contributors - Users with most listings and reviews
• 💬 Review Activity - Review submission patterns and trends
• 🎯 Popular Categories - Distribution of listing categories
• 💰 Platform Value Trends - Pricing trends and listing values

Key Metrics

• Real-time user statistics
• Monthly growth indicators
• Platform engagement metrics
• Revenue and pricing analytics
• Interactive Chart.js visualizations
• Auto-refresh every 5 minutes

For detailed documentation, see Admin Dashboard Guide

🐛 Common Issues & Solutions

Issue	Solution
"Cannot find module" errors	Run npm install
Database connection failed	Check your ATLAS_DB_URL in .env
Images not uploading	Verify Cloudinary credentials in .env
Maps not loading	Check your MAP_TOKEN in .env
Weather not displaying	Verify WEATHER_API_KEY in .env
Holiday calendar empty	Check HOLIDAY_API_KEY in .env
Admin dashboard not loading	Run node createAdmin.js first
Charts not displaying	Check browser console for JS errors
Slow loading times	Weather caching active - wait 10 mins

📜 Code of Conduct

Please refer to the Code of Conduct for details on contributing guidelines and community standards.

🤝 Contributors

🧑‍💻 Project Admin

Kaushik Mandal

⭐ Stargazers

🍴 Forkers

💡 Support & Feedback

If you find this project helpful:

• Please give it a star ⭐ on GitHub
• Share it with others
• Consider contributing
• Feel free to open issues for feedback or suggestions

📞 Contact

If you have any questions or suggestions:

• Open an issue on GitHub
• Contact the maintainers

📄 License

This project is licensed under the MIT License - see the License file for details.

---

Show some by starring this repository!

Happy coding and safe travels! 🧳✈️