Spotter Flight Engine ✈️

Spotter Flight Engine is a next-generation flight search application engineered for performance, stability, and user experience. It leverages a generic BFF (Backend-for-Frontend) architecture to securely interface with the Amadeus GDS, providing real-time flight availability with optimistic UI updates and sub-second interactions.

🚀 Live Demo

---

✨ Key Architectural Features

🛡️ Secure BFF Architecture

Directly exposing third-party API keys on the client is a critical security vulnerability. This project implements a Vercel Serverless Function (/api/search) as a secure proxy.

• Credential Isolation: AMADEUS_CLIENT_ID and SECRET never leave the server environment.
• Data Transformation: The backend sanitizes and shapes 3rd-party data into our strictly typed Domain Model before it reaches the client, reducing bundle size and processing overhead.

⚡ Smart Token Caching

To combat the latency of OAuth2 handshakes, the backend implements a Singleton Token Cache.

• Mechanism: The access token is cached in memory (warm execution context).
• Impact: Checks expiration before every request, reusing valid tokens to save ~500ms of latency per search and preserving API quota.

🎨 Optimistic UI & Stability

"Jank" is the enemy of trust.

• Layout Stability: Precision-engineered Skeleton loaders match the improved 4-4-4 Grid layout of the real cards, ensuring Zero Cumulative Layout Shift (CLS) when data loads.
• Compute-on-Write: Expensive filtering operations are calculated once during the Redux/Zustand action dispatch, ensuring valid referential equality for React rendering optimization.

🚄 High-Performance Virtualization

Rendering thousands of DOM nodes kills mobile performance.

• Window Virtualization: Integrated @tanstack/react-virtual to render only the flight cards currently in the viewport.
• Result: Smooth 60fps scrolling even with 500+ flight results.

🔗 Deep Linking & URL State

Shareable results are a must for travel apps.

• Bi-directional Sync: A custom hook synchronizes the Zustand store with URL Query Parameters.
• Persistence: Refreshing the page hydrates the exact search state, filters, and passenger counts seamlessly.

---

🛠️ Tech Stack

• Core: React 18, TypeScript, Vite
• State Management: Zustand (with custom "Compute-on-Write" middleware pattern)
• UI System: Material UI v5 (Custom "Spotter" Theme), Lucide React Icons
• Backend: Node.js, Vercel Serverless Functions
• Data Source: Amadeus Flight Offers Search API (v2)

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• Amadeus for Developers API Keys (Test Environment)

Installation

# Clone the repository
git clone https://github.com/your-username/spotter-flight-engine.git

# Install dependencies
npm install

Environment Setup

Create a .env file in the root directory:

# Amadeus API Credentials (Server-Side Only)
AMADEUS_CLIENT_ID=your_client_id_here
AMADEUS_CLIENT_SECRET=your_client_secret_here

# Dev Modes
# To test without Amadeus keys, simply visit http://localhost:5173/dev to force Mock Data.
# You can also append `?mode=dev`, but using the /dev path is recommended for stability.

Running Locally

Option A: Full Stack (Recommended) Emulates the Vercel Serverless environment. Required for the Real Amadeus API.

npx vercel dev

Option B: Frontend Only (Mock Mode) Faster startup, uses client-side mock data.

npm run dev
# Then visit http://localhost:5173/dev

---

🧪 Deployment

This project is optimized for Vercel.

1. Connect your GitHub repository to Vercel.
2. Add the AMADEUS_CLIENT_ID and AMADEUS_CLIENT_SECRET in the Project Settings > Environment Variables.
3. Deploy! The api/ directory will be automatically turned into Serverless Functions.