✈️ SkyWander - Flight Comparison Platform

A full-stack flight comparison app inspired by Skyscanner, built with Next.js, Express, PostgreSQL, and Redis. Aggregates results from the Amadeus and Kiwi/Tequila APIs.

---

🗂 Project Structure

skywander/
├── frontend/          # Next.js 14 app (deploy to Vercel)
├── backend/           # Express API (deploy to Railway/Render)
├── database/          # PostgreSQL schema + seed data
└── docker-compose.yml # Local dev with all services

---

🚀 Quick Start (Docker)

# 1. Clone and enter the project
git clone https://github.com/codexdeep/skywander
cd skywander

# 2. Copy and fill in backend env vars
cp backend/.env.example backend/.env
# Edit backend/.env — add Amadeus + Kiwi API keys

# 3. Copy frontend env
cp frontend/.env.local.example frontend/.env.local

# 4. Start everything
docker-compose up --build

# App runs at:
#   Frontend → http://localhost:3000
#   Backend  → http://localhost:4000
#   Postgres → localhost:5432
#   Redis    → localhost:6379

---

🔑 API Keys (all free tier)

Amadeus Self-Service API

1. Register at https://developers.amadeus.com
2. Create a new app → copy Client ID and Client Secret
3. Free tier: 2,000 API calls/month
4. Set in backend/.env:

   AMADEUS_CLIENT_ID=your_id
   AMADEUS_CLIENT_SECRET=your_secret
   

5. Use https://test.api.amadeus.com until production-ready

Kiwi / Tequila API

1. Register at https://tequila.kiwi.com
2. Get your API Key from the dashboard
3. Set in backend/.env:

   KIWI_API_KEY=your_key
   

Email Alerts (Resend — free 100 emails/day)

1. Register at https://resend.com
2. Create an API key
3. Set in backend/.env:

   SMTP_HOST=smtp.resend.com
   SMTP_PORT=465
   SMTP_USER=resend
   SMTP_PASS=re_xxxxxxxx
   EMAIL_FROM=alerts@yourdomain.com
   

---

🛠 Manual Setup (without Docker)

Backend

cd backend
npm install
cp .env.example .env        # fill in your keys

# Start PostgreSQL + Redis locally, then:
npm run dev                 # starts on http://localhost:4000

Frontend

cd frontend
npm install
cp .env.local.example .env.local

npm run dev                 # starts on http://localhost:3000

Database

# Run schema against your PostgreSQL instance
psql -U postgres -d skywander -f database/schema.sql

---

📡 API Endpoints

Method	Path	Description
GET	/api/flights/search	Search flights (Amadeus + Kiwi)
GET	/api/flights/calendar	Price calendar for a route
GET	/api/airports/search?q=DEL	Airport autocomplete
GET	/api/airports/popular?origin=DEL	Popular routes
POST	/api/alerts	Create price alert
DELETE	/api/alerts/:id	Unsubscribe from alert
GET	/api/health	Health check

Flight Search Example

GET /api/flights/search?origin=DEL&destination=DXB&departureDate=2025-06-15&adults=1&cabinClass=ECONOMY&currencyCode=INR

---

🌐 Deployment

Frontend → Vercel

cd frontend
npx vercel --prod

# Set environment variable in Vercel dashboard:
# NEXT_PUBLIC_API_URL = https://your-backend.railway.app

Backend → Railway

# Install Railway CLI
npm install -g @railway/cli
railway login

cd backend
railway up

# Add env vars in Railway dashboard
# Add PostgreSQL and Redis services in Railway

Database → Supabase or Neon (free tier)

1. Create project at https://supabase.com or https://neon.tech
2. Run database/schema.sql in the SQL editor
3. Copy the connection string to DATABASE_URL

---

🏗 Architecture

User Browser
     │
     ▼
Next.js Frontend (Vercel)
     │  REST API calls
     ▼
Express Backend (Railway)
     │
     ├─── Redis Cache ──────── 10-min TTL per route
     │
     ├─── Amadeus API ─────── Flight offers, price calendar
     │
     ├─── Kiwi Tequila API ── Budget routes, cheap fares
     │
     └─── PostgreSQL ───────── Airports, airlines, price history
                               Price alerts, analytics

---

⚡ Performance

• Redis caching: Search results cached for 10 minutes per route
• Parallel API calls: Amadeus + Kiwi fire simultaneously via Promise.allSettled
• SSR: Next.js server-side rendering for fast initial load
• Target: < 2 second search response (cached: < 100ms)

---

📁 Key Files

backend/src/
  server.ts                   Express app + cron jobs
  services/
    amadeus.service.ts        Amadeus auth + flight search
    kiwi.service.ts           Kiwi/Tequila API integration
    flight.service.ts         Aggregator — merges both APIs
    airport.service.ts        Airport autocomplete
    alert.service.ts          Price alerts + email
  config/
    database.ts               PostgreSQL pool
    redis.ts                  Redis client + cache helpers

frontend/src/
  app/page.tsx                Home page (hero + popular)
  app/results/page.tsx        Search results page
  components/
    search/SearchForm.tsx     Full search form
    search/AirportInput.tsx   Autocomplete airport picker
    results/FlightCard.tsx    Flight offer card + detail
    results/PriceCalendar.tsx Price calendar strip
    filters/FiltersSidebar.tsx All filter controls
  lib/
    store.ts                  Zustand state + filter logic
    api.ts                    Axios API client
    utils.ts                  Formatting helpers

---

🔮 Roadmap

• Hotel search (Amadeus Hotel Search API)
• Multi-city trips
• AI price prediction (trend analysis)
• Explore map (cheapest destinations)
• User accounts + saved searches
• Car rental integration

---

📄 License

MIT — use freely, attribution appreciated.