🤖 AI Travel Assistant

Your intelligent companion for seamless travel planning

Features • Demo • Installation • Usage • API Docs • Contributing

---

📋 Table of Contents

• Overview
• Features
• Tech Stack
• Architecture
• Installation
• Configuration
• Usage
• API Documentation
• Deployment
• Contributing
• License

🌟 Overview

AI Travel Assistant is a cutting-edge, full-stack application that revolutionizes travel planning through AI-powered natural language processing. Users can search flights, check weather forecasts, get travel summaries, and interact with the system using voice commands or text input.

Key Highlights

• 🎤 Voice-Enabled Interface - Powered by Deepgram for accurate speech recognition
• 🤖 AI-Powered Conversations - Integrated with OpenRouter for intelligent responses
• ✈️ Smart Flight Search - Real-time flight data via Amadeus API
• 🌤️ Weather Intelligence - Accurate forecasts using OpenWeatherMap
• 🎨 Modern UI/UX - Beautiful, responsive design with dark/light mode
• 🚀 High Performance - Built with modern frameworks for optimal speed

✨ Features

🎯 Core Functionality

Feature	Description
Flight Search	Search and compare flights using natural language queries
Weather Forecasting	Get real-time weather data for any destination
AI Chat Assistant	Conversational AI for travel planning and information
Voice Input	Hands-free interaction with voice commands
Travel Summaries	AI-generated summaries of travel articles and reviews
Multi-Modal Interaction	Text, voice, or GUI-based interactions

🎨 User Experience

• Responsive Design - Works seamlessly on desktop, tablet, and mobile
• Dark/Light Mode - System-aware theme with manual toggle
• Smooth Animations - Framer Motion powered transitions
• Accessibility - WCAG 2.1 AA compliant
• Progressive Web App - Installable on any device

🔐 Security & Authentication

• JWT-based authentication
• Secure API key management
• CORS protection
• Rate limiting
• Input validation and sanitization

🛠️ Tech Stack

Frontend

React 18.2          - UI Framework
TypeScript 5.2      - Type Safety
Vite 5.0            - Build Tool
Tailwind CSS 3.4    - Styling
Framer Motion       - Animations
React Query         - Data Fetching
Zustand             - State Management
React Hook Form     - Form Handling
Zod                 - Schema Validation
Lucide React        - Icons
Recharts            - Data Visualization

Backend

FastAPI 0.100+      - Web Framework
Python 3.12+        - Programming Language
SQLAlchemy          - ORM
Pydantic            - Data Validation
Uvicorn             - ASGI Server
SQLite              - Database
Httpx               - HTTP Client
Python-Jose         - JWT Handling
Passlib             - Password Hashing

External Services

OpenRouter          - AI/LLM Provider
Deepgram            - Voice Recognition
Amadeus             - Flight Data API
OpenWeatherMap      - Weather Data API

🏗️ Architecture

ai-assistant-app/
├── ai-assistant/
│   ├── frontend/              # React TypeScript Application
│   │   ├── src/
│   │   │   ├── components/    # Reusable UI components
│   │   │   │   ├── home/      # Landing page sections
│   │   │   │   ├── chat/      # Chat interface
│   │   │   │   ├── flights/   # Flight search components
│   │   │   │   ├── weather/   # Weather widgets
│   │   │   │   ├── ui/        # Base UI components
│   │   │   │   └── layout/    # Layout components
│   │   │   ├── hooks/         # Custom React hooks
│   │   │   ├── lib/           # Utilities and constants
│   │   │   ├── pages/         # Page components
│   │   │   ├── types/         # TypeScript types
│   │   │   └── styles.css     # Global styles
│   │   ├── public/            # Static assets
│   │   └── package.json
│   │
│   └── backend/               # FastAPI Python Application
│       ├── app/
│       │   ├── api/           # API routes
│       │   │   └── v1/        # API version 1
│       │   │       ├── endpoints/  # Route handlers
│       │   │       └── router.py   # API router
│       │   ├── core/          # Core functionality
│       │   │   ├── config.py       # Configuration
│       │   │   ├── security.py     # Auth & security
│       │   │   ├── ai_client.py    # AI integration
│       │   │   └── voice_client.py # Voice integration
│       │   ├── database/      # Database setup
│       │   ├── models/        # SQLAlchemy models
│       │   ├── schemas/       # Pydantic schemas
│       │   ├── services/      # Business logic
│       │   └── main.py        # Application entry
│       └── requirements.txt
│
├── .env                       # Environment variables
├── README.md                  # This file
└── .gitignore

🚀 Installation

Prerequisites

• Python 3.12+ - Download
• Node.js 18+ - Download
• npm 9+ or yarn
• Git - Download

1. Clone the Repository

git clone https://github.com/yocho1/ai-assistant-app.git
cd ai-assistant-app

2. Backend Setup

# Navigate to backend directory
cd ai-assistant/backend

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Initialize database
python -m app.database.init_db

3. Frontend Setup

# Navigate to frontend directory
cd ../frontend

# Install dependencies
npm install

# or with yarn
yarn install

⚙️ Configuration

Environment Variables

Create a .env file in the backend directory:

# Authentication
SECRET_KEY=your-super-secret-jwt-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

# OpenRouter AI
OPENROUTER_API_KEY=sk-or-v1-your-api-key-here
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=openai/gpt-4-turbo-preview

# Deepgram Voice
DEEPGRAM_API_KEY=your-deepgram-api-key

# Amadeus Flight API
AMADEUS_API_KEY=your-amadeus-api-key
AMADEUS_API_SECRET=your-amadeus-api-secret
AMADEUS_BASE_URL=https://test.api.amadeus.com/v1

# OpenWeatherMap
OPENWEATHER_API_KEY=your-openweather-api-key

# Database
DATABASE_URL=sqlite+aiosqlite:///./assistant.db

# CORS
BACKEND_CORS_ORIGINS=["http://localhost:5173","http://localhost:8000"]

API Keys

Get your API keys from:

• OpenRouter: platform.openrouter.ai
• Deepgram: deepgram.com
• Amadeus: developers.amadeus.com
• OpenWeatherMap: openweathermap.org/api

💻 Usage

Development Mode

Start Backend Server

cd ai-assistant/backend
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

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

Start Frontend Server

cd ai-assistant/frontend
npm run dev

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

Production Build

Backend

cd ai-assistant/backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Frontend

cd ai-assistant/frontend
npm run build
npm run preview

📚 API Documentation

Interactive API Docs

Once the backend is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Key Endpoints

Authentication

POST /api/v1/auth/register
POST /api/v1/auth/login
POST /api/v1/auth/refresh

Chat

POST /api/v1/chat/
GET  /api/v1/chat/history
POST /api/v1/chat/clear

Flights

POST /api/v1/flights/search
POST /api/v1/flights/book

Weather

GET  /api/v1/weather/{city}

Voice

POST /api/v1/voice/transcribe
POST /api/v1/voice/synthesize

Example Request

curl -X POST "http://localhost:8000/api/v1/chat/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "message": "Find me flights from New York to Paris next week",
    "conversation_id": "optional-id"
  }'

🚢 Deployment

Docker Deployment (Recommended)

# Create Dockerfile for backend
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Cloud Platforms

Backend

• Railway: Connect GitHub repo, auto-deploy
• Heroku: git push heroku main
• AWS EC2: Deploy with PM2 or Systemd
• Google Cloud Run: Container-based deployment
• Azure App Service: Web app deployment

Frontend

• Vercel: vercel deploy
• Netlify: netlify deploy --prod
• AWS Amplify: Connect GitHub repo
• Cloudflare Pages: Git integration

Environment Configuration

Set environment variables in your deployment platform's dashboard or use .env files.

🧪 Testing

Backend Tests

cd ai-assistant/backend
pytest tests/ -v --cov=app

Frontend Tests

cd ai-assistant/frontend
npm run test
npm run test:coverage

📊 Performance

• Lighthouse Score: 90+
• First Contentful Paint: < 1.5s
• Time to Interactive: < 3.5s
• API Response Time: < 200ms (average)

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Code Style

• Python: Follow PEP 8, use Black formatter
• TypeScript: Follow Airbnb style guide, use Prettier
• Commits: Use conventional commits format

🐛 Troubleshooting

Common Issues

Backend won't start:

# Check Python version
python --version  # Should be 3.12+

# Reinstall dependencies
pip install --force-reinstall -r requirements.txt

Frontend build errors:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

CORS errors:

• Verify BACKEND_CORS_ORIGINS in .env
• Check that frontend URL matches CORS origins

📝 License

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

👥 Authors

• yocho1 - Initial work - GitHub

🙏 Acknowledgments

• OpenRouter for AI capabilities
• Deepgram for voice recognition
• Amadeus for flight data
• OpenWeatherMap for weather data
• All open-source contributors

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@example.com

---

Made with ❤️ and ☕

If you find this project useful, please consider giving it a ⭐!

⬆ Back to Top