WanderWise - AI-Powered Travel Companion

WanderWise is an intelligent travel companion that transforms your static travel plans into dynamic, context-aware daily recommendations. Using AI and real-time data, it suggests the perfect activity for your current mood, location, and circumstances. It was born a upcoming Tokyo trip I am planning and having the idea for an app that helps you choose an activity from your travel plan. The frontend especially was created with a lot of help from AI.

🌟 Features

• 📱 Android Mobile App: React Native app with Android support
• 🤖 AI-Powered Recommendations: LLM-driven suggestions using OpenRouter API
• 📋 Smart Plan Parsing: Upload travel plans in JSON or text format with structured extraction
• 🎯 Activity Selection: Browse and select activities from parsed travel plans
• ⭐ Feedback System: Rate recommendations to improve future suggestions
• 📍 Location-Aware: GPS integration for location-based recommendations
• 🔄 Session Management: Track completed activities within your trip session

🏗️ Architecture

WanderWise follows a client-server architecture with clear separation of concerns:

┌─────────────────────┐    ┌─────────────────────┐
│   Mobile Frontend   │    │   Backend API       │
│   (React Native)    │◄──►│   (FastAPI)         │
│                     │    │                     │
│ • TypeScript        │    │ • Python 3.10+      │
│ • React Navigation  │    │ • Pydantic          │
│ • Axios             │    │ • Async/Await       │
└─────────────────────┘    └─────────────────────┘
                                      │
                           ┌─────────────────────┐
                           │   External APIs     │
                           │                     │
                           │ • OpenRouter (LLM)  │
                           │ • Google Maps API   │
                           │ • Weather API       │
                           └─────────────────────┘

📁 Project Structure

travelplanner/
├── wanderwise_frontend/          # React Native mobile application
│   ├── src/
│   │   ├── components/           # Reusable UI components
│   │   ├── screens/              # App screens (Welcome, Activity Selection, etc.)
│   │   ├── navigation/           # Navigation configuration
│   │   └── types/                # TypeScript type definitions
│   ├── android/                  # Android-specific code (functional)
│   ├── ios/                      # iOS-specific code (structure exists)
│   └── package.json
│
├── wanderwise_backend/           # FastAPI backend service
│   ├── app/
│   │   ├── api/v1/               # API endpoints and schemas
│   │   ├── core/                 # Configuration and constants
│   │   ├── services/             # Business logic layer
│   │   ├── integrations/         # External service integrations
│   │   │   ├── llm/              # LLM client and prompts
│   │   │   └── tools/            # Tool calling implementations
│   │   └── utils/                # Utility functions
│   ├── data/                     # Feedback data storage (JSONL format)
│   └── requirements.txt

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm/yarn
• Python 3.10+
• React Native CLI and Android development environment
• OpenRouter API Key for LLM access
• Google Maps API Key for location services
• Weather API Key (optional, for weather integration)

Frontend Setup

cd wanderwise_frontend

# Install dependencies
npm install

# Start Metro bundler
npm start

# Run on Android device/emulator
npm run android

# Note: iOS structure exists but not fully functional for development

Backend Setup

cd wanderwise_backend

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Start development server
uvicorn app.main:app --reload

The backend will be available at http://localhost:8000 with interactive API docs at /docs.

🔧 Configuration

Environment Variables

Create a .env file in the backend directory:

# LLM Configuration
OPENROUTER_API_KEY=your_openrouter_key_here

# Maps API
GOOGLE_MAPS_API_KEY=your_google_maps_key_here

# Weather API (optional)
WEATHER_API_KEY=your_weather_api_key_here

# Application Settings
DEBUG=true
LOG_LEVEL=info
FEEDBACK_FILE_PATH=data/feedback.jsonl

Mobile App Configuration

Update wanderwise_frontend/src/constants/config.ts:

export const API_BASE_URL = __DEV__ 
  ? 'http://localhost:8000' 
  : 'https://your-production-api.com';

🎯 How It Works

1. 📤 Upload Travel Plan: Users upload their travel itinerary in Markdown or text format
2. 🎲 Preference Selection: Bracket-style tournament to select current mood and activity type
3. 🤖 AI Processing: LLM analyzes plan, preferences, weather, and location data
4. 💡 Smart Recommendation: Receive a personalized activity suggestion with justification
5. ⭐ Feedback Loop: Rate recommendations to improve future suggestions
6. ✅ Activity Tracking: Mark activities as completed to avoid repetition

🛠️ Development

Frontend Development

# Run tests
npm test

# Lint code
npm run lint

# Type checking
npx tsc --noEmit

# Build for production
npm run build

Backend Development

# Run tests
pytest

# Format code
black app/
isort app/

# Type checking
mypy app/

# Start with auto-reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

📱 Key Features Deep Dive

Intelligent Recommendation Engine

• Context-Aware: Considers weather, location, time, and user mood
• Plan Integration: Parses and understands your existing travel plans
• Adaptive Learning: Improves suggestions based on your feedback

Bracket Selection System

• Engaging UX: Tournament-style preference selection
• Randomized Options: Prevents selection bias
• Quick Decision Making: Reduces choice paralysis

Real-Time Data Integration

• Weather API: Current conditions affect activity suggestions
• GPS Location: Distance and travel time calculations
• Crowd Data: Future integration for popularity-based filtering

🔄 API Endpoints

Core Endpoints

• POST /api/v1/parse-plan - Parse travel plan and extract structured activities
• POST /api/v1/validate-plan - Validate JSON travel plan structure
• POST /api/v1/recommendations - Get activity recommendation
• POST /api/v1/feedback - Submit recommendation feedback

Request/Response Examples

// Recommendation Request
{
  "plan_content": "Day 1: Visit Tokyo Tower, Senso-ji Temple...",
  "completed_activities": ["tokyo-tower"],
  "user_mood": "adventurous",
  "activity_type": "cultural",
  "location": {"lat": 35.6762, "lng": 139.6503}
}

// Recommendation Response
{
  "activity_id": "senso-ji-temple",
  "activity_name": "Senso-ji Temple Visit",
  "justification": "Perfect for cultural exploration in good weather",
  "estimated_travel": "15 minutes by train"
}

🚀 Deployment

Backend Deployment (Fly.io)

# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Deploy
fly deploy

Mobile App Deployment

# Android
cd android && ./gradlew assemble Release

# iOS (requires Xcode)
cd ios && xcodebuild -workspace WanderWise.xcworkspace -scheme WanderWise archive

📄 License

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