# raihacks/satelliteorbit architecture

> Architecture diagram of the GitHub repository raihacks/satelliteorbit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raihacks/satelliteorbit
- Repository: https://github.com/raihacks/satelliteorbit

## Overview

This is a browser-based satellite tracker with an Express API. Users can load a satellite catalog or enter a NORAD ID, then view tracked satellites on a 3D Earth, select one to see telemetry and its orbit/ground track, and move the camera around the globe. The backend retrieves TLE data from Celestrak and uses Upstash Redis as a cache. Frontend interaction and backend route behavior are sampled; some frontend modules are represented from the file tree, so uncertain wiring is omitted.

Main entry points: [`frontend/js/main.js`](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/main.js) (App workflow), [`frontend/js/satellite/satelliteManager.js`](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/satellite/satelliteManager.js) (Satellite manager), [`backend/satelliteRoute.js`](https://github.com/raihacks/satelliteorbit/blob/main/backend/satelliteRoute.js) (Satellite routes), [`backend/server.js`](https://github.com/raihacks/satelliteorbit/blob/main/backend/server.js) (Express server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Viewer interaction"]
  node_main["App workflow<br/>[main.js]"]
  node_telemetry["Telemetry display<br/>[telemetry.js]"]
end

subgraph group_visualization["3D visualization"]
  node_renderer["WebGL renderer<br/>[renderer.js]"]
  node_scene["Scene setup<br/>[scene.js]"]
  node_controls["Camera controls<br/>[controls.js]"]
  node_earth["Earth globe<br/>[earth.js]"]
end

subgraph group_tracking["Satellite tracking"]
  node_manager["Satellite manager"]
  node_marker["Satellite markers<br/>[satelliteMarker.js]"]
  node_coordinates["Coordinate conversion<br/>[latLonToVector3.js]"]
  node_orbit["Orbit prediction<br/>[orbitPrediction.js]"]
  node_updates["Satellite updates<br/>[satelliteUpdate.js]"]
end

subgraph group_backend["Data service"]
  node_tleclient["TLE client<br/>[fetchTLE.js]"]
  node_catalogclient["Catalog client<br/>[fetchTLECatalog.js]"]
  node_server["Express server<br/>[server.js]"]
  node_routes["Satellite routes<br/>[satelliteRoute.js]"]
  node_fetcher["Satellite fetcher<br/>[fetchSatellites.js]"]
  node_redis[("TLE cache")]
end

node_user(("Viewer"))
node_celestrak["Celestrak"]
node_texture["Earth texture"]

node_user -->|"interacts with"| node_main
node_main -->|"creates"| node_scene
node_main -->|"creates"| node_renderer
node_main -->|"creates"| node_controls
node_main -->|"creates"| node_earth
node_main -->|"manages"| node_manager
node_main -->|"updates"| node_telemetry
node_main -->|"requests catalog or TLE"| node_server
node_scene -->|"hosts"| node_earth
node_renderer -->|"renders"| node_scene
node_controls -->|"controls camera"| node_renderer
node_earth -->|"loads texture"| node_texture
node_manager -->|"creates markers"| node_marker
node_manager -->|"converts positions"| node_coordinates
node_manager -->|"predicts paths"| node_orbit
node_manager -->|"updates tracking"| node_updates
node_manager -->|"fetches TLE"| node_tleclient
node_tleclient -->|"requests TLE"| node_server
node_catalogclient -->|"requests catalog"| node_server
node_server -->|"dispatches API requests"| node_routes
node_routes -->|"reads and writes cache"| node_redis
node_routes -->|"fetches TLE data"| node_celestrak
node_routes -.->|"delegates satellite fetch"| node_fetcher

click node_main "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/main.js"
click node_renderer "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/core/renderer.js"
click node_scene "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/core/scene.js"
click node_controls "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/core/controls.js"
click node_earth "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/earth/earth.js"
click node_telemetry "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/ui/telemetry.js"
click node_manager "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/satellite/satelliteManager.js"
click node_marker "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/satellite/satelliteMarker.js"
click node_coordinates "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/math/latLonToVector3.js"
click node_orbit "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/satellite/orbitPrediction.js"
click node_updates "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/satellite/satelliteUpdate.js"
click node_tleclient "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/api/fetchTLE.js"
click node_catalogclient "https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/api/fetchTLECatalog.js"
click node_server "https://github.com/raihacks/satelliteorbit/blob/main/backend/server.js"
click node_routes "https://github.com/raihacks/satelliteorbit/blob/main/backend/satelliteRoute.js"
click node_fetcher "https://github.com/raihacks/satelliteorbit/blob/main/backend/fetchSatellites.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_telemetry,node_user toneBlue
class node_renderer,node_scene,node_controls,node_earth toneAmber
class node_manager,node_marker,node_coordinates,node_orbit,node_updates toneMint
class node_tleclient,node_catalogclient,node_server,node_routes,node_fetcher,node_redis toneRose
class node_celestrak,node_texture toneIndigo
```

## Components

### Viewer interaction

- [App workflow](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/main.js): `frontend/js/main.js`
- [Telemetry display](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/ui/telemetry.js): `frontend/js/ui/telemetry.js`

### 3D visualization

- [WebGL renderer](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/core/renderer.js): `frontend/js/core/renderer.js`
- [Scene setup](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/core/scene.js): `frontend/js/core/scene.js`
- [Camera controls](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/core/controls.js): `frontend/js/core/controls.js`
- [Earth globe](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/earth/earth.js): `frontend/js/earth/earth.js`

### Satellite tracking

- [Satellite manager](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/satellite/satelliteManager.js): `frontend/js/satellite/satelliteManager.js`
- [Satellite markers](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/satellite/satelliteMarker.js): `frontend/js/satellite/satelliteMarker.js`
- [Coordinate conversion](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/math/latLonToVector3.js): `frontend/js/math/latLonToVector3.js`
- [Orbit prediction](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/satellite/orbitPrediction.js): `frontend/js/satellite/orbitPrediction.js`
- [Satellite updates](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/satellite/satelliteUpdate.js): `frontend/js/satellite/satelliteUpdate.js`

### Data service

- [TLE client](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/api/fetchTLE.js): `frontend/js/api/fetchTLE.js`
- [Catalog client](https://github.com/raihacks/satelliteorbit/blob/main/frontend/js/api/fetchTLECatalog.js): `frontend/js/api/fetchTLECatalog.js`
- [Express server](https://github.com/raihacks/satelliteorbit/blob/main/backend/server.js): `backend/server.js`
- [Satellite routes](https://github.com/raihacks/satelliteorbit/blob/main/backend/satelliteRoute.js): `backend/satelliteRoute.js`
- [Satellite fetcher](https://github.com/raihacks/satelliteorbit/blob/main/backend/fetchSatellites.js): `backend/fetchSatellites.js`
- **TLE cache**

### Other components

- **Viewer**
- **Celestrak**
- **Earth texture**

## Connections

- Viewer → App workflow: interacts with
- App workflow → Scene setup: creates
- App workflow → WebGL renderer: creates
- App workflow → Camera controls: creates
- App workflow → Earth globe: creates
- App workflow → Satellite manager: manages
- App workflow → Telemetry display: updates
- App workflow → Express server: requests catalog or TLE
- Scene setup → Earth globe: hosts
- WebGL renderer → Scene setup: renders
- Camera controls → WebGL renderer: controls camera
- Earth globe → Earth texture: loads texture
- Satellite manager → Satellite markers: creates markers
- Satellite manager → Coordinate conversion: converts positions
- Satellite manager → Orbit prediction: predicts paths
- Satellite manager → Satellite updates: updates tracking
- Satellite manager → TLE client: fetches TLE
- TLE client → Express server: requests TLE
- Catalog client → Express server: requests catalog
- Express server → Satellite routes: dispatches API requests
- Satellite routes → TLE cache: reads and writes cache
- Satellite routes → Celestrak: fetches TLE data
- Satellite routes → Satellite fetcher: delegates satellite fetch