# samenthamassey127-hue/orbitly architecture

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

- Interactive diagram: https://gitdiagram.com/samenthamassey127-hue/orbitly
- Repository: https://github.com/samenthamassey127-hue/orbitly

## Overview

ORBITLY is a space-intelligence web platform: users search or select satellites, retrieve normalized telemetry and propagated orbit data, and explore it on a 3D globe; they can also use launch, learning, dashboard, and assistant features. The backend separates HTTP routing from catalog, orbital, and explanation logic. The README documents the live CelesTrak-to-SGP4 path; unsampled feature implementations are represented at their service paths, with only documented or indexed relationships shown.

Main entry points: [`frontend/src/App.tsx`](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/App.tsx) (Orbitly interface), [`backend/main.py`](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/main.py) (FastAPI application), [`frontend/src/api/client.ts`](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/api/client.ts) (API client), [`backend/services/satellite_service.py`](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/satellite_service.py) (Satellite catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Orbitly interface<br/>[App.tsx]"]
  node_client["API client<br/>[client.ts]"]
  node_hooks["Satellite workflows<br/>[useSatellites.ts]"]
  node_state["UI state<br/>[orbitly.ts]"]
  node_globe["3D globe<br/>[Globe3D.tsx]"]
  node_searchui["Satellite search<br/>[SearchBar.tsx]"]
  node_panel["Satellite details<br/>[SatellitePanel.tsx]"]
  node_launchui["Launch tracker<br/>[LaunchTracker.tsx]"]
  node_conceptui["Concept visualizer"]
  node_dashboardui["Role dashboard"]
  node_assistantui["Ask ORBITLY"]
end

subgraph group_api["API surface"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_satroute["Satellite routes<br/>[satellites.py]"]
  node_searchroute["Search route<br/>[search.py]"]
  node_launchroute["Launch route<br/>[launches.py]"]
  node_conroute["Concept route<br/>[concepts.py]"]
  node_dashroute["Dashboard route<br/>[dashboard.py]"]
  node_assroute["Assistant route<br/>[assistant.py]"]
end

subgraph group_sat["Satellite intelligence"]
  node_catalog["Satellite catalog"]
  node_provider["CelesTrak provider<br/>[celestrak.py]"]
  node_orbital["Orbital propagation<br/>[orbital_service.py]"]
  node_explain["Telemetry explanations"]
  node_cache[("Catalog cache<br/>[cache_service.py]")]
  node_models["Satellite models<br/>[satellite.py]"]
end

subgraph group_features["Space features"]
  node_launchsvc["Launch schedules<br/>[launch_service.py]"]
  node_conceptsvc["Space concepts<br/>[concept_service.py]"]
  node_dashsvc["Personalized content"]
  node_assist["Assistant reasoning"]
  node_featuremodels["Feature models<br/>[features.py]"]
end

node_user(("Space explorer"))
node_celestrak{{"CelesTrak GP API"}}
node_gemini{{"Google Gemini"}}

node_user -->|"explores"| node_app
node_app -->|"renders"| node_searchui
node_app -->|"renders"| node_launchui
node_app -->|"renders"| node_conceptui
node_app -->|"renders"| node_dashboardui
node_app -->|"renders"| node_panel
node_app -->|"renders"| node_globe
node_app -.->|"renders"| node_assistantui
node_searchui -->|"searches through"| node_hooks
node_hooks -->|"requests"| node_client
node_hooks -->|"updates"| node_state
node_globe -->|"reads view state"| node_state
node_launchui -->|"loads launches"| node_client
node_conceptui -->|"loads concepts"| node_client
node_dashboardui -->|"loads role data"| node_client
node_assistantui -->|"asks questions"| node_client
node_client -->|"HTTP requests"| node_backend
node_backend -->|"registers"| node_satroute
node_backend -->|"registers"| node_searchroute
node_backend -->|"registers"| node_launchroute
node_backend -->|"registers"| node_conroute
node_backend -->|"registers"| node_dashroute
node_backend -->|"registers"| node_assroute
node_satroute -->|"calls"| node_catalog
node_satroute -->|"calls"| node_orbital
node_satroute -->|"calls"| node_explain
node_searchroute -->|"searches"| node_catalog
node_launchroute -->|"calls"| node_launchsvc
node_conroute -->|"calls"| node_conceptsvc
node_dashroute -->|"calls"| node_dashsvc
node_assroute -->|"calls"| node_assist
node_catalog -->|"loads catalog"| node_provider
node_catalog -->|"reads and writes"| node_cache
node_provider -->|"fetches TLE data"| node_celestrak
node_provider -->|"normalizes records"| node_models
node_orbital -->|"computes satellite state"| node_models
node_explain -.->|"requests AI summary"| node_gemini
node_launchsvc -->|"returns launch data"| node_featuremodels
node_conceptsvc -->|"returns concepts"| node_featuremodels
node_dashsvc -->|"returns dashboards"| node_featuremodels
node_assist -->|"looks up satellite"| node_catalog
node_assist -->|"queries model"| node_gemini
node_assist -->|"builds response"| node_featuremodels

click node_app "https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/App.tsx"
click node_client "https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/api/client.ts"
click node_hooks "https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/hooks/useSatellites.ts"
click node_state "https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/store/orbitly.ts"
click node_globe "https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/Globe3D.tsx"
click node_searchui "https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/SearchBar.tsx"
click node_panel "https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/SatellitePanel.tsx"
click node_launchui "https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/LaunchTracker.tsx"
click node_conceptui "https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/ConceptVisualizer.tsx"
click node_dashboardui "https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/PersonalizedDashboard.tsx"
click node_assistantui "https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/AskOrbitlyAssistant.tsx"
click node_backend "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/main.py"
click node_satroute "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/satellites.py"
click node_searchroute "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/search.py"
click node_launchroute "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/launches.py"
click node_conroute "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/concepts.py"
click node_dashroute "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/dashboard.py"
click node_assroute "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/assistant.py"
click node_catalog "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/satellite_service.py"
click node_provider "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/providers/celestrak.py"
click node_orbital "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/orbital_service.py"
click node_explain "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/explanation_service.py"
click node_cache "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/cache_service.py"
click node_models "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/models/satellite.py"
click node_launchsvc "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/launch_service.py"
click node_conceptsvc "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/concept_service.py"
click node_dashsvc "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/dashboard_service.py"
click node_assist "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/assistant_service.py"
click node_featuremodels "https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/models/features.py"

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_app,node_client,node_hooks,node_state,node_globe,node_searchui,node_panel,node_launchui,node_conceptui,node_dashboardui,node_assistantui toneBlue
class node_backend,node_satroute,node_searchroute,node_launchroute,node_conroute,node_dashroute,node_assroute toneAmber
class node_catalog,node_provider,node_orbital,node_explain,node_cache,node_models,node_celestrak toneMint
class node_launchsvc,node_conceptsvc,node_dashsvc,node_assist,node_featuremodels toneRose
class node_user,node_gemini toneIndigo
```

## Components

### Web experience

- [Orbitly interface](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Satellite workflows](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/hooks/useSatellites.ts): `frontend/src/hooks/useSatellites.ts`
- [UI state](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/store/orbitly.ts): `frontend/src/store/orbitly.ts`
- [3D globe](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/Globe3D.tsx): `frontend/src/components/Globe3D.tsx`
- [Satellite search](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/SearchBar.tsx): `frontend/src/components/SearchBar.tsx`
- [Satellite details](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/SatellitePanel.tsx): `frontend/src/components/SatellitePanel.tsx`
- [Launch tracker](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/LaunchTracker.tsx): `frontend/src/components/LaunchTracker.tsx`
- [Concept visualizer](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/ConceptVisualizer.tsx): `frontend/src/components/ConceptVisualizer.tsx`
- [Role dashboard](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/PersonalizedDashboard.tsx): `frontend/src/components/PersonalizedDashboard.tsx`
- [Ask ORBITLY](https://github.com/samenthamassey127-hue/orbitly/blob/main/frontend/src/components/AskOrbitlyAssistant.tsx): `frontend/src/components/AskOrbitlyAssistant.tsx`

### API surface

- [FastAPI application](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/main.py): `backend/main.py`
- [Satellite routes](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/satellites.py): `backend/routers/satellites.py`
- [Search route](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/search.py): `backend/routers/search.py`
- [Launch route](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/launches.py): `backend/routers/launches.py`
- [Concept route](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/concepts.py): `backend/routers/concepts.py`
- [Dashboard route](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/dashboard.py): `backend/routers/dashboard.py`
- [Assistant route](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/routers/assistant.py): `backend/routers/assistant.py`

### Satellite intelligence

- [Satellite catalog](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/satellite_service.py): `backend/services/satellite_service.py`
- [CelesTrak provider](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/providers/celestrak.py): `backend/providers/celestrak.py`
- [Orbital propagation](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/orbital_service.py): `backend/services/orbital_service.py`
- [Telemetry explanations](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/explanation_service.py): `backend/services/explanation_service.py`
- [Catalog cache](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/cache_service.py): `backend/services/cache_service.py`
- [Satellite models](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/models/satellite.py): `backend/models/satellite.py`

### Space features

- [Launch schedules](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/launch_service.py): `backend/services/launch_service.py`
- [Space concepts](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/concept_service.py): `backend/services/concept_service.py`
- [Personalized content](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/dashboard_service.py): `backend/services/dashboard_service.py`
- [Assistant reasoning](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/services/assistant_service.py): `backend/services/assistant_service.py`
- [Feature models](https://github.com/samenthamassey127-hue/orbitly/blob/main/backend/models/features.py): `backend/models/features.py`

### Other components

- **Space explorer**
- **CelesTrak GP API**
- **Google Gemini**

## Connections

- Space explorer → Orbitly interface: explores (evidence: `README.md`)
- Orbitly interface → Satellite search: renders (evidence: `frontend/src/App.tsx`)
- Orbitly interface → Launch tracker: renders (evidence: `frontend/src/App.tsx`)
- Orbitly interface → Concept visualizer: renders (evidence: `frontend/src/App.tsx`)
- Orbitly interface → Role dashboard: renders (evidence: `frontend/src/App.tsx`)
- Orbitly interface → Satellite details: renders (evidence: `frontend/src/App.tsx`)
- Orbitly interface → 3D globe: renders (evidence: `frontend/src/App.tsx`)
- Orbitly interface → Ask ORBITLY: renders (evidence: `frontend/src/App.tsx`)
- Satellite search → Satellite workflows: searches through (evidence: `frontend/src/components/SearchBar.tsx`)
- Satellite workflows → API client: requests (evidence: `frontend/src/hooks/useSatellites.ts`)
- Satellite workflows → UI state: updates (evidence: `frontend/src/hooks/useSatellites.ts`)
- 3D globe → UI state: reads view state (evidence: `frontend/src/components/Globe3D.tsx`)
- Launch tracker → API client: loads launches (evidence: `frontend/src/components/LaunchTracker.tsx`)
- Concept visualizer → API client: loads concepts (evidence: `frontend/src/components/ConceptVisualizer.tsx`)
- Role dashboard → API client: loads role data (evidence: `frontend/src/components/PersonalizedDashboard.tsx`)
- Ask ORBITLY → API client: asks questions (evidence: `frontend/src/components/AskOrbitlyAssistant.tsx`)
- API client → FastAPI application: HTTP requests (evidence: `frontend/src/api/client.ts`)
- FastAPI application → Satellite routes: registers (evidence: `backend/main.py`)
- FastAPI application → Search route: registers (evidence: `backend/main.py`)
- FastAPI application → Launch route: registers (evidence: `backend/main.py`)
- FastAPI application → Concept route: registers (evidence: `backend/main.py`)
- FastAPI application → Dashboard route: registers (evidence: `backend/main.py`)
- FastAPI application → Assistant route: registers (evidence: `backend/main.py`)
- Satellite routes → Satellite catalog: calls (evidence: `backend/routers/satellites.py`)
- Satellite routes → Orbital propagation: calls (evidence: `backend/routers/satellites.py`)
- Satellite routes → Telemetry explanations: calls (evidence: `backend/routers/satellites.py`)
- Search route → Satellite catalog: searches (evidence: `backend/routers/search.py`)
- Launch route → Launch schedules: calls (evidence: `backend/routers/launches.py`)
- Concept route → Space concepts: calls (evidence: `backend/routers/concepts.py`)
- Dashboard route → Personalized content: calls (evidence: `backend/routers/dashboard.py`)
- Assistant route → Assistant reasoning: calls (evidence: `backend/routers/assistant.py`)
- Satellite catalog → CelesTrak provider: loads catalog (evidence: `backend/services/satellite_service.py`)
- Satellite catalog → Catalog cache: reads and writes (evidence: `backend/services/satellite_service.py`)
- CelesTrak provider → CelesTrak GP API: fetches TLE data (evidence: `README.md`)
- CelesTrak provider → Satellite models: normalizes records (evidence: `backend/providers/celestrak.py`)
- Orbital propagation → Satellite models: computes satellite state (evidence: `backend/services/orbital_service.py`)
- Telemetry explanations → Google Gemini: requests AI summary (evidence: `README.md`)
- Launch schedules → Feature models: returns launch data (evidence: `backend/routers/launches.py`)
- Space concepts → Feature models: returns concepts (evidence: `backend/routers/concepts.py`)
- Personalized content → Feature models: returns dashboards (evidence: `backend/routers/dashboard.py`)
- Assistant reasoning → Satellite catalog: looks up satellite (evidence: `backend/services/assistant_service.py`)
- Assistant reasoning → Google Gemini: queries model (evidence: `backend/services/assistant_service.py`)
- Assistant reasoning → Feature models: builds response (evidence: `backend/services/assistant_service.py`)
