🌍 GEOVIGILANT ARGUS EYE

================================================================================
  [ SECURE UPLINK ESTABLISHED ] // [ AUTH: OPERATOR_LEVEL_5 ] // [ KH11-OPS-4117 ]
================================================================================
   ____             __     ___       _ _                 _        _                          
  / ___| ___  ___   \ \   / (_) __ _(_) | __ _ _ __  | |_     / \   _ __ __ _ _   _ ___ 
 | |  _ / _ \/ _ \   \ \ / /| |/ _` | | |/ _` | '_ \ | __|   / _ \ | '__/ _` | | | / __|
 | |_| |  __/ (_) |   \ V / | | (_| | | | (_| | | | || |_   / ___ \| | | (_| | |_| \__ \
  \____|\___|\___/     \_/  |_|\__, |_|_|\__,_|_| |_| \__| /_/   \_\_|  \__, |\__,_|___/
                               |___/                                    |___/            
================================================================================
  // CLASSIFICATION: TOP SECRET // SI-TK // NOFORN // PROJECT: ARGUS EYE v1.1.0
  // DEVELOPER: YTxFSGAMERz
================================================================================

[OPERATIONAL DIRECTIVE]: GeoVigilant Argus Eye is an enterprise-grade geospatial intelligence (GEOINT), cyber-physical surveillance, and multi-domain OSINT reconnaissance platform. It seamlessly fuses live military and commercial ADS-B flight transponders, real-time AIS maritime fleets, orbital satellite positions, USGS seismic telemetry, thermal wildfire perimeters, CCTV surveillance nodes, undersea fiber-optic cables, and geopolitical crisis zones onto a photorealistic 3D Cesium globe and an ultra-low-latency 2D MapLibre tactical workspace.

📸 SYSTEM SHOWCASE & OPERATIONAL SCREENSHOTS

🛰️ 1. Multi-Domain Intelligence Suite & Command Overview

The central command hub connecting all geospatial intelligence engines, real-time sensor grids, and zero-trust IoT telemetry networks.

📡 2. 3D Air Surveillance Radar & Tactical Multi-Layer HUD

Real-time 3D tactical radar with rotating sweep beam, true altitude drop stems, velocity vectors, and 16 active real-time telemetry layers.

🌍 3. Photorealistic 3D Cesium Planetary Reconnaissance

Full-spectrum satellite basemap with global ADS-B flight tracks, LEO/GEO satellite orbits, live world clocks, and the real-time GEO-AI UPLINK threat matrix.

🗺️ 4. ARGUS GroundView: 2D Tactical Intelligence & SVI Camera Sensor Inspection

Dedicated 2D MapLibre workspace for street-level intelligence, high-density asset clustering, and Street View Imagery (SVI) sensor interrogation.

Tactical Ground Sensor Mesh	SVI Optical Camera Inspection Modal

📶 5. RF Surveillance, Wireless Intercept & Deep Dark Web OSINT

Geolocated WiFi BSSID/SSID tracking, OpenCellID mobile tower triangulation, and integrated Tor SOCKS5 dark web onion search.

📰 6. Geopolitical Intelligence Stream & Social Reconnaissance

Real-time crisis monitoring, sentiment analysis, hot sector trending hashtags, active crisis sector interrogation, and neural social media reconnaissance across Twitter/X and Reddit.

Geopolitical Crisis Map & Sentiment Matrix	Active Sector Tactical Intercept

Twitter / X Neural Reconnaissance	Reddit OSINT & Community Intelligence

🌐 PRODUCTION UPLINKS & WORKSPACES

Interface	Route	Primary Engine	Purpose
🎛️ Command Suite	`/`	HTML5 / Vite HUD	Flagship executive portfolio, system index, and telemetry metrics
🌍 3D Earth HUD	`/earth`	CesiumJS 1.114	Planetary 3D visualization, 16 live telemetry feeds, GLSL shaders, 3D Air Radar
🗺️ GroundView 2D	`/ground`	MapLibre GL JS	High-speed 2D ground surveillance, Mapillary SVI street inspection, 88K+ visual landmarks
📶 RF Surveillance	`/surveillance`	Leaflet / Google Maps	WiGLE WiFi mapping, OpenCellID cell towers, Tor Onion search, and crime recon
📰 News Intelligence	`/news`	Leaflet / Carto Dark	Geopolitical event mapping, regional crisis streams, sentiment analysis
🐦 Twitter OSINT	`/social/twitter`	Tactical Form HUD	Neural user search, keyword sentiment tracking, timeline OSINT
🤖 Reddit OSINT	`/social/reddit`	Tactical Form HUD	Subreddit intelligence, thread scraping, community behavior analysis

⚡ ARCHITECTURE & CORE CAPABILITIES

[GEOVIGILANT ARGUS SYSTEM ARCHITECTURE]
 ├── 🌍 3D PLANETARY ENGINE       : CesiumJS 1.114 (ArcGIS World Imagery + 3D Terrain + OSM Buildings)
 ├── 🗺️ 2D TACTICAL ENGINE        : MapLibre GL JS (Vector Carto Basemaps + Mapillary SVI Layer)
 ├── 📡 3D AIR SURVEILLANCE RADAR : Real-time rotating sweep beam, drop stems, 6 continental hubs
 ├── 🖥️ CYBERPUNK HUD DESIGN     : 1,300+ lines custom CSS, responsive panels, telemetry clocks, HUD audio
 ├── 🚀 SERVERLESS API RUNTIME    : Flask 3.1 WSGI + Python 3.12 Serverless Functions on Vercel
 ├── ✈️ GLOBAL FLIGHT TRACKING    : Multi-hub ADS-B radar (OpenSky Network + regional aggregators)
 ├── 🚢 MARITIME VESSEL FLEET     : Live AIS WebSocket stream (AISstream.io) + global sea lane corridors
 ├── 🛰️ ORBITAL ASSET MATRIX     : 800+ Live LEO/GEO Satellites via SatNOGS DB / CelesTrak TLE
 ├── 🌋 REAL-TIME SEISMIC GRID   : Instantaneous Global Earthquake Telemetry via USGS GeoJSON
 ├── 📹 SURVEILLANCE CCTV NETWORK : Global Camera Feeds with Real-Time Analog Scan Overlay
 ├── 📶 RF & WIRELESS SURVEILLANCE: WiGLE WiFi networks, OpenCellID cell towers, Bluetooth beacons
 ├── 🤖 GEO-AI RECON ASSISTANT   : LLaMA-3.1 / OpenRouter / Hugging Face + ChromaDB RAG Vector Memory
 └── 🕵️ MULTI-SOURCE OSINT & TOR  : Clearnet Aggregator (DDG/Bing/Google) + Tor Onion Search Proxy

📡 REAL-TIME DATA FEEDS

The tactical console tracks and renders 16 simultaneous telemetry data feeds:

Layer	Node Source	Description
🛫 Live Flights	OpenSky Network & Multi-Hub	Worldwide ADS-B transponder telemetry with altitude, true heading, and squawk alert detection
🚢 Live Vessels	AISstream.io & Maritime Fleet	Real-time container ships, tankers, cargo, and naval vessels across maritime chokepoints
🛰️ Satellites	SatNOGS & CelesTrak	800+ active satellites calculated via orbital parameters (TLE) and SGP4 orbital propagation
🌋 Earthquakes	USGS Earthquake API	Real-time global seismic events with magnitude-scaled shockwave rings and hypocenter depth
📡 Weather Radar	Open-Meteo & NOAA NWS	Live precipitation levels, atmospheric pressure, and severe county warnings
📹 CCTV Cameras	Global Surveillance Nodes	Worldwide traffic and security cameras with live modal video overlays
🏛️ Military Bases	Global GeoINT DB	Strategic defense installations, naval stations, and command headquarters
☢️ Nuclear Sites	IAEA Open Geodata	Global nuclear power plants, enrichment facilities, and storage depots
⚔️ Conflict Zones	ACLED / Conflict Intel	Active geopolitical war theaters (Gaza, Ukraine, Strait of Hormuz, Sudan, Red Sea)
🎯 Intel Hotspots	Strategic Risk Matrix	Real-time risk-assessed hotspots classified by threat severity level
⚓ Strategic Waterways	Maritime Chokepoints	Critical maritime transit corridors (Bab el-Mandeb, Malacca, Hormuz, Suez, Panama)
🔌 Undersea Cables	Submarine Telecom DB	Trans-oceanic fiber-optic communications cables powering global internet traffic
🔥 Wildfires	NASA FIRMS (VIIRS/MODIS)	Real-time thermal anomaly blooms and active wildfire perimeter tracking
🌪️ Natural Events	NASA EONET	Severe storms, active volcanoes, sea/lake ice floes, and natural hazards
🚀 Spaceports	Orbital Launch DB	Global space launch complexes (Cape Canaveral, Baikonur, Kourou, Tanegashima)
💰 Economic Centers	Global Financial Matrix	Major stock exchanges, trading hubs, and central financial districts

👁️ GLSL OPTICAL FILTERS (SENSOR MODES)

The 3D globe features hardware-accelerated GLSL (OpenGL Shading Language) post-processing fragment shaders:

[GLSL SENSOR MODES]:
 ├── NORMAL : Full-spectrum photorealistic ArcGIS Earth satellite imagery.
 ├── CRT    : Vintage surveillance monitor with phosphor scanlines and chromatic aberration.
 ├── NVG    : Gen-3 Night Vision Goggles with green-phosphor luminance mapping and ISO sensor noise.
 ├── FLIR   : Forward-Looking Infrared mapping luminance across a 4-band thermal spectrum.
 ├── NOIR   : High-contrast monochrome surveillance overlay with edge vignetting.
 ├── ANIME  : Sobel edge-detection filter with color-quantization comic outlines.
 └── SNOW   : Severe winter atmospheric conditions simulator with blizzard noise grain.

🧠 ADVANCED TACTICAL MODULES

📡 3D AIR SURVEILLANCE RADAR

Press R to engage the rotating 3D air radar dome. Projects true spherical-to-Cartesian altitude drop stems, velocity vectors, and concentric range rings (50–300 NM) across 6 switchable continental radar hubs (Americas, Europe, East Asia, Middle East, South Asia, Global).

🔲 PANOPTIC A.I. OBJECT DETECTION

Activating AI Panoptic Mode triggers a real-time scanning sweep. The targeting core renders dynamic HUD bounding boxes around planetary coordinates, classifying anomalies into Vehicle, Aircraft, Vessel, Building, or Personnel with computed confidence ratings.

📶 GEO-AI UPLINK (THREAT MATRIX)

A context-aware geospatial AI responding to cursor movement over planetary coordinates. Evaluates regional threat indicators on a localized 2° grid and displays real-time telemetry: Naval Movement, Encrypted Comm Burst, Thermal Bloom, or Troop Buildup.

🍕 PIZZINT (PENTAGON PIZZA INDEX)

A real-time status monitoring panel tracking late-night pizza delivery surges at US intelligence headquarters (Arlington Pentagon HQ, Langley CIA, and Fort Meade NSA) as a leading proxy for impending geopolitical operations.

📂 REPOSITORY ARCHITECTURE

GeoVigilant-Argus/
├── api/
│   └── index.py               # WSGI serverless entrypoint for Vercel Python runtime
├── globe/                     # Standalone 3D Cesium Subsystem
│   ├── index.html             # Standalone 3D globe entrypoint
│   ├── src/globe.js           # Terra5Globe Cesium controller & GLSL shader pipeline
│   ├── src/main.js            # AppController state management, polling, & UI bindings
│   └── src/services/          # Telemetry API clients & GeoJSON datasets
├── static/
│   ├── css/
│   │   ├── globe-style.css    # Primary tactical HUD layout, panels, and responsiveness
│   │   └── cyberpunk.css      # Cyberpunk visual styles, neon borders, and animations
│   └── js/
│       ├── globe.js           # Compiled 3D globe engine
│       └── globe-main.js      # Compiled frontend application controller
├── templates/
│   ├── portfolio.html         # Executive command suite & showcase overview (/)
│   ├── earth.html             # Master 3D Earth HUD template (/earth)
│   ├── groundview.html        # ARGUS GroundView 2D intelligence template (/ground)
│   ├── wifi-search.html       # RF & WiFi surveillance template (/surveillance)
│   ├── news.html              # Geopolitical intelligence stream template (/news)
│   └── social/                # Social media OSINT templates (Twitter, Reddit)
├── screenshots/               # High-resolution tactical screenshots & UI captures
├── ARGUS_DATASET/             # Verified 88K+ landmark & streetscape image dataset
│   ├── reports/final_report.md# Autonomous acquisition & verification audit report
│   └── geodata/               # GeoJSON boundaries, military sites, cables, waterways
├── app.py                     # Core Flask application, REST APIs, & OSINT endpoints
├── Socio.py                   # Social media OSINT, Twitter API v2, & sentiment analysis
├── news_config.py             # Global news feeds and geopolitical RSS feeds configuration
├── vercel.json                # Vercel serverless routing, rewrite rules, and static routing
├── requirements.txt           # Optimized lightweight Python dependencies
└── package.json               # Vite build pipeline and frontend dependencies

🚀 QUICK START & INSTALLATION

Tip

⚡ ZERO API KEYS REQUIRED TO RUN!

You do NOT need to obtain or configure ANY API keys to run GeoVigilant Argus Eye. The platform is engineered to work 100% out-of-the-box. All primary surveillance and telemetry systems run immediately using free public feeds, built-in telemetry proxies, and local heuristics:

🛫 Live ADS-B Flights: Real-time OpenSky Network transponders (Free / Public, No Key Needed)
🚢 Live Maritime Vessels: Pre-configured global AISstream vessel proxy (Built-In Key, No Setup)
🛰️ Orbiting Satellites: CelesTrak & SatNOGS TLE orbital propagation (Free / Public, No Key Needed)
🌋 Earthquake Sensors: USGS Global Seismic Network (Free / Public, No Key Needed)
📡 Weather Radar & Alerts: NOAA NWS & Open-Meteo atmospheric radar (Free / Public, No Key Needed)
🔥 Thermal Wildfires: NASA FIRMS VIIRS/MODIS satellite blooms (Free / Public, No Key Needed)
🌪️ Natural Disasters: NASA EONET hazard events (Free / Public, No Key Needed)
🗺️ 3D & 2D Basemaps: ArcGIS Photorealistic Imagery & CartoDB Dark Matter (Free / Public, No Key Needed)
📹 Global CCTV: Public traffic & security camera network (Free / Public, No Key Needed)
🏛️ Defense & GeoINT: Military bases, nuclear sites, undersea cables, waterways (Built-in GeoData)
📰 Geopolitical News: 50+ regional RSS news feeds + GDELT crisis stream (Free / Public, No Key Needed)
🤖 Tactical AI Core: Local Ollama integration or built-in deterministic heuristic analysis (No Key Needed)

⚡ Option A: 1-Click Launch (Easiest)

🪟 Windows (1-Click)

Simply double-click start.bat in the project folder (or run .\start.bat in PowerShell/CMD).

Automatically detects your Python runtime and virtual environment.
Automatically verifies dependencies.
Displays an interactive tactical launcher menu (Eco Mode, 60 FPS Performance Mode, or Standalone Flask).
Automatically launches your browser at http://localhost:5000/.

🐧 Linux & 🍎 macOS (1-Command)

Run the unified shell launcher:

chmod +x start.sh
./start.sh

📦 Option B: Manual Setup (3 Simple Commands)

If you prefer to run standard terminal commands:

1. Clone the Repository

git clone https://github.com/YTxFSGAMERz/GeoVigilant-Argus.git
cd GeoVigilant-Argus

2. Install Python Dependencies

pip install -r requirements.txt

3. Run the Application

python app.py

Open http://localhost:5000/ in your browser!

Note

Do I need Node.js or npm? No! All frontend bundles (globe-main.js) are already pre-compiled and included in static/js/. You only need Node.js / npm if you are actively modifying the frontend source code and running the Vite HMR dev server (npm run dev).

⚙️ How to Configure Optional API Keys

To add your own optional API keys securely without putting them in the codebase:

Copy .env.example to .env:
```
cp .env.example .env
```
(On Windows Command Prompt, run: copy .env.example .env)

Open .env and fill in any optional provider keys:

# Server & Operational Security (Optional overrides)
HOST=127.0.0.1
PORT=5000
SECRET_KEY=your_custom_secret_key

# Optional: Cloud AI Reasoning (Defaults to Local Ollama / Built-in Heuristics if omitted)
OPENROUTER_API_KEY=your_openrouter_key
ANTHROPIC_AUTH_TOKEN=your_anthropic_token
HF_TOKEN=your_huggingface_token

# Optional: Commercial & Telemetry Overrides (Built-in free fallbacks used if omitted)
OPENCELLID_API_KEY=your_custom_opencellid_key
AIS_API_KEY=your_custom_aisstream_key
NEWS_API_KEY=your_custom_newsapi_key
WIGLE_API_NAME=your_wigle_name
WIGLE_API_TOKEN=your_wigle_token
MACVENDORS_TOKEN=your_macvendors_token

# Optional: Live Twitter/X API v2 Dev Access
TWITTER_API_KEY=your_key
TWITTER_API_SECRET=your_secret
TWITTER_BEARER_TOKEN=your_token

# Optional: Discord Bot & Alerts
DISCORD_BOT_TOKEN=your_bot_token
DISCORD_CHANNEL_ID=your_channel_id

Launch the Platform: The platform automatically loads .env upon startup!

Note

Again, everything runs out-of-the-box without configuring .env. Optional keys simply unlock private high-rate-limit commercial endpoints and custom cloud LLMs.

🌐 PRODUCTION DEPLOYMENT (VERCEL + RENDER)

GeoVigilant Argus Eye uses a high-performance decoupled cloud architecture:

Vercel: Hosts the static multi-page frontend (dist/), Cesium 3D HUD, and 2D GroundView at edge latency.
Render: Hosts the Flask 3.1 WSGI backend API via Gunicorn with real-time live telemetry proxies and OSINT engines.
Database: Runs on lightweight embedded SQLite caches (geosent.db, socio.db). Zero paid or external database servers required.

[VERCEL EDGE FRONTEND]  ---- HTTPS API Calls (VITE_API_URL) ---->  [RENDER BACKEND API]
(dist/ static distribution)                                          (Gunicorn 0.0.0.0:$PORT)
                                                                               │
                                                                   [EXTERNAL DATA SOURCES]
                                                                (OpenSky, USGS, NASA, AIS, etc.)

🛠️ Step 1: Deploy Backend on Render

Log in to your Render Dashboard and click New + → Web Service (or use Blueprint pointing to render.yaml).
Connect your GitHub repository YTxFSGAMERz/GeoVigilant-Argus.
Configure service parameters:
- Name: geovigilant-argus-api
- Environment: Python
- Region: Oregon (or nearest)
- Branch: main
- Build Command: pip install -r requirements.txt && python scripts/sync_hf_dataset.py
- Start Command: gunicorn app:app --bind 0.0.0.0:$PORT --workers 1 --threads 4 --timeout 120
- Plan: Free
Under Advanced → Health Check Path, set /health.
Add Environment Variables:
- PYTHON_VERSION: 3.12.0
- FLASK_DEBUG: false
- HOST: 0.0.0.0
- ARGUS_HF_DATASET: YTxFSGAMERz/ARGUS_DATASET
- SECRET_KEY: <generate-a-random-hex-string>
- (Optional) Add any telemetry API keys (e.g. OPENCELLID_API_KEY, AIS_API_KEY, OPENROUTER_API_KEY).
Click Create Web Service. Wait for the build to complete and copy your live backend URL (e.g., https://geovigilant-argus-api.onrender.com).

⚡ Step 2: Deploy Frontend on Vercel

Log in to Vercel and click Add New... → Project.
Import the YTxFSGAMERz/GeoVigilant-Argus repository.
Configure build & deployment settings:
- Framework Preset: Vite
- Root Directory: ./ (leave default)
- Build Command: npm run build
- Output Directory: dist
Under Environment Variables, add:
- VITE_API_URL: https://your-render-service.onrender.com (use your actual Render URL from Step 1)
Click Deploy. Vercel will run npm run build, assemble dist/, and provision your production URL (e.g., https://geovigilant-argus.vercel.app).

🔗 Step 3: Configure Cross-Origin Synchronization (CORS)

Return to your Render Dashboard for geovigilant-argus-api.
Under Environment Variables, set:
- FRONTEND_URL: https://geovigilant-argus.vercel.app (your actual Vercel domain)
Trigger a manual deploy (or Render will automatically restart with the new variable).
Now your frontend on Vercel and backend on Render can securely communicate with CORS credentials enabled.

⏰ Step 4: 24/7 Keep-Alive via GitHub Actions (Zero Cold Starts)

To eliminate Render's 15-minute inactivity spin-down for $0.00 forever, this repository includes an automated GitHub Actions workflow .github/workflows/render_keep_alive.yml:

Trigger: Scheduled cron running every 10 minutes (*/10 * * * *) + manual dispatch.
Default Target: Pings https://geovigilant-argus-api.onrender.com/health.
Custom URL: If your Render service has a different URL, add RENDER_API_URL under your GitHub Repo Settings → Secrets and variables → Actions.
Result: Render stays warm and awake 24/7 with zero sleeping and zero cold starts!

📦 30GB Landmark & Streetscape Dataset Integration (Hugging Face)

GeoVigilant Argus Eye connects directly to the 30GB+ landmark image library hosted on Hugging Face:

Index Sync: During container build, scripts/sync_hf_dataset.py downloads lightweight index files (state_tracker.db, phash_bktree.index, places.csv, coords.csv) taking under ~250 MB disk space.
On-Demand CDN Streaming: When an image is requested via /api/argus/images/<image_id>, the backend automatically redirects (HTTP 302) to the global Hugging Face Dataset CDN (https://huggingface.co/datasets/YTxFSGAMERz/ARGUS_DATASET/).
Storage Cost: $0.00 / month with zero local disk footprint for 74,000+ high-res images.

🩺 Health & Verification Endpoints

Render Health Check: GET https://your-backend.onrender.com/health → {"status": "ok"}
System Telemetry: GET https://your-backend.onrender.com/api/sys/memory

Local Test Suite:

npm test        # Vitest pipeline and cryptographic unit tests
npm run build   # Production Vite bundle and dist/ assembly

💡 Known Free-Tier Characteristics

Zero Cold Starts: With the GitHub Actions keep-alive workflow pinging every 10 minutes, Render never enters sleep mode.
Vercel Edge: The frontend runs 24/7 with 0ms cold start latency on the Vercel Edge Global CDN.
Cost: $0.00 / month forever.

⌨️ OPERATOR KEYBOARD SHORTCUTS

Shortcut	Command	Action
`R`	`TOGGLE_AIR_RADAR`	Activates / deactivates the 3D rotating air surveillance radar dome
`Ctrl + [`	`TOGGLE_SIDEBAR`	Collapses / expands the tactical layers control drawer
`Ctrl + P`	`TOGGLE_PANOPTIC`	Activates / deactivates the AI target bounding box generator
`Escape`	`DISMISS_PANELS`	Closes all open modals (Radar, CCTV, News, Target Info, PIZZINT)

📜 DOCUMENTATION DIRECTORY

📊 SYSTEM_SPEC.md: Mathematical models, shader pipelines, 3D radar trigonometry, and architecture specifications.
📖 OPERATOR_GUIDE.md: Field operating manual, HUD controls, SVI sensor inspection, and coordinate directory.
🎯 docs/presentation_guide.md: Complete pitch manual, problem-solution matrix, and demo script.
🤖 docs/geovigilant_ai.md: GeoVigilant AI GEOINT assistant, RAG architecture, and command tags.
🔍 docs/search_options.md: Clear-net OSINT, dark web Tor integration, and social search.
🔎 docs/criminal_recon_manual.md: Crime record search, police data ingestion, and biometrics roadmap.
🌍 globe/README.md: Isolated 3D Cesium globe subsystem and Vite build toolchain.
📁 ARGUS_DATASET/reports/final_report.md: 88K+ landmark & streetscape imagery acquisition benchmark.
🔒 SECURITY.md: Security policy and vulnerability disclosure procedures.
🤝 CONTRIBUTING.md: Contribution guidelines and code standards.

📄 LICENSE

Distributed under the MIT License. See LICENSE.md for full details.

================================================================================
  [ END OF TRANSMISSION ] // [ GEOVIGILANT ARGUS EYE READY ]
================================================================================

FilesExpand file tree

README.md

Latest commit

History