spb/satelliteindex

1# SatelliteIndex.io — project guide (condensed from the founding spec, see docs/SPEC-summary.md)23> ⚠️ **PRODUCTION RETIRÉE LE 2026-10-02.** Le serveur OVH qui hébergeait cette app a été retiré du MacLustr (résiliation OVH ; seule la passerelle BHS64 est conservée). Plus aucune instance ne tourne, le site public ne répond plus et la route MacLustr Tunnel a été supprimée. Code final = ce dépôt (spbgit, branche `main`). Sauvegardes à froid : dumps Postgres + état sur **M3U96b:~/ovh-retired-20261002/**, manifestes/secrets/PM2 sur le laptop `~/Desktop/Cluster/secrets/ovh-retired-20261002/` (0600). Les procédures de déploiement ci-dessous sont historiques.45**Mission**: the definitive public intelligence layer for everything operating, launched, proposed, licensed, decaying or changing in6Earth orbit — Bloomberg Terminal × FlightRadar24 × Crunchbase for orbital infrastructure. Not a simple satellite tracker.78## Architecture (never couple the website to third-party sources)910```11External sources → connector workers → raw snapshots (SI_DATA_DIR/raw, gzip + raw_records) → normalization → entity resolution12→ canonical Postgres → derived analytics (matviews, stats_snapshots, search_index, events) → FastAPI /api/v1 → Next.js13```1415- **Backend** `src/satelliteindex/` (Python 3.12, FastAPI, SQLAlchemy Core + asyncpg, Alembic, sgp4, APScheduler, Redis).16  - `connectors/` framework (`BaseConnector.run()` = bookkeeping, hashing, circuit breaker; `execute()` per connector) — CelesTrak GP17    (`celestrak_gp`), CelesTrak groups (`celestrak_groups`), SATCAT (`celestrak_satcat`), `derived_analytics`. Registry: `connectors/__init__.py`.18  - `orbital/` SGP4 (vectorised `SatrecArray`), TEME→geodetic, orbit classification (documented metric `orbit_class`).19  - `services/` entity resolution (`SatIndex`, NORAD → COSPAR → name; never auto-merge ambiguous), classification (curated20    `registry/constellations.yaml`), positions service (in-memory propagator, 30 s cache), events (dedupe keys), Redis cache/locks.21  - `api/routers/` satellites, search, stats/rankings/density, orbit positions, constellations, operators, countries, launches/sites/debris/reentries,22    events, misc (sources, status, methodology, sitemap, view beacon), admin (`x-si-admin-token`).23  - CLI `si`: `migrate | seed | run <connector> [--file group=path] | status | stats | position <norad> | schedule | api | backup`.24- **Frontend** `apps/web/` (Next 16, Tailwind v4, Three/R3F globe). Guide: `docs/FRONTEND-GUIDE.md`.25- **Database**: `migrations/versions/0001_initial.py` (plain SQL). Internal ids are prefixed ULIDs (`sat_…`); NORAD/COSPAR are *source* identifiers.26  Orbital history is append-only (`orbital_elements`), `orbital_state` = latest per object. Materialized views refresh hourly.2728## Hard rules (from the spec)2930- No hardcoded satellite counts, source results, timestamps, fake analytics or placeholder charts. Missing → "Unavailable".31- Never overwrite orbital history, discard provenance, merge ambiguous satellites silently, or delete entities because a source went quiet32  (empty/short upstream responses are *suspicious*, not "no data").33- Never expose credentials (Space-Track, DB, Scrapfly…) or internal cluster addresses. Admin behind token. Rate limits on search/positions.34- Derived analytics (orbit class, mission type, constellation membership, activity score, orbital density) are labelled derived with a35  documented, versioned methodology (`metric_definitions`, `/methodology`). Never present them as safety metrics. Never invent collision36  probabilities or precise reentry locations.37- Mobile-first (390/430/768/1440), no horizontal overflow, ≥ 44 px targets, DOM order = visual order. Design: premium, scientific,38  dark, data-dense — no crypto-dashboard look, no wall of rounded cards.39- Units: km, km/s, kg, degrees, minutes, UTC. ISO 3166 country codes.40- Every feature: real data, error + loading states, mobile + desktop, source attribution, performance, accessibility, logging, tests, deployment.4142## Local development4344```45uv venv --python 3.12 .venv && uv pip install --python .venv/bin/python -e ".[dev]"   # backend deps46cp .env.example .env            # local Postgres `satelliteindex`, Redis db 447.venv/bin/si migrate && .venv/bin/si seed48.venv/bin/si run celestrak_satcat && .venv/bin/si run celestrak_gp && .venv/bin/si run celestrak_groups && .venv/bin/si run derived_analytics49.venv/bin/si api                # http://127.0.0.1:8311 (docs at /api/v1/docs)50pnpm install && pnpm dev:web    # http://localhost:831051pytest                          # tests/ (fixtures in tests/fixtures, no live network by default)52```5354CelesTrak blocks a second download of the same GP group within 2 h (HTTP 403 "has not updated") — the connector treats it as *unchanged*;55`si run celestrak_gp --file active=/path/active.json` ingests a local snapshot.5657## Production5859**Since 2026-09-14: OVH server BHS128b** (`ssh BHS128b`, Ubuntu 24.04), outside `mld`: PM2 under systemd (`~/apps/pm2.satelliteindex.config.cjs`,60generated from the mld manifest kept in `~/apps/.manifests/`) — `satelliteindex-api` (uvicorn 127.0.0.1:8311), `satelliteindex-scheduler`61(`si schedule`), `satelliteindex-web` (Next :8310). Postgres 17 + Redis native; code `~/apps/satelliteindex` (uv Python 3.12 venv), data in62`~/satelliteindex-data/`. Public route: MacLustr Tunnel (BHS64 Caddy) `https://www.satelliteindex.io → wg1 10.67.0.62:8310`, apex redirected.63Release = rsync + `uv pip install -e .` + `si migrate` + web build + `pm2 restart` (exact command in `docs/DEPLOY.md`).64Former home: M2M32b via `mld` (manifest `deploy/satelliteindex.mld.json`), kept as a cold copy.65