spb/satelliteindex

1# SatelliteIndex.io — project guide (condensed from the founding spec, see docs/SPEC-summary.md)23**Mission**: the definitive public intelligence layer for everything operating, launched, proposed, licensed, decaying or changing in4Earth orbit — Bloomberg Terminal × FlightRadar24 × Crunchbase for orbital infrastructure. Not a simple satellite tracker.56## Architecture (never couple the website to third-party sources)78```9External sources → connector workers → raw snapshots (SI_DATA_DIR/raw, gzip + raw_records) → normalization → entity resolution10→ canonical Postgres → derived analytics (matviews, stats_snapshots, search_index, events) → FastAPI /api/v1 → Next.js11```1213- **Backend** `src/satelliteindex/` (Python 3.12, FastAPI, SQLAlchemy Core + asyncpg, Alembic, sgp4, APScheduler, Redis).14  - `connectors/` framework (`BaseConnector.run()` = bookkeeping, hashing, circuit breaker; `execute()` per connector) — CelesTrak GP15    (`celestrak_gp`), CelesTrak groups (`celestrak_groups`), SATCAT (`celestrak_satcat`), `derived_analytics`. Registry: `connectors/__init__.py`.16  - `orbital/` SGP4 (vectorised `SatrecArray`), TEME→geodetic, orbit classification (documented metric `orbit_class`).17  - `services/` entity resolution (`SatIndex`, NORAD → COSPAR → name; never auto-merge ambiguous), classification (curated18    `registry/constellations.yaml`), positions service (in-memory propagator, 30 s cache), events (dedupe keys), Redis cache/locks.19  - `api/routers/` satellites, search, stats/rankings/density, orbit positions, constellations, operators, countries, launches/sites/debris/reentries,20    events, misc (sources, status, methodology, sitemap, view beacon), admin (`x-si-admin-token`).21  - CLI `si`: `migrate | seed | run <connector> [--file group=path] | status | stats | position <norad> | schedule | api | backup`.22- **Frontend** `apps/web/` (Next 16, Tailwind v4, Three/R3F globe). Guide: `docs/FRONTEND-GUIDE.md`.23- **Database**: `migrations/versions/0001_initial.py` (plain SQL). Internal ids are prefixed ULIDs (`sat_…`); NORAD/COSPAR are *source* identifiers.24  Orbital history is append-only (`orbital_elements`), `orbital_state` = latest per object. Materialized views refresh hourly.2526## Hard rules (from the spec)2728- No hardcoded satellite counts, source results, timestamps, fake analytics or placeholder charts. Missing → "Unavailable".29- Never overwrite orbital history, discard provenance, merge ambiguous satellites silently, or delete entities because a source went quiet30  (empty/short upstream responses are *suspicious*, not "no data").31- Never expose credentials (Space-Track, DB, Scrapfly…) or internal cluster addresses. Admin behind token. Rate limits on search/positions.32- Derived analytics (orbit class, mission type, constellation membership, activity score, orbital density) are labelled derived with a33  documented, versioned methodology (`metric_definitions`, `/methodology`). Never present them as safety metrics. Never invent collision34  probabilities or precise reentry locations.35- Mobile-first (390/430/768/1440), no horizontal overflow, ≥ 44 px targets, DOM order = visual order. Design: premium, scientific,36  dark, data-dense — no crypto-dashboard look, no wall of rounded cards.37- Units: km, km/s, kg, degrees, minutes, UTC. ISO 3166 country codes.38- Every feature: real data, error + loading states, mobile + desktop, source attribution, performance, accessibility, logging, tests, deployment.3940## Local development4142```43uv venv --python 3.12 .venv && uv pip install --python .venv/bin/python -e ".[dev]"   # backend deps44cp .env.example .env            # local Postgres `satelliteindex`, Redis db 445.venv/bin/si migrate && .venv/bin/si seed46.venv/bin/si run celestrak_satcat && .venv/bin/si run celestrak_gp && .venv/bin/si run celestrak_groups && .venv/bin/si run derived_analytics47.venv/bin/si api                # http://127.0.0.1:8311 (docs at /api/v1/docs)48pnpm install && pnpm dev:web    # http://localhost:831049pytest                          # tests/ (fixtures in tests/fixtures, no live network by default)50```5152CelesTrak blocks a second download of the same GP group within 2 h (HTTP 403 "has not updated") — the connector treats it as *unchanged*;53`si run celestrak_gp --file active=/path/active.json` ingests a local snapshot.5455## Production5657**Since 2026-09-14: OVH server BHS128b** (`ssh BHS128b`, Ubuntu 24.04), outside `mld`: PM2 under systemd (`~/apps/pm2.satelliteindex.config.cjs`,58generated from the mld manifest kept in `~/apps/.manifests/`) — `satelliteindex-api` (uvicorn 127.0.0.1:8311), `satelliteindex-scheduler`59(`si schedule`), `satelliteindex-web` (Next :8310). Postgres 17 + Redis native; code `~/apps/satelliteindex` (uv Python 3.12 venv), data in60`~/satelliteindex-data/`. Public route: MacLustr Tunnel (BHS64 Caddy) `https://www.satelliteindex.io → wg1 10.67.0.62:8310`, apex redirected.61Release = rsync + `uv pip install -e .` + `si migrate` + web build + `pm2 restart` (exact command in `docs/DEPLOY.md`).62Former home: M2M32b via `mld` (manifest `deploy/satelliteindex.mld.json`), kept as a cold copy.63