Wanderlust AI 🌿

A friendly, light-themed travel planner that builds weather-smart AI itineraries for any city worldwide — with live destination photos as you search.

---

✨ Features

• Light, travel-friendly UI — green & white theme with soft cards and rounded corners
• Destination photos — real location images from Wikipedia as you search
• Global city search — 200,000+ cities with autocomplete
• Popular getaways — one-click picks with photo cards
• Live weather + forecast — plans adapted to current and upcoming conditions
• Gemini AI itineraries — friendly day-by-day markdown plans
• Trip history — search, revisit, and delete past adventures

---

📁 Project structure

smart_weather_check/
├── client/                 React + Vite + Tailwind frontend
│   ├── src/
│   │   ├── components/     UI (search, history, itinerary panel)
│   │   ├── hooks/          Location image loading
│   │   └── utils/          Wikipedia image fetcher
│   └── .env                VITE_API_URL
├── server/                 Express API
│   ├── index.js            Routes + MongoDB + OpenWeather + Gemini
│   └── .env                API keys & database URI
└── README.md

---

🛠 Prerequisites

Before you start, make sure you have:

Requirement	Link
Node.js 18+	nodejs.org
MongoDB Atlas (free)	mongodb.com/cloud/atlas
OpenWeatherMap API key (free)	openweathermap.org/register
Google Gemini API key (free)	aistudio.google.com/apikey

---

🚀 Step-by-step setup

Step 1 — Clone & open the project

git clone <your-repo-url>
cd smart_weather_check

Or, if you already have the folder:

cd smart_weather_check

Step 2 — Install backend dependencies

cd server
npm install

Step 3 — Create MongoDB Atlas database (free)

1. Go to MongoDB Atlas and sign up / log in.
2. Create a free cluster (e.g. M0, AWS, region closest to you).
3. Database Access → Add New Database User
   • Choose a username and password (save these — you need them for MONGO_URI).
4. Network Access → Add IP Address
   • Click Add Current IP Address, or use Allow Access from Anywhere (0.0.0.0/0) for local development only.
5. Go to Database → click Connect on your cluster.
6. Choose Drivers (not Compass, Shell, SQL, or Power BI).
7. Select Node.js and copy the connection string.

It looks like:

mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/?appName=Cluster0

Important:

• Replace <username> and <password> with your database user credentials.
• If your password contains special characters, URL-encode them (e.g. @ → %40, # → %23).
• Add the database name smart-travel before the ?:

mongodb+srv://YOUR_USER:YOUR_PASSWORD@cluster0.xxxxx.mongodb.net/smart-travel?retryWrites=true&w=majority

Tip: If you see querySrv ECONNREFUSED, your network may block SRV DNS. In Atlas → Connect → Drivers, use the standard connection string (mongodb://... with shard hostnames) instead of mongodb+srv://. See server/.env.example.

You do not need to:

• Change cluster tier on the Edit Cluster page (Free is fine).
• Add cluster Tags (optional, for organization only).
• Use Atlas SQL or Power BI connection strings.

Step 4 — Get OpenWeatherMap API key (free)

1. Sign up at OpenWeatherMap.
2. Verify your email.
3. Open API keys and copy your default key.
4. New keys can take up to 2 hours to activate. A 401 error right after signup is normal — wait and retry.

This app uses the free tier: Geocoding, Current Weather, and 5-day Forecast.

Step 5 — Get Google Gemini API key (free)

1. Go to Google AI Studio.
2. Sign in with your Google account.
3. Click Create API key and copy it.

Gemini keys are usually active immediately.

Step 6 — Configure backend environment

Copy the example file:

# macOS / Linux / Git Bash
cp .env.example .env

# Windows PowerShell
Copy-Item .env.example .env

Edit server/.env with your real values:

PORT=5000
CLIENT_URL=http://localhost:5173
MONGO_URI=mongodb+srv://YOUR_USER:YOUR_PASSWORD@cluster0.xxxxx.mongodb.net/smart-travel?retryWrites=true&w=majority
WEATHER_API_KEY=your_openweathermap_key_here
GEMINI_API_KEY=your_google_gemini_key_here

Example (password example@123 must be encoded as example%40123):

MONGO_URI=mongodb+srv://myuser:example%40123@cluster0.abc123.mongodb.net/smart-travel?retryWrites=true&w=majority

Never commit .env — it is gitignored.

Step 7 — Install frontend dependencies

cd ../client
npm install

Step 8 — Configure frontend environment

Copy the example file (optional — defaults work for local dev):

cp .env.example .env

Default client/.env:

VITE_API_URL=http://localhost:5000

Change VITE_API_URL when deploying to point at your production backend URL.

Step 9 — Start the backend

Open Terminal 1:

cd server
npm run dev

Or, without auto-reload:

npm start

You should see:

MongoDB Connected
Server running on port 5000

Verify the backend (optional):

curl http://localhost:5000/api/health

Expected response:

{ "ok": true, "envConfigured": true, "databaseConnected": true }

Step 10 — Start the frontend

Open Terminal 2:

cd client
npm run dev

Vite prints the local URL, usually http://localhost:5173. If that port is busy, it may use 5174 or 5175 — open the exact URL shown in the terminal.

Step 11 — Open the app in your browser

1. Open the URL Vite printed (e.g. http://localhost:5173).
2. Confirm the status banner does not show missing API keys or backend offline.

Step 12 — Try it out

1. Type a city (e.g. Paris, FR or Kodaikanal, IN) — a destination photo appears as you search.
2. Pick from Popular getaways or select an autocomplete suggestion.
3. Set trip length with the slider (1–14 days).
4. Click Generate My Itinerary.
5. View your weather-smart plan with photos, forecast, and day-by-day details.
6. Check Trip history — saved plans are stored in MongoDB.

---

⚡ Quick run (after first-time setup)

If dependencies and .env files are already configured:

Terminal 1 — Backend:

cd server
npm run dev

Terminal 2 — Frontend:

cd client
npm run dev

Then open the URL Vite prints in your browser.

---

🔌 API endpoints

Method	Route	Description
GET	/api/health	Server & database status
GET	/api/locations/search?q=	Global city autocomplete
POST	/api/generate-itinerary	Generate & save itinerary
GET	/api/history?search=	List past trips (optional filter)
DELETE	/api/history/:id	Delete a saved trip

---

🩺 Troubleshooting

Problem	What to do
Amber API keys needed banner	Fill in all three keys in server/.env, restart backend
MongoDB connection failed / querySrv ECONNREFUSED	Use the standard URI from Atlas (mongodb://... not mongodb+srv://) — see server/.env.example
MongoDB connection failed (other)	Check username/password; URL-encode special chars in password (@ → %40); whitelist your IP in Atlas Network Access
Used wrong Atlas connection type	Choose Drivers → Node.js, not Atlas SQL / Power BI / Compass
Weather 401 Unauthorized	Verify WEATHER_API_KEY at API keys; wait up to 2 hours if key is new
Location not found	Add country code: Paris, FR or pick from suggestions
Backend offline banner	Run cd server && npm run dev — confirm MongoDB Connected in terminal
Port 5000 already in use	Stop the old Node process, then restart the server
Frontend on 5174 / 5175 instead of 5173	Normal when 5173 is busy — open the URL Vite prints
No destination photo	Wikipedia may not have an image; a green fallback is shown
Generate fails / Network Error	Ensure backend is running and CLIENT_URL in server/.env matches your frontend origin

---

🌐 Deploy (optional)

1. Push to GitHub (.env files are gitignored — never commit secrets)
2. Deploy server/ to Render or Railway with all env vars
3. Deploy client/ to Vercel with VITE_API_URL=<your-backend-url>
4. Update MongoDB Atlas network access for your host

---

📜 License

MIT — built for learning and adventure. Happy travels! ✈️