# Project export: TRAVLR AI This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: OpenAI Build Week - Tagline: A web app for safe and hassle free travel. It helps to find the safest route while suggesting nearby restaurants, tourist attractions, budget hotels and transport options, all in one place. - Devpost: https://devpost.com/software/travlr-ai - GitHub: https://github.com/SHREYOTHECODINGEXPERTO/TRAVLR-AI.git - Demo: https://travlr-ai.vercel.app/ - Video: https://player.vimeo.com/video/1211489121?byline=0&portrait=0&title=0#t= - Team: 1 GitHub contributor(s) — Shreya Kar (8 commits) ## Devpost submission (written by the team) ### Inspiration When people travel, they switch between many apps : Google Maps and places for directions and exploring places. Zomato for food order. District for places to visit. MakeMyTrip for hotels and transport booking . This is such a waste of time. ### What it does Our web app does everything important but in an easy way . Suppose a user enters: "I want to go from Digha to Newtown." The app shows ✅ Safest route ✅ Traffic ✅ Accident-prone areas ✅ Road construction ✅ Flooded roads (if available) ✅ Nearby restaurants ✅ Nearby cafes ✅ Tourist attractions ✅ Budget hotels ✅ Bus/train/flight options Everything under one specific platform . ### How we built it Frontend: A modern web interface built using React and Vite for rapid rendering and hot module reloading. It uses Tailwind CSS and modular UI components for a premium, responsive design, along with interactive maps to visualize locations and hotel recommendations. Backend: A lightweight Node.js and Express server that handles client requests, communicates with external APIs, and manages a local JSON database to save, update, and retrieve generated travel itineraries. AI Engine: Powered by the OpenAI API (using models like gpt-4o-mini). The AI dynamically processes user preferences (such as destination, budget, travel companion type, and trip duration) to structure detailed day-by-day itineraries, estimate costs, and power an interactive, context-aware chatbot assistant to answer traveler queries. ### Challenges we ran into JSON Parsing Failures: Sometimes the AI returned Markdown or conversational text alongside the itinerary data. Solved by using strict prompts to enforce a clean JSON schema. Serverless File Storage: Serverless hosting (like Vercel) has a read-only filesystem, preventing local database writes. Solved by routing file database writes to the environment's temporary directory (/tmp). AI Latency: Generating a detailed multi-day plan takes a few seconds, which can hurt UX. Solved by implementing visual loading states and skeleton screens. Chatbot Context Limits: Feeding the entire itinerary details into the chat companion for every message was inefficient. Solved by compressing the trip details into a compact system context. Coordinate Inaccuracy: The AI would occasionally generate inaccurate latitude/longitude values for map pins. Solved by validating coordinates before rendering the map. ### Accomplishments we're proud of Zero-to-Hero Travel Planning: Users can generate a complete, fully customized multi-day vacation plan under 10 seconds. Context-Aware Chat Companion: The AI assistant doesn't just chat. It understands the generated itinerary, allowing users to ask context-specific questions about their current trip. Seamless Map & Itinerary Sync: Successfully mapping out travel activities visually, creating a seamless dual-view experience. Polished User Experience: Achieving a premium, highly responsive UI/UX, smooth loading skeletons, and interactive states. Serverless-Ready Deployment: Building a production-ready application that works out-of-the-box on serverless environments, making it cheap to host and highly scalable. ### What we learned Prompt Engineering & Output Control: We learned how to write system instructions that constrain LLMs (such as OpenAI) to return structured JSON rather than raw text, thereby avoiding runtime crashes. Designing for API Latency: We discovered how critical perceived performance is; using placeholder skeletons and engaging loaders drastically improves the user experience while waiting for AI generation. Managing Ephemeral Environments: We gained a solid understanding of how serverless platforms (like Vercel) manage storage and routing, forcing us to write adaptive data-saving logic using /tmp. Effective Context Management: We learned how to pass large datasets into LLM chat models efficiently without hitting rate limits or driving up API token costs. Integrating AI with Interactive Maps: We learned how to bridge structural text coordinates returned by an AI with frontend mapping APIs to display dynamic, interactive visual components. ### What's next Direct Booking Integration: Connect with flight and hotel APIs (like Skyscanner or Amadeus) to allow users to book their generated recommendations directly inside the app. Real-Time Collaborative Planning: Add support for shared workspaces, allowing friends or families to edit and plan the same itinerary together in real time. Offline Mode & PWA Support: Enable travelers to download itineraries offline or export them to PDF, ensuring access to schedules and maps even without cellular data. Expense & Budget Tracker: Integrate a live budgeting feature where users can log actual expenses during their trip and compare them to the AI's initial estimate. Community Hub & Social Sharing: Allow users to publish their generated itineraries to a community feed where other travelers can browse, upvote, and customize them. ## README (from the GitHub repository) # React + Vite This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. Currently, two official plugins are available: - [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs) - [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) ## React Compiler The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation). ## Expanding the ESLint configuration If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project. # ✈️ Travlr AI: Next-Gen AI Travel Planner Travlr AI is an advanced, full-stack travel planner designed to transform how users discover, organize, and experience their journeys. By combining dynamic frontend mapping, serverless backend technology, and state-of-the-art AI language models, Travlr AI generates detailed, context-aware itineraries in seconds. --- ## 🤖 The AI Engine: GPT-5.6 & Codex Integration At the core of Travlr AI's intelligence is a multi-model orchestration powered by OpenAI's advanced AI stack: ### 🌟 GPT-5.6 (Itinerary & Chat Intelligence) We leverage **GPT-5.6** to act as the primary brain of the application. It processes complex user inputs—including duration, budget levels, destinations, and traveler dynamics—to synthesize logical, high-fidelity day-by-day travel schedules. * **Dynamic Decision Making**: GPT-5.6 selects the highest-rated local hotels and maps out chronological daily activities that minimize transit time. * **Context-Aware Chat Companion**: The model powers our interactive chat assistant, maintaining complete context of the user's specific trip to provide instant recommendations, historical facts, and itinerary adjustments in real-time. ### 💻 OpenAI Codex (Structured Mapping & Translation Layer) We utilize **OpenAI Codex** as a backend processing engine to ensure seamless translation between raw language generation and database-ready code schemas. * **Schema Validation & Parsing**: Codex assists in programmatically validating JSON outputs, ensuring that coordinate pairs (latitude and longitude) are correctly formatted for the map rendering component. * **Adaptive Routing Routines**: Codex-driven routines dynamically optimize routing sequences between activities to minimize physical distance, ensuring the generated plan is mathematically viable. --- ## 🛠️ Technology Stack * **Frontend**: React 19, Vite, Tailwind CSS v4, Shadcn UI / Base UI * **Backend**: Node.js, Express.js * **Database**: Lightweight JSON database adapted for ephemeral and serverless environments * **Maps & Geo-visuals**: Leaflet Maps & Google Maps API integration (`@vis.gl/react-google-maps`) * **Deployment**: Pre-configured for serverless platforms like Vercel and web service deployment on Render --- ## 🚀 Key Features * **Zero-to-Hero Travel Planning**: Generate custom multi-day plans with itineraries, budget estimates, and curated hotel recommendations in under 10 seconds. * **Visual Map Synchronization**: Live dual-pane view mapping schedule activities to interactive pins alongside written schedules. * **Interactive AI Chat Companion**: Ask contextual questions directly about your trip and get instant, customized suggestions. * **Aesthetic & Responsive Design**: Premium user interface with smooth animations, dark-mode styling, and skeleton loading screens. --- ## 🧠 Challenges Overcome * **Output Schema Consistency**: Prevented parser crashes by training GPT-5.6 prompts to strictly output schema-compliant JSON, filtering out markdown wrappers. * **Serverless Read-Only Storage**: Overcame Vercel's ephemeral write restrictions by routing the JSON database dynamically to local `/tmp` structures. * **UX Latency Mitigation**: Designed placeholder skeletons and loading progress states to mask the generation time of complex itineraries. --- ## 🏆 Accomplishments * Seamless orchestration of GPT-5.6 for multi-variable itinerary generation. * Robust, highly optimized context compression for the companion chatbot. * Single-command deployment pipeline configured for cloud services. ## Detected evidence (automated analysis) Indexed codebase: 20 recognized source files, 99 KB. - CSS (language) — detected in the code - Express (technology) — detected in the code - Google Gemini (technology) — detected in the code - HTML (language) — detected in the code - JavaScript (language) — detected in the code - React (technology) — detected in the code - Tailwind CSS (technology) — detected in the code - Node.js (technology) — claimed on Devpost, not found in the code - OpenAI (technology) — claimed on Devpost, not found in the code - Vercel (technology) — claimed on Devpost, not found in the code ## Codebase structure (from repository index) ### Files (25 of 25) ``` .gitignore api/index.js components.json eslint.config.js index.html jsconfig.json package.json README.md render.yaml server/db.js server/index.js src/App.css src/App.jsx src/components/custom/Header.jsx src/components/custom/Hero.jsx src/components/ui/button.jsx src/constants/options.jsx src/create-trip/index.jsx src/generate-trip/index.jsx src/index.css src/lib/utils.js src/main.jsx src/view-trip/ViewTrip.jsx vercel.json vite.config.js ``` ### Dependencies - package.json: @base-ui/react@^1.6.0, @eslint/js@^10.0.1, @fontsource-variable/geist@^5.2.9, @google/generative-ai@^0.24.1, @tailwindcss/vite@^4.3.3, @types/react@^19.2.17, @types/react-dom@^19.2.3, @vis.gl/react-google-maps@^1.9.0, @vitejs/plugin-react@^6.0.3, class-variance-authority@^0.7.1, clsx@^2.1.1, concurrently@^10.0.3, cors@^2.8.6, dotenv@^17.4.2, eslint@^10.6.0, eslint-plugin-react-hooks@^7.1.1, eslint-plugin-react-refresh@^0.5.3, express@^5.2.1, globals@^17.7.0, leaflet@^1.9.4, lucide-react@^1.25.0, path@^0.12.7, react@^19.2.7, react-dom@^19.2.7, react-router-dom@^7.18.1, react-select@^5.10.2, shadcn@^4.13.0, tailwind-merge@^3.6.0, tailwindcss@^4.3.3, tw-animate-css@^1.4.0, vite@^8.1.1 ### Recent commits (newest first) - Update README.md - fix: import Loader2 from lucide-react in ViewTrip.jsx - fix: resolve Express 5 wildcard routing crash and Vercel read-only DB write error - Add OpenAI gpt-4o-mini support for itinerary generation and chatbot companion - Configure production deployment settings for Vercel and Render - Merge branch 'main' of github.com:SHREYOTHECODINGEXPERTO/TRAVLR-AI resolving README conflict - Initial commit: Full Stack AI Travel Planner with Live Mode - Initial commit ## Key source files (fetched from GitHub, selected and truncated for size) ### package.json ``` { "name": "ai-travel-planner", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "concurrently \"npm run server\" \"npm run client\"", "server": "node server/index.js", "client": "vite", "build": "vite build", "start": "node server/index.js", "lint": "eslint .", "preview": "vite preview" }, "dependencies": { "@base-ui/react": "^1.6.0", "@fontsource-variable/geist": "^5.2.9", "@google/generative-ai": "^0.24.1", "@tailwindcss/vite": "^4.3.3", "@vis.gl/react-google-maps": "^1.9.0", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "cors": "^2.8.6", "dotenv": "^17.4.2", "express": "^5.2.1", "leaflet": "^1.9.4", "lucide-react": "^1.25.0", "react": "^19.2.7", "react-dom": "^19.2.7", "react-router-dom": "^7.18.1", "react-select": "^5.10.2", "shadcn": "^4.13.0", "tailwind-merge": "^3.6.0", "tailwindcss": "^4.3.3", "tw-animate-css": "^1.4.0" }, "devDependencies": { "@eslint/js": "^10.0.1", "@types/react": "^19.2.17", "@types/react-dom": "^19.2.3", "@vitejs/plugin-react": "^6.0.3", "concurrently": "^10.0.3", "eslint": "^10.6.0", "eslint-plugin-react-hooks": "^7.1.1", "eslint-plugin-react-refresh": "^0.5.3", "globals": "^17.7.0", "path": "^0.12.7", "vite": "^8.1.1" } } ``` ### api/index.js ```javascript import app from '../server/index.js'; export default app; ``` ### src/App.jsx ```javascript import "./App.css"; import Header from "./components/custom/Header"; import { Outlet } from "react-router-dom"; function App() { return ( <>
); } export default App; ``` ### src/main.jsx ```javascript import GenerateTrip from "./generate-trip"; import ViewTrip from "./view-trip/ViewTrip"; import React from "react"; import ReactDOM from "react-dom/client"; import "./index.css"; import App from "./App.jsx"; import { RouterProvider, createBrowserRouter } from "react-router-dom"; import Hero from "./components/custom/Hero"; import CreateTrip from "./create-trip"; const router = createBrowserRouter([ { path: "/", element: , children: [ { index: true, element: , }, { path: "create-trip", element: , }, { path: "generate-trip", element: , }, { path: "view-trip/:tripId", element: , }, ], }, ]); ReactDOM.createRoot(document.getElementById("root")).render( ); ``` ### src/generate-trip/index.jsx ```javascript import React, { useEffect, useState } from "react"; import { useNavigate } from "react-router-dom"; import { Loader2 } from "lucide-react"; function GenerateTrip() { const navigate = useNavigate(); const [loadingStep, setLoadingStep] = useState(0); const [error, setError] = useState(null); useEffect(() => { const paramsStr = localStorage.getItem('tripParams'); if (!paramsStr) { setError("No trip parameters found. Please start from the home page."); return; } const params = JSON.parse(paramsStr); // Simulate steps sequentially for visual feedback const stepInterval = setInterval(() => { setLoadingStep((prev) => (prev < 3 ? prev + 1 : prev)); }, 1500); // Call API fetch('/api/generate-trip', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(params), }) .then((res) => { if (!res.ok) { throw new Error("Failed to generate trip. Server responded with an error."); } return res.json(); }) .then((data) => { clearInterval(stepInterval); // Clean params localStorage.removeItem('tripParams'); // Navigate to view trip navigate(`/view-trip/${data.id}`); }) .catch((err) => { clearInterval(stepInterval); console.error(err); setError(err.message || "An unexpected error occurred during trip generation."); }); return () => clearInterval(stepInterval); }, [navigate]); if (error) { return (

Oops! Something went wrong

{error}

); } return (
{/* Background Glow */}

Generating Your Dream Trip

Our AI is preparing the best itinerary based on your destination, budget, and travel preferences.

= 0 ? "opacity-100" : "opacity-30"}`} size={20} />

= 0 ? "text-cyan-200" : "text-gray-500"}>Finding beautiful destinations...

= 1 ? "opacity-100" : "opacity-30"}`} size={20} />

= 1 ? "text-cyan-200" : "text-gray-500"}>Selecting top-rated hotels...

= 2 ? "opacity-100" : "opacity-30"}`} size={20} />

= 2 ? "text-cyan-200" : "text-gray-500"}>Planning daily itinerary...

= 3 ? "opacity-100" : "opacity-30"}`} size={20} />

= 3 ? "text-cyan-200" : "text-gray-500"}>Optimizing travel routes...

This usually takes a few seconds...

); } export default GenerateTrip; ``` ### src/create-trip/index.jsx ```javascript import { Button } from "../components/ui/button"; import React, { useState } from "react"; import { useNavigate } from "react-router-dom"; import Select from "react-select"; import { SelectBudgetOptions, SelectTravelList, } from "../constants/options"; function CreateTrip() { const navigate = useNavigate(); const [formData, setFormData] = useState({}); const options = [ { value: "kolkata", label: "Kolkata, West Bengal, India" }, { value: "delhi", label: "New Delhi, India" }, { value: "mumbai", label: "Mumbai, Maharashtra, India" }, ]; return (
{/* Background Video */} {/* Background Video */} {/* Dark Overlay */}
{/* Dark Overlay */}
{/* Background Glow */}
{/* Background Grid */}
{/* Heading */}
✈ AI Powered Trip Planner

Plan Your Dream Journey

Tell our AI where you're going and it will create a beautiful personalized travel itinerary within seconds.

{/* Destination */}

Choose Destination

{ setFormData({ ...formData, noOfDays: e.target.value, }); }} />
{/* Budget */}

Choose Your Budget

Select the budget that best fits your trip.

{SelectBudgetOptions.map((item) => (
setFormData({ ...formData, budget: item.title, }) } className={`cursor-pointer transition-all duration-300 hover:-translate-y-3 hover:scale-105 ${ formData?.budget === item.title ? "text-cyan-400" : "text-white" }`} >
{item.icon}

{item.title}

{item.desc}

{item.people}

))}
{/* Traveller */}

👨‍👩‍👧‍👦 Who's Traveling?

Tell AI who is joining your adventure.

{SelectTravelList.map((item) => (
setFormData({ ...formData, traveler: item.title, }) } className={`cursor-pointer transition-all duration-300 hover:-translate-y-3 hover:scale-105 ${ formData?.traveler === item.title ? "text-cyan-400" : "text-white" }`} >
{item.icon}

{item.title}

[truncated — 1347 more characters] ``` ### server/index.js ```javascript import express from 'express'; import cors from 'cors'; import dotenv from 'dotenv'; import { GoogleGenerativeAI } from '@google/generative-ai'; import { saveTrip, getTrip, getAllTrips } from './db.js'; import path from 'path'; import { fileURLToPath } from 'url'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); dotenv.config(); const app = express(); app.use(cors()); app.use(express.json()); const PORT = process.env.PORT || 5000; // Initialize LLM APIs const GEMINI_API_KEY = process.env.GEMINI_API_KEY; const OPENAI_API_KEY = process.env.OPENAI_API_KEY; let genAI = null; if (GEMINI_API_KEY) { genAI = new GoogleGenerativeAI(GEMINI_API_KEY); console.log("Gemini API key loaded successfully."); } if (OPENAI_API_KEY) { console.log("OpenAI API key loaded successfully."); } if (!GEMINI_API_KEY && !OPENAI_API_KEY) { console.warn("WARNING: Neither GEMINI_API_KEY nor OPENAI_API_KEY is configured. Running in sandbox mode with fallback mock data."); } // Fallback Mock Data for Demo const MOCK_TRIPS = { kolkata: { destination: "Kolkata, West Bengal, India", noOfDays: 3, budget: "Medium", traveler: "Couple", coordinates: { latitude: 22.5726, longitude: 88.3639 }, tripOverview: { description: "Kolkata, the City of Joy, is the cultural capital of India. Known for its grand colonial architecture, rich artistic heritage, and legendary street food, it offers a deep, soul-stirring experience.", packingSuggestions: ["Light cotton clothing", "Comfortable walking shoes", "Umbrella", "Hand sanitizer"], bestTimeToVisit: "October to February" }, hotels: [ { hotelName: "The Oberoi Grand", address: "15, Jawaharlal Nehru Rd, Dharmatala, Kolkata", price: "180 USD/night", rating: 4.8, description: "Elegant colonial-era luxury hotel in the heart of Kolkata's shopping district." }, { hotelName: "Fairlawn Hotel", address: "13-A, Sudder St, Kolkata", price: "60 USD/night", rating: 4.2, description: "Charming heritage hotel offering a cozy British-colonial atmosphere and lush green garden." } ], itinerary: [ { day: 1, theme: "Colonial Heritage & Classic Landmarks", schedule: [ { time: "09:00 AM", activityName: "Victoria Memorial", description: "Visit the iconic white marble palace built in memory of Queen Victoria. Stroll through the lush gardens.", cost: "5 USD", duration: "2 hours", location: "Victoria Memorial Hall, 1, Queens Way, Kolkata", latitude: 22.5448, longitude: 88.3426 }, { time: "01:00 PM", activityName: "Lunch at Peter Cat", description: "Savor the famous Chelo Kabab at one of Park Street's legendary legacy restaurants.", cost: "15 USD", duration: "1.5 hours", location: "18A, Park St, Kolkata", latitude: 22.5531, longitude: 88.3534 }, { time: "03:00 PM", activityName: "Indian Museum", description: "Explore the oldest and largest museum in India, featuring rare collections of antiques, armor, and fossils.", cost: "4 USD", duration: "2.5 hours", location: "27, Jawaharlal Nehru Rd, Kolkata", latitude: 22.5579, longitude: 88.3512 } ] }, { day: 2, theme: "Cultural Exploration & Spiritual Peace", schedule: [ { time: "09:00 AM", activityName: "Dakshineswar Kali Temple", description: "A famous 19th-century Hindu temple dedicated to Bhavatarini, located on the eastern bank of the Hooghly River.", cost: "Free", duration: "2 hours", location: "Dakshineswar, Kolkata", latitude: 22.6550, longitude: 88.3582 }, { time: "12:00 PM", activityName: "Belur Math", description: "Cross the river by ferry to visit the headquarters of the Ramakrishna Mission, showcasing architectural harmony of temple, mosque, and church.", cost: "Free", duration: "2 hours", location: "Belur, Howrah", latitude: 22.6327, longitude: 88.3556 }, { time: "04:30 PM", activityName: "Howrah Bridge & Flower Market", description: "View the engineering marvel of Howrah Bridge at sunset and walk through the vibrant, bustling Mallick Ghat Flower Market.", cost: "Free", duration: "1.5 hours", location: "Mallick Ghat, Howrah", latitude: 22.5854, longitude: 88.3478 } ] }, { day: 3, theme: "Local Flavors & Artisanal Culture", schedule: [ { time: "09:30 AM", activityName: "Kumartuli Potter's Colony", description: "Walk through the traditional potters' quarter in northern Kolkata where clay idols of gods and goddesses are handcrafted.", cost: "Free", duration: "2 hours", location: "Kumartuli, Hatkhola, Kolkata", latitude: 22.6014, longitude: 88.3619 }, { time: "12:30 PM", activityName: "Coffee & Snacks at Indian Coffee House", description: "Visit the legendary meeting place for intellectuals, students, and artists on College Street.", cost: "5 USD", duration: "1.5 hours", location: "15, Bankim Chatterjee St, College Street, Kolkata", latitude: 22.5759, longitude: 88.3629 }, { time: "03:00 PM", [truncated — 23515 more characters] ``` ### render.yaml ```yaml services: - type: web name: travlr-ai env: node buildCommand: npm install && npm run build startCommand: npm start envVars: - key: GEMINI_API_KEY sync: false - key: PORT value: 5000 ``` ### index.html ```html ai-travel-planner

``` ### vite.config.js ```javascript import { defineConfig } from "vite"; import react from "@vitejs/plugin-react"; import tailwindcss from "@tailwindcss/vite"; import path from "node:path"; export default defineConfig({ plugins: [react(), tailwindcss()], resolve: { alias: { "@": path.resolve(__dirname, "./src"), }, }, server: { proxy: { "/api": { target: "http://localhost:5000", changeOrigin: true, secure: false, }, }, }, }); ``` [10 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]