travel-agent

byRana Owais

# WanderSync — AI-Powered Travel Itinerary Planner ## Complete Project Build Prompt You are an expert full-stack developer and UI/UX designer. Build a **complete, production-quality web application** called **WanderSync** — an AI-powered travel itinerary planner. Follow every specification below exactly. The final product must look and feel like a polished, professional SaaS product — not a student project. --- ## 1. PROJECT OVERVIEW WanderSync lets users describe their travel preferences in natural language (or a structured form) and receive a personalized, day-wise travel itinerary generated by AI, enriched with real attraction, hotel, and weather data. **Example user input:** *"I want a 7-day cultural trip in Italy with budget hotels and art museums."* --- ## 2. TECH STACK - **Frontend:** HTML5, CSS3, JavaScript, React JS (functional components + hooks) - **Backend:** Python, Flask (REST API) - **Database:** SQLite (users, sessions) + JSON/MongoDB (itinerary storage) - **AI Model:** OpenAI API — GPT-4o (for itinerary generation, natural language understanding, and personalization/embeddings) - **External APIs:** - **Google Places API** — attractions, points of interest, ratings, photos - **OpenWeatherMap API** — weather forecasts for the destination and travel dates - (Optional, if credentials available) **Booking.com / RapidAPI Hotels** — hotel data - **PDF Export:** `reportlab` or `weasyprint` - **Auth:** Flask-Login / session-based authentication with hashed passwords (bcrypt) --- ## 3. DESIGN SYSTEM (STRICT — FOLLOW EXACTLY) ### Color Palette — "Professional White + Deep Teal" | Role | Color | Hex | |---|---|---| | Background (primary) | White | `#FFFFFF` | | Background (secondary/cards) | Soft off-white | `#F7F9FA` | | Primary brand color | Deep Teal / Navy | `#0D3B4A` | | Accent color (CTAs, highlights) | Warm Coral | `#FF6B4A` | | Secondary accent | Muted Gold | `#E8A33D` | | Text (primary) | Charcoal | `#1A1D29` | | Text (secondary/muted) | Slate Grey | `#6B7280` | | Borders/dividers | Light grey | `#E5E7EB` | | Success | `#2EC4B6` | | Error | `#E63946` | Design should feel **airy, clean, minimal, and premium** — generous white space, soft shadows (`box-shadow: 0 4px 20px rgba(0,0,0,0.06)`), rounded corners (`border-radius: 12–16px`). ### Typography - **Headings font:** `Sora` (Google Font) — bold, modern, geometric — used for H1–H3, hero text, logo. - **Body font:** `Inter` (Google Font) — clean, highly readable — used for paragraphs, form labels, buttons. - **Accent/quote font (optional):** `Fraunces` (serif, italic) — for taglines or testimonial-style text, to add a premium editorial touch. Import via Google Fonts: ```html <link href="https://fonts.googleapis.com/css2?family=Sora:wght@400;600;700;800&family=Inter:wght@400;500;600&family=Fraunces:ital,wght@1,400;1,500&display=swap" rel="stylesheet"> ``` ### UI Principles - Consistent 8px spacing grid - Buttons: solid coral for primary actions, outlined teal for secondary actions, subtle hover transitions (`transition: all 0.2s ease`) - Icons: use a consistent icon set (Lucide or Feather icons) - Cards for itinerary days, attractions, and hotel suggestions with subtle hover-lift effect - Fully responsive (mobile-first breakpoints: 480px, 768px, 1024px, 1280px) - Skeleton loaders / shimmer effects while AI is generating content (never a blank spinner alone) --- ## 4. PAGES / SITE MAP 1. **Home / Landing Page** — Hero section with tagline, "Plan Your Trip" CTA, "How it Works" (3–4 steps), featured destination cards. 2. **Login / Signup Page** — Clean split-screen layout (form on one side, travel imagery on the other). 3. **Trip Planner Page (Input)** — Natural language text box + structured filters (destination, dates, budget, interests as tags/chips, number of travelers). 4. **Loading / Processing State** — Animated, on-brand loading screen with rotating status messages ("Curating your perfect trip...", "Checking the weather...", "Finding hidden gems..."). 5. **Itinerary Result Page** — Day-wise tabs, each with timeline-style activity cards (time, title, description, image, map pin), weather widget, hotel suggestions sidebar. Buttons: Edit, Download PDF, Share, Save. 6. **Edit Itinerary (inline)** — Drag-to-reorder or remove activities within the result page. 7. **Dashboard / My Trips** — Grid of saved itineraries as cards (destination image, dates, "View" button). 8. *(Optional)* **Profile/Settings Page** — Basic user info management. --- ## 5. FUNCTIONAL REQUIREMENTS 1. User authentication (signup/login/logout) with secure password hashing. 2. Natural language + structured input handling for trip preferences. 3. OpenAI GPT-4o integration to generate a structured JSON itinerary (day-wise activities, timing, descriptions, local insights). 4. Google Places API integration to enrich the itinerary with real attractions, ratings, and photos. 5. OpenWeatherMap integration to show forecasted weather for the trip dates. 6. Personalization: store past user queries/itineraries and use them (via embeddings or simple heuristics) to bias future recommendations. 7. Itinerary output must be downloadable as a formatted PDF and shareable via a link. 8. Users can edit (reorder/remove activities) and re-save their itinerary. 9. All itineraries are stored per-user and retrievable from a "My Trips" dashboard. 10. Real-time progress indicator while the AI/API calls are processing. --- ## 6. NON-FUNCTIONAL REQUIREMENTS - **Performance:** Itinerary generation should complete and render within 3–5 seconds under normal load (show progressive loading if longer). - **Security:** All data transmitted over HTTPS; passwords hashed with bcrypt; API keys stored in environment variables, never hardcoded. - **Scalability:** Backend structured so it can handle concurrent requests (use async calls to external APIs where possible). - **Reliability:** Graceful error handling if OpenAI or a third-party API fails (fallback messaging, retry logic). - **Usability:** Fully responsive, accessible (proper contrast ratios, alt text, keyboard navigation). --- ## 7. DELIVERABLES - Complete, well-commented source code (Flask backend + React or HTML/CSS/JS frontend) - `.env.example` file listing required API keys (OpenAI, Google Places, OpenWeatherMap) - `README.md` with setup instructions, assumptions made, and a system architecture diagram (described in text/ASCII if needed) - Sample test data (3–4 example user prompts and their generated itineraries) - Clean project folder structure, e.g.: ``` wandersync/ ├── backend/ │ ├── app.py │ ├── routes/ │ ├── services/ (openai_service.py, places_service.py, weather_service.py, pdf_service.py) │ ├── models/ │ └── database.db ├── frontend/ │ ├── src/ │ │ ├── components/ │ │ ├── pages/ │ │ ├── styles/ │ │ └── App.jsx ├── .env.example ├── README.md └── requirements.txt ``` --- ## 8. TONE OF THE FINAL PRODUCT The end result should feel like a **premium travel-tech startup product** — think Airbnb's cleanliness meets a modern AI SaaS tool. Avoid generic Bootstrap defaults, avoid purple-gradient AI-app clichés, avoid cluttered layouts. Every screen should look intentional and polished enough to be shown in a portfolio. Begin by scaffolding the project structure, then implement the backend services, then build the frontend screens in the order listed in Section 4.