From 8d4403c7e68a01837672e0040f9301ddde55fd3a Mon Sep 17 00:00:00 2001 From: anoracleofra-code Date: Sun, 8 Mar 2026 16:40:18 -0600 Subject: [PATCH] docs: optimize README for conversion (quick start & fantasy hooks) Former-commit-id: 8c0a62d125399d53b5490428ef34f02cd526edaf --- README.md | 130 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 76 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index b48bccc..d7039a8 100644 --- a/README.md +++ b/README.md @@ -14,69 +14,91 @@ Built with **Next.js**, **MapLibre GL**, **FastAPI**, and **Python**, it's desig --- +## πŸ”₯ The Fantasy + +* Track private jets of billionaires +* Monitor satellites passing overhead +* Watch naval traffic worldwide +* Detect GPS jamming zones +* Follow earthquakes and disasters in real time + +--- + +## ⚑ Quick Start (Docker) + +```bash +git clone https://github.com/BigBodyCobain/Shadowbroker.git +cd Shadowbroker +docker-compose up -d +``` + +Open `http://localhost:3000` to view the dashboard! *(Requires Docker)* + +--- + ## ✨ Features ### πŸ›©οΈ Aviation Tracking -- **Commercial Flights** β€” Real-time positions via OpenSky Network (~5,000+ aircraft) -- **Private Aircraft** β€” Light GA, turboprops, bizjets tracked separately -- **Private Jets** β€” High-net-worth individual aircraft with owner identification -- **Military Flights** β€” Tankers, ISR, fighters, transports via adsb.lol military endpoint -- **Flight Trail Accumulation** β€” Persistent breadcrumb trails for all tracked aircraft -- **Holding Pattern Detection** β€” Automatically flags aircraft circling (>300Β° total turn) -- **Aircraft Classification** β€” Shape-accurate SVG icons: airliners, turboprops, bizjets, helicopters -- **Grounded Detection** β€” Aircraft below 100ft AGL rendered with grey icons +* **Commercial Flights** β€” Real-time positions via OpenSky Network (~5,000+ aircraft) +* **Private Aircraft** β€” Light GA, turboprops, bizjets tracked separately +* **Private Jets** β€” High-net-worth individual aircraft with owner identification +* **Military Flights** β€” Tankers, ISR, fighters, transports via adsb.lol military endpoint +* **Flight Trail Accumulation** β€” Persistent breadcrumb trails for all tracked aircraft +* **Holding Pattern Detection** β€” Automatically flags aircraft circling (>300Β° total turn) +* **Aircraft Classification** β€” Shape-accurate SVG icons: airliners, turboprops, bizjets, helicopters +* **Grounded Detection** β€” Aircraft below 100ft AGL rendered with grey icons ### 🚒 Maritime Tracking -- **AIS Vessel Stream** β€” 25,000+ vessels via aisstream.io WebSocket (real-time) -- **Ship Classification** β€” Cargo, tanker, passenger, yacht, military vessel types with color-coded icons -- **Carrier Strike Group Tracker** β€” All 11 active US Navy aircraft carriers with OSINT-estimated positions - - Automated GDELT news scraping for carrier movement intelligence - - 50+ geographic region-to-coordinate mappings - - Disk-cached positions, auto-updates at 00:00 & 12:00 UTC -- **Cruise & Passenger Ships** β€” Dedicated layer for cruise liners and ferries -- **Clustered Display** β€” Ships cluster at low zoom with count labels, decluster on zoom-in +* **AIS Vessel Stream** β€” 25,000+ vessels via aisstream.io WebSocket (real-time) +* **Ship Classification** β€” Cargo, tanker, passenger, yacht, military vessel types with color-coded icons +* **Carrier Strike Group Tracker** β€” All 11 active US Navy aircraft carriers with OSINT-estimated positions + * Automated GDELT news scraping for carrier movement intelligence + * 50+ geographic region-to-coordinate mappings + * Disk-cached positions, auto-updates at 00:00 & 12:00 UTC +* **Cruise & Passenger Ships** β€” Dedicated layer for cruise liners and ferries +* **Clustered Display** β€” Ships cluster at low zoom with count labels, decluster on zoom-in ### πŸ›°οΈ Space & Satellites -- **Orbital Tracking** β€” Real-time satellite positions from N2YO API -- **Mission-Type Classification** β€” Color-coded by mission: military recon (red), SAR (cyan), SIGINT (white), navigation (blue), early warning (magenta), commercial imaging (green), space station (gold) +* **Orbital Tracking** β€” Real-time satellite positions from N2YO API +* **Mission-Type Classification** β€” Color-coded by mission: military recon (red), SAR (cyan), SIGINT (white), navigation (blue), early warning (magenta), commercial imaging (green), space station (gold) ### 🌍 Geopolitics & Conflict -- **Global Incidents** β€” GDELT-powered conflict event aggregation (last 8 hours, ~1,000 events) -- **Ukraine Frontline** β€” Live warfront GeoJSON from DeepState Map -- **SIGINT/RISINT News Feed** β€” Real-time RSS aggregation from multiple intelligence-focused sources -- **Region Dossier** β€” Right-click anywhere on the map for: - - Country profile (population, capital, languages, currencies, area) - - Head of state & government type (Wikidata SPARQL) - - Local Wikipedia summary with thumbnail +* **Global Incidents** β€” GDELT-powered conflict event aggregation (last 8 hours, ~1,000 events) +* **Ukraine Frontline** β€” Live warfront GeoJSON from DeepState Map +* **SIGINT/RISINT News Feed** β€” Real-time RSS aggregation from multiple intelligence-focused sources +* **Region Dossier** β€” Right-click anywhere on the map for: + * Country profile (population, capital, languages, currencies, area) + * Head of state & government type (Wikidata SPARQL) + * Local Wikipedia summary with thumbnail ### πŸ“· Surveillance -- **CCTV Mesh** β€” 2,000+ live traffic cameras from: - - πŸ‡¬πŸ‡§ Transport for London JamCams - - πŸ‡ΊπŸ‡Έ Austin, TX TxDOT - - πŸ‡ΊπŸ‡Έ NYC DOT - - πŸ‡ΈπŸ‡¬ Singapore LTA - - Custom URL ingestion -- **Feed Rendering** β€” Automatic detection & rendering of video, MJPEG, HLS, embed, satellite tile, and image feeds -- **Clustered Map Display** β€” Green dots cluster with count labels, decluster on zoom +* **CCTV Mesh** β€” 2,000+ live traffic cameras from: + * πŸ‡¬πŸ‡§ Transport for London JamCams + * πŸ‡ΊπŸ‡Έ Austin, TX TxDOT + * πŸ‡ΊπŸ‡Έ NYC DOT + * πŸ‡ΈπŸ‡¬ Singapore LTA + * Custom URL ingestion +* **Feed Rendering** β€” Automatic detection & rendering of video, MJPEG, HLS, embed, satellite tile, and image feeds +* **Clustered Map Display** β€” Green dots cluster with count labels, decluster on zoom ### πŸ“‘ Signal Intelligence -- **GPS Jamming Detection** β€” Real-time analysis of aircraft NAC-P (Navigation Accuracy Category) values - - Grid-based aggregation identifies interference zones - - Red overlay squares with "GPS JAM XX%" severity labels -- **Radio Intercept Panel** β€” Scanner-style UI for monitoring communications +* **GPS Jamming Detection** β€” Real-time analysis of aircraft NAC-P (Navigation Accuracy Category) values + * Grid-based aggregation identifies interference zones + * Red overlay squares with "GPS JAM XX%" severity labels +* **Radio Intercept Panel** β€” Scanner-style UI for monitoring communications ### 🌐 Additional Layers -- **Earthquakes (24h)** β€” USGS real-time earthquake feed with magnitude-scaled markers -- **Day/Night Cycle** β€” Solar terminator overlay showing global daylight/darkness -- **Global Markets Ticker** β€” Live financial market indices (minimizable) -- **Measurement Tool** β€” Point-to-point distance & bearing measurement on the map +* **Earthquakes (24h)** β€” USGS real-time earthquake feed with magnitude-scaled markers +* **Day/Night Cycle** β€” Solar terminator overlay showing global daylight/darkness +* **Global Markets Ticker** β€” Live financial market indices (minimizable) +* **Measurement Tool** β€” Point-to-point distance & bearing measurement on the map --- @@ -202,9 +224,9 @@ If you want to modify the code or run from source: #### Prerequisites -- **Node.js** 18+ and **npm** -- **Python** 3.10+ with `pip` -- API keys for: `aisstream.io`, `n2yo.com` (and optionally `opensky-network.org`, `lta.gov.sg`) +* **Node.js** 18+ and **npm** +* **Python** 3.10+ with `pip` +* API keys for: `aisstream.io`, `n2yo.com` (and optionally `opensky-network.org`, `lta.gov.sg`) ### Installation @@ -240,8 +262,8 @@ npm run dev This starts: -- **Next.js** frontend on `http://localhost:3000` -- **FastAPI** backend on `http://localhost:8000` +* **Next.js** frontend on `http://localhost:3000` +* **FastAPI** backend on `http://localhost:8000` --- @@ -273,14 +295,14 @@ All layers are independently toggleable from the left panel: The platform is optimized for handling massive real-time datasets: -- **Gzip Compression** β€” API payloads compressed ~92% (11.6 MB β†’ 915 KB) -- **ETag Caching** β€” `304 Not Modified` responses skip redundant JSON parsing -- **Viewport Culling** β€” Only features within the visible map bounds (+20% buffer) are rendered -- **Clustered Rendering** β€” Ships, CCTV, and earthquakes use MapLibre clustering to reduce feature count -- **Debounced Viewport Updates** β€” 300ms debounce prevents GeoJSON rebuild thrash during pan/zoom -- **Position Interpolation** β€” Smooth 10s tick animation between data refreshes -- **React.memo** β€” Heavy components wrapped to prevent unnecessary re-renders -- **Coordinate Precision** β€” Lat/lng rounded to 5 decimals (~1m) to reduce JSON size +* **Gzip Compression** β€” API payloads compressed ~92% (11.6 MB β†’ 915 KB) +* **ETag Caching** β€” `304 Not Modified` responses skip redundant JSON parsing +* **Viewport Culling** β€” Only features within the visible map bounds (+20% buffer) are rendered +* **Clustered Rendering** β€” Ships, CCTV, and earthquakes use MapLibre clustering to reduce feature count +* **Debounced Viewport Updates** β€” 300ms debounce prevents GeoJSON rebuild thrash during pan/zoom +* **Position Interpolation** β€” Smooth 10s tick animation between data refreshes +* **React.memo** β€” Heavy components wrapped to prevent unnecessary re-renders +* **Coordinate Precision** β€” Lat/lng rounded to 5 decimals (~1m) to reduce JSON size ---