Repository: mirva777/tavelcocoon
Primary language: Python

# Body Comfort Travel Planner

A web-based travel planner that helps you prepare for optimal comfort across different climates and cultures. Built for LauzHack 2025.

## Features

- **Climate Analysis**: Day-by-day weather forecasting with climate shock detection
- **Smart Packing Optimizer**: Algorithmic packing recommendations based on temperature, activities, and weight constraints
- **Comfort Analysis**: Skin, UV, and environmental comfort assessment with personalized kit recommendations
- **Food & Culture Guidance**: Dietary accommodation finder with cultural tips for each destination
- **Plane Outfit Suggestions**: Layering recommendations for temperature transitions

## Tech Stack

**Backend:**
- FastAPI (Python)
- Pydantic for data validation
- **Open-Meteo API** (FREE, no API key needed!) for real weather data
- **Google Gemini** for LLM-powered cultural guidance (with fallback to mock data)

**Frontend:**
- React + TypeScript
- Vite
- Tailwind CSS
- Custom hooks for API integration

## Quick Start

### Backend Setup

1. Navigate to backend directory:
```bash
cd backend
```

2. Create virtual environment and install dependencies:
```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```

3. (Optional) Set up Gemini API key for LLM features:
```bash
cp .env.example .env
# Edit .env and add your Gemini API key:
# GEMINI_API_KEY=your_key_here
# Get free API key at: https://makersuite.google.com/app/apikey
```

**Note: Weather data works automatically (no API key needed)!** The app uses Open-Meteo's free API for real weather forecasts. LLM features use mock data if no Gemini key is provided.

4. Run the backend:
```bash
python main.py
```

Backend will be available at `http://localhost:8000`

### Frontend Setup

1. Navigate to frontend directory:
```bash
cd frontend
```

2. Install dependencies:
```bash
npm install
```

3. Run the development server:
```bash
npm run dev
```

Frontend will be available at `http://localhost:5173`

## Usage

1. **Step 1 - Trip Basics**: Enter your origin, destinations, dates, and luggage limit
2. **Step 2 - You & Plans**: Select activities, dietary preferences, and optionally upload a selfie
3. **Step 3 - Results**: View your personalized travel plan with packing list, comfort kit, and food guidance

## Architecture Highlights

### Packing Optimizer Algorithm
- Uses greedy set-cover approach with knapsack-style weight management
- Scores items based on coverage, priority, and weight
- Automatically suggests rental/purchase for heavy items
- Real algorithmic logic, not LLM hallucination

### Climate Engine
- Fetches weather forecasts for each destination
- Calculates climate shocks between locations
- Classifies days into temperature buckets
- Supports both real API calls and mock data

### LLM Integration
- Structured prompts for food & culture guidance (JSON output)
- Narrative generation for summaries and recommendations
- Fallback to mock data for demo without API keys

## Demo Data

The app includes smart mock data generators, so you can demo without API keys:
- Weather data based on latitude and season
- Realistic food guidance templates
- Pre-configured clothing catalog

## Project Structure

```
├── backend/
│   ├── models/          # Pydantic data models
│   ├── engines/         # Core algorithms (packing, climate, comfort, food)
│   ├── services/        # External API integrations
│   ├── data/            # Clothing catalog
│   └── main.py          # FastAPI application
├── frontend/
│   ├── src/
│   │   ├── components/  # Shared components, wizard, result cards
│   │   ├── pages/       # Step 1, 2, 3 pages
│   │   ├── hooks/       # API integration hook
│   │   └── types/       # TypeScript types
│   └── package.json
└── README.md
```

## API Endpoints

- `GET /health` - Health check
- `POST /api/analyze-trip` - Main analysis endpoint

### Example Request
```json
{
  "origin": {"city": "Tashkent"},
  "segments": [
    {
      "city": "Istanbul",
      "arrival_date": "2025-11-25",
      "departure_date": "2025-11-27"
    }
  ],
  "luggage_limit_kg": 20,
  "activities": ["city_exploration", "hiking"],
  "diet": {
    "pattern": "omnivore",
    "needs_halal": true,
    "openness": "medium"
  }
}
```

## Development Notes

- Backend runs on port 8000
- Frontend runs on port 5173 (Vite default)
- CORS is configured for local development
- All dates should be in ISO format (YYYY-MM-DD)

## Future Enhancements

- Real-time weather integration
- User accounts and trip history
- Mobile app
- More clothing items and activities
- Integration with booking platforms
- Expanded cultural guidance database

## License

MIT

## Team

Built with ❤️ for LauzHack 2025
# tavelcocoon
# tavelcocoon
# tavelcocoon
# tavelcocoon