mirror of
https://github.com/koala73/worldmonitor.git
synced 2026-04-25 17:14:57 +02:00
09a582e089
* fix(docs): correct variant count from 4 to 5 Updated overview.mdx and architecture.mdx to reflect all 5 platform variants (World Monitor, Tech Monitor, Happy Monitor, Finance Monitor, Commodity Monitor). Previously only 2 were listed in the table and the text said "four". * fix(docs): correct all numerical inaccuracies across documentation Updated counts verified against actual codebase: - AI datacenters: 111 → 313 - Undersea cables: 55 → 86 - Map layers: 45 → 49 - News sources: 80+ → 344 - Service domains: 22 → 24 - CII countries: 20 → 24 - Military bases: 210/220+ → 226 - Strategic ports: 61/83 → 62 - Airports: 30/107 → 111 - Chokepoints: 6/8 → 9 - Signal entities: 100+/600+ → 66 - Variant count: four → five (added Commodity Monitor) * docs(overview): add Happy, Finance, and Commodity Monitor sections Added detailed documentation sections for the three previously undocumented platform variants, including layers, panels, and news categories for each. * docs(features): document 13 previously undocumented features Added: trade routes, FIRMS fire detection, webcam surveillance, country brief, aviation intelligence panel, climate anomalies, displacement tracking, Gulf economies, WTO trade policy, central banks & BIS, market watchlist, NOTAM closure detection, and offline ML capabilities. * docs: standardize terminology, add cross-references, fix stale refs Phase 4: Renamed "News Importance Scoring" to "Headline Scoring", "Signal Correlation" to "Cross-Stream Correlation". Added cross-refs between CII/convergence, CORS/API-key, maritime/finance chokepoints. Deduplicated Population Exposure content. Clarified hotspot vs focal point distinction. Phase 5: Rewrote daily_stock_analysis as historical context. Added legacy note for api/*.js files. Added OREF 24h rolling history boost and GPS jamming classification thresholds to algorithms.mdx. Fixed orbital-surveillance tier table contradictions. Phase 6: Fixed orphaned markdown separator in orbital-surveillance. * fix(docs): catch remaining stale numbers in secondary doc files Fixed stale counts in data-sources.mdx, strategic-risk.mdx, documentation.mdx, ai-intelligence.mdx, PRESS_KIT.md, and roadmap-pro.md that were missed in the initial pass. * fix(docs): address review findings from fresh-eyes pass - desktop-app.mdx: "four variants" → "five", "22 services" → "24" - infrastructure-cascade.mdx: chokepoints 8 → 9, node total 279 → 350 - data-sources.mdx: chokepoints 8 → 9 - overview.mdx: remove duplicated intro sentence - getting-started.mdx: fix stale file tree comments (AI clusters, airports, entities)
186 lines
7.9 KiB
Plaintext
186 lines
7.9 KiB
Plaintext
---
|
||
title: "Orbital Surveillance"
|
||
description: "Real-time satellite orbital tracking on the 3D globe, powered by SGP4 propagation from CelesTrak TLE data."
|
||
---
|
||
|
||
## Overview
|
||
|
||
The Orbital Surveillance layer tracks ~80–120 intelligence-relevant satellites in real time. Satellites are rendered at their actual orbital altitude on the globe with country-coded colors, orbit trails, and ground footprint projections.
|
||
|
||
**Globe-only** — orbital mechanics don't translate meaningfully to a flat map projection.
|
||
|
||
### What It Shows
|
||
|
||
| Element | Description |
|
||
|---------|-------------|
|
||
| **Satellite marker** | 4px glowing dot at actual orbital altitude (LEO ~400km, SSO ~600–900km) |
|
||
| **Country color** | CN = red, RU = orange, US = blue, EU = green, KR = purple, OTHER = grey |
|
||
| **Orbit trail** | 15-minute historical trace rendered as a dashed path at orbital altitude |
|
||
| **Ground footprint** | Translucent circle projected on the surface below each satellite (nadir point) |
|
||
| **Tooltip** | Name, country, sensor type (SAR Imaging / Optical Imaging / Military / SIGINT), altitude |
|
||
|
||
---
|
||
|
||
## Architecture
|
||
|
||
### Data Flow
|
||
|
||
```
|
||
CelesTrak (free) ──2h──▶ Railway relay ──Redis──▶ Vercel edge ──CDN 1h──▶ Browser
|
||
(TLE parse, (read-only, (SGP4 propagation
|
||
filter, 10min cache) every 3 seconds)
|
||
classify)
|
||
```
|
||
|
||
### Cost Model
|
||
|
||
| Component | Cost | Notes |
|
||
|-----------|------|-------|
|
||
| CelesTrak API | Free | Public NORAD TLE data, 2h update cycle |
|
||
| Railway relay | ~$0 | Seed loop runs inside existing `ais-relay.cjs` process |
|
||
| Redis (Upstash) | Negligible | Single key, 4h TTL, ~50KB payload |
|
||
| Vercel edge | ~$0 | CDN caches 1h (`s-maxage=3600`), stale-while-revalidate 30min |
|
||
| Browser CPU | Client-side | SGP4 math runs locally every 3s — zero server cost for real-time movement |
|
||
|
||
**Key insight**: TLE data changes slowly (every 2h), but satellite positions change every second. By shipping TLEs to the browser and doing SGP4 propagation client-side, we get real-time movement with zero ongoing server cost.
|
||
|
||
---
|
||
|
||
## Satellite Selection
|
||
|
||
Two CelesTrak groups are fetched: `military` (~21 sats) and `resource` (~164 sats). After deduplication and name-pattern filtering, ~80–120 intelligence-relevant satellites remain.
|
||
|
||
### Filter Patterns
|
||
|
||
| Category | Patterns | Type Classification |
|
||
|----------|----------|---------------------|
|
||
| **Chinese recon** | YAOGAN, GAOFEN, JILIN | SAR (YAOGAN), Optical |
|
||
| **Russian recon** | COSMOS 24xx/25xx | Military |
|
||
| **Commercial SAR** | COSMO-SKYMED, TERRASAR, PAZ, SAR-LUPE, ICEYE | SAR |
|
||
| **Commercial optical** | WORLDVIEW, SKYSAT, PLEIADES, KOMPSAT | Optical |
|
||
| **Military** | SAPPHIRE, PRAETORIAN | Military |
|
||
| **EU/civil** | SENTINEL | SAR (Sentinel-1), Optical (Sentinel-2) |
|
||
|
||
### Country Classification
|
||
|
||
Satellites are classified by operator country: CN, RU, US, EU, IN, KR, JP, IL, or OTHER. Classification is name-based (e.g., YAOGAN → CN, COSMOS → RU, WORLDVIEW → US).
|
||
|
||
> **Note**: US KH-11 spy satellites (USA-224/245/290/314/338) are classified — no public TLEs exist. The tracked satellites are those with publicly available orbital elements.
|
||
|
||
---
|
||
|
||
## Technical Details
|
||
|
||
### SGP4 Propagation
|
||
|
||
The browser uses [`satellite.js`](https://github.com/shashwatak/satellite-js) (v6) for SGP4/SDP4 orbital propagation:
|
||
|
||
1. **`initSatRecs()`** — Parse TLEs into `SatRec` objects once (expensive, cached until TLEs refresh)
|
||
2. **`propagatePositions()`** — For each satellite: `propagate()` → `eciToGeodetic()` → lat/lng/alt. Also computes 15-point trail (1 per minute, looking back 15 minutes)
|
||
3. **`startPropagationLoop()`** — Runs every 3 seconds via `setInterval`. LEO satellites move ~23km in 3 seconds, producing visible motion on the globe
|
||
|
||
### Globe Rendering
|
||
|
||
| Property | Value |
|
||
|----------|-------|
|
||
| `htmlAltitude` | `altitude_km / 6371` (Earth radius = 6371km, globe.gl uses normalized units) |
|
||
| Marker size | 4px with 6px glow |
|
||
| Trail rendering | `pathsData` with `pathPointAlt` for 3D orbit paths |
|
||
| Footprint | Surface-level marker (`htmlAltitude = 0`) with 12px translucent ring |
|
||
|
||
### Lifecycle
|
||
|
||
| Event | Action |
|
||
|-------|--------|
|
||
| Layer enabled | `loadSatellites()` → fetch TLEs → init satrecs → start 3s propagation loop |
|
||
| Layer disabled | `stopSatellitePropagation()` → clear interval |
|
||
| Globe → flat map | Propagation stops (globe-only layer) |
|
||
| Page load (cold start) | If `satellites` enabled and globe mode: loads alongside other intelligence signals |
|
||
| Page unload | Cleanup in `destroy()` |
|
||
|
||
### Circuit Breaker
|
||
|
||
Client-side fetch uses a circuit breaker: 3 consecutive failures trigger a 10-minute cooldown. Cached data continues to be used during cooldown.
|
||
|
||
---
|
||
|
||
## Redis Keys
|
||
|
||
| Key | TTL | Writer | Shape |
|
||
|-----|-----|--------|-------|
|
||
| `intelligence:satellites:tle:v1` | 4h | Railway relay (2h cycle) | `{ satellites: SatelliteTLE[], fetchedAt: number }` |
|
||
| `seed-meta:intelligence:satellites` | 7d | Railway relay | `{ fetchedAt: number, recordCount: number }` |
|
||
|
||
### Health Monitoring
|
||
|
||
- `api/health.js` checks `intelligence:satellites:tle:v1` as a standalone key
|
||
- Seed metadata checked with `maxStaleMin: 180` (3h — survives 1 missed cycle)
|
||
|
||
---
|
||
|
||
## Files
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `scripts/ais-relay.cjs` | `seedSatelliteTLEs()` + `startSatelliteSeedLoop()` |
|
||
| `api/satellites.js` | Vercel edge handler (Redis read, CDN cache) |
|
||
| `src/services/satellites.ts` | Frontend service: fetch, parse, propagate, loop |
|
||
| `src/components/GlobeMap.ts` | Marker rendering, trails, footprints, tooltips |
|
||
| `src/components/MapContainer.ts` | Adapter with cache + rehydration |
|
||
| `src/app/data-loader.ts` | Lifecycle: load, loop, stop, cleanup |
|
||
| `src/config/map-layer-definitions.ts` | Layer registry entry (globe-only) |
|
||
|
||
---
|
||
|
||
## Tier Availability
|
||
|
||
| Feature | Free | Pro | Enterprise |
|
||
|---------|------|-----|------------|
|
||
| Live satellite positions on globe | Yes | Yes | Yes |
|
||
| Orbit trails (15-min trace) | Yes | Yes | Yes |
|
||
| Ground footprint markers | Yes | Yes | Yes |
|
||
| Overhead pass predictions | — | Planned | Planned |
|
||
| Revisit frequency analysis | — | Planned | Planned |
|
||
| Imaging window alerts | — | Planned | Planned |
|
||
| Cross-layer correlation (sat + GPS jam, sat + conflict) | — | Planned | Planned |
|
||
| Satellite intel summary panel | — | Planned | Planned |
|
||
| Sensor swath / FOV visualization | — | Planned | — |
|
||
| Historical pass log (24h) | — | Planned | Planned (30-day archive) |
|
||
| Actual satellite imagery (SAR/optical) | — | — | Yes |
|
||
|
||
---
|
||
|
||
## Roadmap (Phase 2)
|
||
|
||
### Overhead Pass Prediction
|
||
|
||
Compute next pass times over user-selected locations (hotspots, conflict zones, bases). Example: _"GAOFEN-12 will be overhead Tartus in 14 min."_
|
||
|
||
### Revisit Time Analysis
|
||
|
||
Calculate how often a location is observed by hostile or friendly satellites. Useful for operational security and intelligence gap analysis.
|
||
|
||
### Imaging Window Alerts
|
||
|
||
Push notifications when SAR or optical satellites are overhead a user's watched regions. Integrates with Pro delivery channels (Slack, Telegram, WhatsApp, Email).
|
||
|
||
### Sensor Swath Visualization
|
||
|
||
Replace nadir-point footprints with actual field-of-view cones based on satellite sensor specs and orbital altitude.
|
||
|
||
### Cross-Layer Correlation
|
||
|
||
Detect intelligence-relevant patterns by combining satellite positions with other layers:
|
||
|
||
- **Satellite + GPS jamming zone** → electronic warfare context
|
||
- **Satellite + conflict zone** → battlefield ISR detection
|
||
- **Satellite + AIS gap** → maritime reconnaissance indicator
|
||
|
||
### Satellite Intel Summary Panel
|
||
|
||
Dedicated Pro panel with a table of tracked satellites: operator, sensor capability, orbit type, current position, and next pass over user-defined points of interest.
|
||
|
||
### Historical Pass Log
|
||
|
||
Which satellites passed over a given location in the last 24h (Pro) or 30 days (Enterprise). Useful for post-event analysis: _"What imaging assets were overhead during the incident?"_
|