Sovereign Watch

---

Screenshots

Tactical Map View

Orbital Tracking

JS8CALL Terminal

Global Map Filters and Layers

Dashboard View

Intel Map View

---

Quick Start

# 1. Clone & configure
git clone https://github.com/d3mocide/Sovereign_Watch.git
cd Sovereign_Watch
cp .env.example .env
# Edit .env — see Documentation/Configuration.md for all variables

# 2. Boot
make prod          # production build (static frontend, no hot-reload)
# or
make dev           # development build (Vite HMR, uvicorn --reload)

# 3. Access
#   Tactical Map: http://localhost
#   API Docs:     http://localhost/api/docs

Minimum config required in .env:

CENTER_LAT=45.5152        # Your monitoring area
CENTER_LON=-122.6784
POSTGRES_PASSWORD=...     # Required — choose any strong password
JWT_SECRET_KEY=...        # Required — generate with: openssl rand -hex 32
AISSTREAM_API_KEY=...     # Free at aisstream.io (maritime data)
AISHUB_USERNAME=...       # Optional — enables automatic AIS fallback via AISHub
AIS_PRIMARY_SOURCE=aisstream  # Optional — aisstream or aishub
VITE_MAPBOX_TOKEN=...     # mapbox.com (optional — for 3D terrain)
ANTHROPIC_API_KEY=...     # For AI track analysis (optional)

---

Documentation

Full documentation is in the Documentation/ folder:

Guide	Description
Deployment & Upgrade Guide	Install, run, upgrade, troubleshoot
Configuration Reference	All .env variables
ADS-B Poller	Aviation data ingestion
AIS Maritime Poller	Maritime vessel positions
Space Pulse	SGP4, SatNOGS, and Space Weather
JS8Call Radio	HF Radio / JS8Call Terminal
Infra Poller	Internet outages + submarine cables
RF Pulse	RF repeaters + NOAA weather radio
GEODENT (GDELT)	Real-time OSINT event stream
TAK Protocol Reference	Internal message schema (CoT/Protobuf)
API Reference	REST endpoints + WebSocket
UI User Guide	How to use the Tactical and Orbital maps
AI Configuration	How to configure the AI models

---

Architecture

graph TD
    subgraph "Entry Point (Nginx)"
        NG[Reverse Proxy :80]
    end

    subgraph "Ingestion (Python Pollers)"
        A[ADS-B Network] -->|JSON| B(Ingestion Services)
        C[AIS Stream] -->|JSON| B
        Z[Space Domain Feed] -->|TLE/SatNOGS/NOAA| B
        H3[H3 Coverage: Live Poller Pulse] -->|JSON| B
        JS[Sovereign JS8Call] -->|UDP Bridge| B
        RF[RF Pulse: ARD/NOAA/RepBook/RadioRef] -->|REST API/SOAP| B
        IN[Infra Poller: IODA/Cables] -->|REST API| B
        GD[GEODENT: GDELT Pulse OSINT] -->|TSV/REST API| B
        B -->|TAK JSON| D(Redpanda Bus)
    end

    subgraph "State & Persistence"
        D -->|Stream| E[(TimescaleDB)]
        RS[(Redis Cache)]
        B -->|Cache| RS
    end

    subgraph "Cognition (LiteLLM)"
        G[Fusion API] -->|Query| H{AI Router}
        H -->|Tier 1| I[Local Llama3]
        H -->|Tier 3| CL[Claude]
    end

    subgraph "Presentation (React + Deck.gl)"
        FE[MainHUD Shell] --> L[Intelligence Feed]
        FE --> M[Projective Velocity Blending]
        M -->|WebGL 3D| N[Mapbox / MapLibre Overlay]
        FE --> SYS[System Settings Widget]
        FE --> INF[Infrastructure Layers]
    end

    NG -->|/| FE
    NG -->|/api/| G
    NG -->|/js8/| JS
    G -->|Read Cache| RS

---

Data Sources

All upstream data is sourced from public, open-access networks.

Domain	Source	Update Rate
Aviation (ADS-B)	adsb.fi, adsb.lol, airplanes.live	Every 2–30 seconds
Maritime (AIS)	AISStream.io WebSocket	Event-driven (real time)
Space	Celestrak, SatNOGS, NOAA SWPC	5s (SGP4) / 1h (Obs)
Internet Outages	IODA (Georgia Tech)	Every 30 minutes
Submarine Cables	TeleGeography	Every 24 hours
RF Infrastructure	ARD, NOAA NWR, RadioReference	Every 24–168 hours
GDELT (OSINT)	GDELTproject.org	Every 15 minutes
WebSDR	Global Network	Discovery (on-demand)

---

⚠️ Disclaimer

---

AI Agent Protocol

This repository is Agent-Aware. Read AGENTS.md before contributing.

• All inter-service data must adhere to the TAK Protocol — see TAK Protocol Reference
• Follow the "Sovereign Glass" design principles for all UI modifications
• Never run commands directly on the host — use Docker Compose

---

Contributing

Pull requests are welcome. Please review AGENTS.md and the Documentation before contributing.

• Issues: Use the GitHub issue tracker for bugs and feature requests
• PRs: Include a clear description; AI agent contributions must align with AGENTS.md

---

Tech Stack

Docker · FastAPI · React · Deck.gl · MapLibre GL JS · Mapbox GL JS · TimescaleDB · Redpanda · Celestrak · JS8Call · KiwiSDR

---