How shahvir-w/3d-flight-tracker works
Project Type and Purpose
• This is a full-stack web application called “3D Flight Tracker.”
• Frontend: React + TypeScript + Mapbox GL to render a 3D globe and flight paths.
• Backend: Node.js + Express + TypeScript REST API that fetches flight data from the AeroAPI.
• No traditional database—favorite flights persist in browser Local Storage; flight data comes from the AeroAPI.
File Structure Analysis
• Top level:
• backend/ – Express server code (controllers, routes, utils, tests).
• frontend/ – React app (components, pages, utils, styles).
• Backend breaks down into:
• src/routes (defines /api/flights/:flightNum)
• src/controllers (flightData.ts orchestrates data fetch & parsing)
• src/utils (getGeoLocation, parseData, timeCalculations)
• src/types (AeroAPI response types, parsedFlight model)
• Frontend breaks down into:
• src/pages (SearchPage, FlightDetailsPage)
• src/components (SearchBar, FlightDetails, Globe, SavedModal)
• src/utils (savedFlights for Local Storage)
• React Router for navigation, Axios for HTTP calls, Mapbox GL for rendering.
Key Insights from README
• RESTful endpoint: GET /api/flights/:flightNum
• Env-based config (.env for Mapbox token, API URL, AeroAPI key, port)
• Tech stack and feature overview confirm separation of concerns and external dependencies.
Main Components and Their Relationships
A. User Interface (Browser)
• React pages & components
• Mapbox GL (3D globe)
• Local Storage (for saved flights)
B. Frontend Server (Vite dev server or static build)
• Serves React assets
• Proxies API calls to backend
C. Backend API Server (Node/Express)
• Routes → Controllers → Utils
• Environment config
• Communicates with external AeroAPI
D. External Services
• AeroAPI (flight data provider)
• Mapbox GL (tile & globe service)
Data flow:
1. User enters flight number in SearchBar →
2. Axios GET to Frontend dev server proxy →
3. Request forwarded to Express /api/flights/:flightNum →
4. Controller uses Utils to call AeroAPI, parse & compute times →
5. JSON response back to frontend →
6. React updates state, Globe component plots trajectory →
7. “Save” action writes flight to browser Local Storage.
Architectural Patterns & Design Principles
• Clear separation of concerns (UI vs API vs external services).
• MVC-inspired backend: Routes (entry) → Controllers (business logic) → Utils (helpers) → Types (contracts).
• Component-based UI in React; page‐level vs shared components.
• Environment‐based config for keys & URLs.
• RESTful API design.
• No heavy server‐side storage—uses client‐side Local Storage.
Detailed Elements to Capture
• The flow from SearchPage → SearchBar → Axios → /api/flights/:flightNum.
• Separation of src/routes vs src/controllers vs src/utils in backend.
• Mapbox GL integration sitting in the Globe component.
• Local Storage module for savedFlights utility.
• Environment variables for AeroAPI_KEY, VITE_MAPBOX_TOKEN, VITE_API_URL.
Final Recommendations
• Grouping of frontend modules (components, pages, utils) and backend modules (routes, controllers, utils) within their service boundaries.