# 1nnamdi/orbitwatch architecture

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

- Interactive diagram: https://gitdiagram.com/1nnamdi/orbitwatch
- Repository: https://github.com/1nnamdi/orbitwatch

## Overview

OrbitWatch gathers satellite and launch data, stores catalog and history, analyzes orbital changes and decay, and presents tracking and domain dashboards. The main user workflow runs from the React app through its typed API client to FastAPI endpoints and PostgreSQL-backed results; satellite positions, tracks, and passes are also computed server-side, while the globe and detail panel propagate TLEs client-side. Scheduled ingestion and optional Space-Track enrichment form a separate data-entry path. Edges reflect README documentation and SOURCE INDEX references; unsampled endpoint behavior is represented at subsystem level.

Main entry points: [`frontend/src/App.tsx`](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/App.tsx) (App routing), [`frontend/src/api.ts`](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/api.ts) (Typed API client), [`backend/app/models.py`](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/models.py) (Domain records), [`backend/app/main.py`](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Data ingestion"]
  node_celestrak["CelesTrak ingestion<br/>[celestrak.py]"]
  node_launchlib["Launch Library ingestion<br/>[launchlibrary.py]"]
  node_spacetrack["Space-Track integration<br/>[spacetrack.py]"]
end

subgraph group_backend["Backend services"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_satapi["Satellite endpoints<br/>[satellites.py]"]
  node_domainapi["Domain endpoints"]
  node_propagation["Orbital propagation<br/>[propagation.py]"]
  node_maneuvers["Maneuver analysis<br/>[maneuvers.py]"]
  node_decay["Decay analysis<br/>[decay.py]"]
end

subgraph group_storage["Persistence"]
  node_dbsession["Database sessions<br/>[db.py]"]
  node_records["Domain records<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_frontend["User experience"]
  node_app["App routing<br/>[App.tsx]"]
  node_globe["3D globe<br/>[GlobePage.tsx]"]
  node_map["Ground track map<br/>[MapPage.tsx]"]
  node_passes["Pass predictions<br/>[PassesPage.tsx]"]
  node_events["Events dashboard<br/>[EventsPage.tsx]"]
  node_launches["Launch tracker<br/>[LaunchesPage.tsx]"]
  node_reentries["Re-entry dashboard<br/>[ReentryPage.tsx]"]
  node_constellations["Constellation views"]
  node_satdetails["Satellite details<br/>[SatDetails.tsx]"]
  node_search["Satellite search"]
  node_clientapi["Typed API client<br/>[api.ts]"]
end

node_user(("OrbitWatch user"))
node_externaldata(("Public data sources"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_globe
node_app -->|"routes to"| node_map
node_app -->|"routes to"| node_passes
node_app -->|"routes to"| node_events
node_app -->|"routes to"| node_launches
node_app -->|"routes to"| node_reentries
node_app -->|"routes to"| node_constellations
node_app -->|"fetches stats"| node_clientapi
node_globe -->|"requests data"| node_clientapi
node_map -->|"requests data"| node_clientapi
node_passes -->|"requests data"| node_clientapi
node_events -->|"requests data"| node_clientapi
node_launches -->|"requests data"| node_clientapi
node_reentries -->|"requests data"| node_clientapi
node_constellations -->|"requests data"| node_clientapi
node_globe -->|"renders"| node_search
node_globe -->|"renders"| node_satdetails
node_map -->|"renders"| node_search
node_map -->|"renders"| node_satdetails
node_search -->|"searches via"| node_clientapi
node_clientapi -->|"calls API"| node_domainapi
node_fastapi -->|"registers router"| node_satapi
node_fastapi -->|"registers routers"| node_domainapi
node_satapi -->|"uses"| node_propagation
node_domainapi -->|"uses"| node_maneuvers
node_domainapi -->|"uses"| node_decay
node_fastapi -->|"schedules ingestion"| node_celestrak
node_fastapi -->|"schedules ingestion"| node_launchlib
node_fastapi -->|"schedules ingestion"| node_spacetrack
node_fastapi -->|"schedules analysis"| node_maneuvers
node_externaldata -->|"provides TLEs"| node_celestrak
node_celestrak -->|"stores satellite TLEs"| node_records
node_launchlib -.->|"stores launches"| node_records
node_spacetrack -->|"stores catalog and history"| node_records
node_maneuvers -->|"reads and writes events"| node_records
node_decay -->|"analyzes orbital history"| node_records
node_satapi -->|"queries catalog"| node_records
node_domainapi -->|"queries domain data"| node_records
node_dbsession -->|"provides ORM base"| node_records
node_dbsession -->|"connects"| node_postgres

click node_app "https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/App.tsx"
click node_globe "https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/GlobePage.tsx"
click node_map "https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/MapPage.tsx"
click node_passes "https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/PassesPage.tsx"
click node_events "https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/EventsPage.tsx"
click node_launches "https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/LaunchesPage.tsx"
click node_reentries "https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/ReentryPage.tsx"
click node_constellations "https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/ConstellationsPage.tsx"
click node_satdetails "https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/components/SatDetails.tsx"
click node_search "https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/components/SatelliteSearch.tsx"
click node_clientapi "https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/api.ts"
click node_fastapi "https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/main.py"
click node_satapi "https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/api/satellites.py"
click node_domainapi "https://github.com/1nnamdi/orbitwatch/tree/master/backend/app/api"
click node_propagation "https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/services/propagation.py"
click node_maneuvers "https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/services/maneuvers.py"
click node_decay "https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/services/decay.py"
click node_celestrak "https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/sources/celestrak.py"
click node_launchlib "https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/sources/launchlibrary.py"
click node_spacetrack "https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/sources/spacetrack.py"
click node_dbsession "https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/db.py"
click node_records "https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/models.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_celestrak,node_launchlib,node_spacetrack,node_user toneBlue
class node_fastapi,node_satapi,node_domainapi,node_propagation,node_maneuvers,node_decay toneAmber
class node_dbsession,node_records,node_postgres toneMint
class node_app,node_globe,node_map,node_passes,node_events,node_launches,node_reentries,node_constellations,node_satdetails,node_search,node_clientapi toneRose
class node_externaldata toneIndigo
```

## Components

### Data ingestion

- [CelesTrak ingestion](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/sources/celestrak.py): `backend/app/sources/celestrak.py`
- [Launch Library ingestion](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/sources/launchlibrary.py): `backend/app/sources/launchlibrary.py`
- [Space-Track integration](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/sources/spacetrack.py): `backend/app/sources/spacetrack.py`

### Backend services

- [FastAPI app](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/main.py): `backend/app/main.py`
- [Satellite endpoints](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/api/satellites.py): `backend/app/api/satellites.py`
- [Domain endpoints](https://github.com/1nnamdi/orbitwatch/tree/master/backend/app/api): `backend/app/api`
- [Orbital propagation](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/services/propagation.py): `backend/app/services/propagation.py`
- [Maneuver analysis](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/services/maneuvers.py): `backend/app/services/maneuvers.py`
- [Decay analysis](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/services/decay.py): `backend/app/services/decay.py`

### Persistence

- [Database sessions](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/db.py): `backend/app/db.py`
- [Domain records](https://github.com/1nnamdi/orbitwatch/blob/master/backend/app/models.py): `backend/app/models.py`
- **PostgreSQL**

### User experience

- [App routing](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [3D globe](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/GlobePage.tsx): `frontend/src/pages/GlobePage.tsx`
- [Ground track map](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/MapPage.tsx): `frontend/src/pages/MapPage.tsx`
- [Pass predictions](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/PassesPage.tsx): `frontend/src/pages/PassesPage.tsx`
- [Events dashboard](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/EventsPage.tsx): `frontend/src/pages/EventsPage.tsx`
- [Launch tracker](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/LaunchesPage.tsx): `frontend/src/pages/LaunchesPage.tsx`
- [Re-entry dashboard](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/ReentryPage.tsx): `frontend/src/pages/ReentryPage.tsx`
- [Constellation views](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/pages/ConstellationsPage.tsx): `frontend/src/pages/ConstellationsPage.tsx`
- [Satellite details](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/components/SatDetails.tsx): `frontend/src/components/SatDetails.tsx`
- [Satellite search](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/components/SatelliteSearch.tsx): `frontend/src/components/SatelliteSearch.tsx`
- [Typed API client](https://github.com/1nnamdi/orbitwatch/blob/master/frontend/src/api.ts): `frontend/src/api.ts`

### Other components

- **OrbitWatch user**
- **Public data sources**

## Connections

- OrbitWatch user → App routing: uses (evidence: `frontend/src/App.tsx`)
- App routing → 3D globe: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Ground track map: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Pass predictions: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Events dashboard: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Launch tracker: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Re-entry dashboard: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Constellation views: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Typed API client: fetches stats (evidence: `frontend/src/App.tsx`)
- 3D globe → Typed API client: requests data (evidence: `frontend/src/pages/GlobePage.tsx`)
- Ground track map → Typed API client: requests data (evidence: `frontend/src/pages/MapPage.tsx`)
- Pass predictions → Typed API client: requests data (evidence: `frontend/src/pages/PassesPage.tsx`)
- Events dashboard → Typed API client: requests data (evidence: `frontend/src/pages/EventsPage.tsx`)
- Launch tracker → Typed API client: requests data (evidence: `frontend/src/pages/LaunchesPage.tsx`)
- Re-entry dashboard → Typed API client: requests data (evidence: `frontend/src/pages/ReentryPage.tsx`)
- Constellation views → Typed API client: requests data (evidence: `frontend/src/pages/ConstellationsPage.tsx`)
- 3D globe → Satellite search: renders (evidence: `frontend/src/pages/GlobePage.tsx`)
- 3D globe → Satellite details: renders (evidence: `frontend/src/pages/GlobePage.tsx`)
- Ground track map → Satellite search: renders (evidence: `frontend/src/pages/MapPage.tsx`)
- Ground track map → Satellite details: renders (evidence: `frontend/src/pages/MapPage.tsx`)
- Satellite search → Typed API client: searches via (evidence: `frontend/src/components/SatelliteSearch.tsx`)
- Typed API client → Domain endpoints: calls API (evidence: `frontend/src/api.ts`)
- FastAPI app → Satellite endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI app → Domain endpoints: registers routers (evidence: `backend/app/main.py`)
- Satellite endpoints → Orbital propagation: uses (evidence: `backend/app/api/satellites.py`)
- Domain endpoints → Maneuver analysis: uses (evidence: `backend/app/api/events.py`)
- Domain endpoints → Decay analysis: uses (evidence: `backend/app/api/reentries.py`)
- FastAPI app → CelesTrak ingestion: schedules ingestion (evidence: `backend/app/main.py`)
- FastAPI app → Launch Library ingestion: schedules ingestion (evidence: `backend/app/main.py`)
- FastAPI app → Space-Track integration: schedules ingestion (evidence: `backend/app/main.py`)
- FastAPI app → Maneuver analysis: schedules analysis (evidence: `backend/app/main.py`)
- Public data sources → CelesTrak ingestion: provides TLEs (evidence: `README.md`)
- CelesTrak ingestion → Domain records: stores satellite TLEs (evidence: `backend/app/sources/celestrak.py`)
- Launch Library ingestion → Domain records: stores launches (evidence: `backend/app/sources/launchlibrary.py`)
- Space-Track integration → Domain records: stores catalog and history (evidence: `backend/app/sources/spacetrack.py`)
- Maneuver analysis → Domain records: reads and writes events (evidence: `backend/app/services/maneuvers.py`)
- Decay analysis → Domain records: analyzes orbital history (evidence: `backend/app/services/decay.py`)
- Satellite endpoints → Domain records: queries catalog (evidence: `backend/app/api/satellites.py`)
- Domain endpoints → Domain records: queries domain data (evidence: `backend/app/api/launches.py`)
- Database sessions → Domain records: provides ORM base (evidence: `backend/app/models.py`)
- Database sessions → PostgreSQL: connects (evidence: `backend/app/db.py`)
