Starlink Lifecycle Research

Local-first web app for researching publicly obtainable Starlink satellite lifecycle, decay, and reentry information. The app is intentionally conservative: catalog dates, orbital history, expert references, aggregate explanations, computed values, and rule-based inferences are labeled separately.

Visible app disclaimer:

Public satellite-tracking data can usually show which satellite reentered and when. It generally does not provide a definitive public per-satellite internal reason for deorbit. This app distinguishes sourced facts from computed values and inferences.

.
├── backend/
│   ├── app/
│   │   ├── api/routes.py
│   │   ├── core/config.py
│   │   ├── db/init_db.py
│   │   ├── db/session.py
│   │   ├── ingestion/
│   │   ├── models/
│   │   ├── schemas/
│   │   └── services/
│   ├── scripts/init_db.py
│   ├── tests/
│   └── pyproject.toml
├── frontend/
│   ├── src/
│   │   ├── api/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── types/
│   │   └── utils/
│   ├── tests/
│   └── package.json
├── sample_data/seed_satellites.csv
├── Dockerfile
├── docker-compose.yml
├── Makefile
└── .env.example

1. Copy .env.example to .env.
2. Install dependencies:

make install

3. Initialize SQLite with sample data:

make init-db

4. Start the API and frontend in two terminals:

make backend
make frontend

Open http://localhost:5173.

With the backend running:

make ingest-starlink
make ingest-satcat

Or call:

• POST /api/ingest/celestrak/starlink
• POST /api/ingest/celestrak/satcat
• POST /api/ingest/planet4589
• POST /api/ingest/spacetrack

CelesTrak active Starlink GP uses https://celestrak.org/NORAD/elements/gp.php?GROUP=starlink&FORMAT=json. SATCAT uses https://celestrak.org/pub/satcat.csv.

Space-Track is optional. Register with Space-Track and set:

SPACE_TRACK_USERNAME=your_username
SPACE_TRACK_PASSWORD=your_password

Credentials are read from environment variables only. They are never hardcoded. The current importer logs in and fetches scoped Starlink SATCAT data conservatively; explicit field mapping should be reviewed before overwriting catalog records.

Use POST /api/import/csv/preview to validate a CSV, then POST /api/import/csv to import it. Supported columns include:

norad_cat_id, object_name, starlink_name, international_designator, launch_date, decay_date, object_type, operational_status, generation_or_variant, launch_group, source_name, source_url, notes.

Sample input is in sample_data/seed_satellites.csv.

• CSV: GET /api/export/satellites.csv
• Markdown report: GET /api/export/report.md

Exports include source counts and inference labels. Markdown reports include notes explaining FACT, AGGREGATE_EXPLANATION, COMPUTED, and INFERENCE.

• FACT: a stored source directly supports the claim.
• AGGREGATE_EXPLANATION: a source discusses a group, campaign, or reporting period. It is not automatically a proven cause for each satellite in that window.
• COMPUTED: derived from stored orbital elements, such as semimajor axis or altitude estimates.
• INFERENCE: generated by transparent rules. It must not be presented as a disclosed internal reason for deorbit unless direct evidence is linked.

• Public catalogs can establish identity, epoch/orbital history, launch date, decay date, and status, but usually not definitive per-satellite internal deorbit causes.
• CelesTrak active GP only covers active objects; historical orbital history requires archival sources such as Space-Track credentials or manual imports.
• Planet4589 page formats can change. The importer stores page metadata as expert-reference evidence and leaves detailed row extraction for review.
• The bundled seed data is synthetic and only demonstrates app behavior.

make test
make lint

Backend tests cover upsert logic, CelesTrak GP parsing, TLE parsing, date filters, post-election and reporting-period filters, inference safety, CSV export, Markdown export, and manual CSV import. Frontend tests cover satellite tables, query-param filters, fact/inference labels, timeline markers, and reliability labels.

make docker-up

Frontend: http://localhost:8080
API: http://localhost:8000

The public GitHub Pages site can be served directly from the repository root. The committed index.html, assets/, and static-data/ files are a read-only static build of the app.

This repository also includes .github/workflows/pages.yml for optional manual deployments through GitHub Actions. When run manually, GitHub Actions:

1. Installs the backend.
2. Fetches current public CelesTrak Starlink GP and SATCAT data.
3. Exports a read-only static snapshot into frontend/public/static-data.
4. Builds the React frontend with VITE_STATIC_DATA=true.
5. Deploys frontend/dist to GitHub Pages.

GitHub Pages cannot run FastAPI or SQLite, so the public Pages site is intentionally read-only. Search, filters, detail pages, timeline playback, reporting-period views, and exports work from the generated static data snapshot. Evidence editing and fresh ingestion still require running the app locally.

If you switch Pages to Source: GitHub Actions, run the workflow manually from the Actions tab. Otherwise, keep Pages on the branch-root source and update the committed static files when you want to publish a refreshed snapshot.