# shahvir-w/3d-flight-tracker architecture

> Architecture diagram of the GitHub repository shahvir-w/3d-flight-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shahvir-w/3d-flight-tracker
- Repository: https://github.com/shahvir-w/3d-flight-tracker

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser/Client Layer
    subgraph "Browser/Client"
        direction TB
        FEEntry["main.tsx"]:::frontend
        App["App.tsx"]:::frontend
        subgraph "Pages"
            SP["SearchPage.tsx"]:::frontend
            FDP["FlightDetailsPage.tsx"]:::frontend
        end
        subgraph "Components"
            SB["SearchBar.tsx"]:::frontend
            FD["FlightDetails.tsx"]:::frontend
            GLOBE["Globe.tsx"]:::frontend
            SM["SavedModal.tsx"]:::frontend
        end
        UTIL_FE["savedFlights.ts"]:::data
        LS(("Local Storage")):::data
    end

    %% Dev Server Layer
    VITE["Vite Dev Server (5173)"]:::backend
    ViteConfig["vite.config.ts"]:::backend

    %% Backend API Server Layer
    subgraph "Backend API Server"
        direction TB
        BEEntry["index.ts"]:::backend
        Routes["flightData.ts (routes)"]:::backend
        Controller["flightData.ts (controller)"]:::backend
        subgraph "Utils"
            Geo["getGeoLocation.ts"]:::backend
            Parse["parseData.ts"]:::backend
            Time["timeCalculations.ts"]:::backend
        end
        subgraph "Types"
            AeroType["AeroAPI.ts"]:::backend
            ParsedType["parsedFlight.ts"]:::backend
        end
        subgraph "Tests"
            Test1["calculateFlightTimes.test.ts"]:::backend
            Test2["getGeoLocationData.test.ts"]:::backend
        end
    end

    %% External Services
    Aero["AeroAPI"]:::external
    Mapbox["Mapbox GL"]:::external

    %% Data Flows
    SP --> SB
    SB -->|HTTP GET /api/flights/:flightNum| VITE
    VITE -->|Proxy REST| BEEntry
    BEEntry -->|Express Router| Routes
    Routes -->|calls| Controller
    Controller --> Geo
    Controller --> Parse
    Controller --> Time
    Controller -->|HTTPS REST| Aero
    Aero -->|JSON| Controller
    Controller -->|JSON response| Routes
    Routes -->|HTTP response| BEEntry
    BEEntry -->|proxied response| VITE
    VITE -->|Axios JSON| SP
    SP --> FDP
    FDP --> FD
    FDP --> GLOBE
    FD -->|Save action| UTIL_FE
    UTIL_FE --> LS
    GLOBE --> Mapbox

    %% Config Dependencies
    VITE -.-> ViteConfig
    Controller -.->|uses| AeroType
    Controller -.->|uses| ParsedType

    %% Click Events
    click FEEntry "https://github.com/shahvir-w/3d-flight-tracker/blob/main/frontend/src/main.tsx"
    click App "https://github.com/shahvir-w/3d-flight-tracker/blob/main/frontend/src/App.tsx"
    click SP "https://github.com/shahvir-w/3d-flight-tracker/blob/main/frontend/src/pages/SearchPage.tsx"
    click FDP "https://github.com/shahvir-w/3d-flight-tracker/blob/main/frontend/src/pages/FlightDetailsPage.tsx"
    click SB "https://github.com/shahvir-w/3d-flight-tracker/blob/main/frontend/src/components/SearchBar.tsx"
    click FD "https://github.com/shahvir-w/3d-flight-tracker/blob/main/frontend/src/components/FlightDetails.tsx"
    click GLOBE "https://github.com/shahvir-w/3d-flight-tracker/blob/main/frontend/src/components/Globe.tsx"
    click SM "https://github.com/shahvir-w/3d-flight-tracker/blob/main/frontend/src/components/SavedModal.tsx"
    click UTIL_FE "https://github.com/shahvir-w/3d-flight-tracker/blob/main/frontend/src/utils/savedFlights.ts"
    click ViteConfig "https://github.com/shahvir-w/3d-flight-tracker/blob/main/frontend/vite.config.ts"
    click BEEntry "https://github.com/shahvir-w/3d-flight-tracker/blob/main/backend/src/index.ts"
    click Routes "https://github.com/shahvir-w/3d-flight-tracker/blob/main/backend/src/routes/flightData.ts"
    click Controller "https://github.com/shahvir-w/3d-flight-tracker/blob/main/backend/src/controllers/flightData.ts"
    click Geo "https://github.com/shahvir-w/3d-flight-tracker/blob/main/backend/src/utils/getGeoLocation.ts"
    click Parse "https://github.com/shahvir-w/3d-flight-tracker/blob/main/backend/src/utils/parseData.ts"
    click Time "https://github.com/shahvir-w/3d-flight-tracker/blob/main/backend/src/utils/timeCalculations.ts"
    click AeroType "https://github.com/shahvir-w/3d-flight-tracker/blob/main/backend/src/types/AreoAPI.ts"
    click ParsedType "https://github.com/shahvir-w/3d-flight-tracker/blob/main/backend/src/types/parsedFlight.ts"
    click Test1 "https://github.com/shahvir-w/3d-flight-tracker/blob/main/backend/src/__tests__/calculateFlightTimes.test.ts"
    click Test2 "https://github.com/shahvir-w/3d-flight-tracker/blob/main/backend/src/__tests__/getGeoLocationData.test.ts"

    %% Styles
    classDef frontend fill:#ccf,stroke:#333,stroke-width:1px
    classDef backend fill:#cfc,stroke:#333,stroke-width:1px
    classDef data fill:#fcf,stroke:#333,stroke-width:1px
    classDef external fill:#eef,stroke:#333,stroke-width:1px
```
