AegisSight-Globe/CLAUDE.md

AegisSight Globe — Entwicklungsdokumentation

Projektueberblick

Eigenstaendige GEOINT-Anwendung (Geospatial Intelligence) auf globe.aegis-sight.de. CesiumJS 3D-Globus mit Echtzeit-Datenfusion aus oeffentlichen Quellen. Inspiriert vom WorldView/God's Eye Konzept, komplett eigenentwickelt.

Server & Deployment

• Server: 178.104.43.177 (Monitor-Server, 8GB RAM, Ubuntu 22.04)
• Port: 8890
• URL: https://globe.aegis-sight.de
• Service: systemd globe.service (auto-start, Memory-Limit 1GB)
• Venv: ~/.venvs/globe/ (Python 3.10)
• Verzeichnis: ~/AegisSight-Globe/
• Nginx: /etc/nginx/sites-enabled/globe.aegis-sight.de (SSL via Certbot)
• Git: Gitea gitea-undso.aegis-sight.de/AegisSight/AegisSight-Globe

Tech-Stack

• Backend: FastAPI + uvicorn
• Frontend: CesiumJS (CDN v1.125), Vanilla JS, kein Build-Step
• Datenbank: Geteilte SQLite /mnt/gitea/osint-data/osint.db (mit Monitor)
• Auth: Magic Link Login (JWT, gleicher JWT_SECRET wie Monitor)

Datenquellen & Layer

Layer	Quelle	API	Refresh	Menge
Flugverkehr	adsb.lol	/v2/point/30/0/10000	15s	~10.800
(Fallback)	adsb.one	/v2/point/30/0/10000	-	~7.000
Schiffsverkehr	AISStream.io	WebSocket wss://stream.aisstream.io	Echtzeit	~15.000+
Erdbeben	USGS	earthquake.usgs.gov GeoJSON	5min	~50/Tag
Katastrophen	NASA EONET	eonet.gsfc.nasa.gov/api/v3	10min	~30-80 aktiv
Nachrichten	GDELT	api.gdeltproject.org/v2/geo	10min	~200
Satelliten	CelesTrak	celestrak.org TLE JSON	1h	~500
Regenradar	RainViewer	api.rainviewer.com	5min	Radar-Overlay
Monitor OSINT	AegisSight Monitor	monitor.aegis-sight.de/api/public	2min	variabel

Satellitenbilder (Imagery Switcher)

Quelle	URL-Template	Lizenz
Cesium Ion	(Default via Ion Token)	Free-Tier / Commercial
Esri World Imagery	server.arcgisonline.com/.../tile/{z}/{y}/{x}	Frei fuer Display
Sentinel-2 2018-2024	tiles.maps.eox.at/wmts/.../s2cloudless-{YEAR}	CC-BY (ESA Copernicus)
OpenTopoMap	tile.opentopomap.org/{z}/{x}/{y}.png	ODbL
OpenStreetMap	a.tile.openstreetmap.org/{z}/{x}/{y}.png	ODbL

API-Keys & Credentials

Alle in ~/AegisSight-Globe/.env (nicht in Git):

• AISSTREAM_KEY: AISStream.io WebSocket API
• CESIUM_ION_TOKEN: Cesium Ion (Free-Tier, Commercial noetig fuer Vertrieb)
• JWT_SECRET: Gleicher wie Monitor
• SMTP_*: E-Mail-Versand fuer Magic Link
• MONITOR_API_KEY: Public API Key des Monitors
• DISASTER_INCIDENT_ID=45: Naturkatastrophen-Lage fuer Auto-Push

Verzeichnisstruktur

~/AegisSight-Globe/
├── .env
├── .gitignore
├── CLAUDE.md
├── requirements.txt
├── src/
│   ├── main.py                   # FastAPI App, Auth-Middleware, Static Mount
│   ├── config.py                 # DB, JWT, SMTP Konfiguration
│   ├── database.py               # aiosqlite Verbindung zur geteilten DB
│   ├── auth.py                   # JWT + Magic Link Token/Code
│   ├── auth_router.py            # /api/auth/* Endpoints
│   ├── email_utils.py            # Magic Link E-Mail-Versand
│   ├── data_flights.py           # adsb.lol + adsb.one Fallback
│   ├── data_ships.py             # AISStream.io WebSocket Collector
│   ├── data_quakes.py            # USGS Earthquake API
│   ├── data_gdelt.py             # GDELT GEO 2.0 API
│   ├── data_satellites.py        # CelesTrak TLE Orbital Elements
│   ├── data_disasters.py         # NASA EONET Events
│   ├── data_monitor.py           # Proxy zum Monitor Public API
│   └── data_push.py              # Auto-Push: Globe-Events -> Monitor
├── static/
│   ├── index.html                # CesiumJS Globe
│   ├── login.html                # Magic Link Login
│   ├── css/globe.css             # Dark-Theme
│   └── js/
│       ├── app.js                # Viewer, Layer-Management
│       ├── layers/
│       │   ├── flights.js        # Flugverkehr (zoom-adaptiv)
│       │   ├── ships.js          # Schiffsverkehr (zoom-adaptiv)
│       │   ├── disasters.js      # EONET + USGS kombiniert
│       │   ├── gdelt.js          # GDELT Nachrichten
│       │   ├── satellites.js     # Satelliten-Orbits
│       │   ├── weather.js        # Regenradar
│       │   ├── monitor.js        # Monitor OSINT-Daten
│       │   └── visualmodes.js    # NVG, FLIR, CRT
│       └── ui/
│           ├── sidebar.js        # Rechte Datenpunkt-Sidebar
│           ├── search.js         # Ortssuche + City Quick-Links
│           ├── imagery.js        # Satellitenbilder-Switcher
│           └── crosshairs.js     # Fadenkreuz + Range Rings
└── logs/globe.log

Bidirektionale Monitor-Verbindung

Globe -> Monitor (Auto-Push, data_push.py)

• Alle 10min: NASA EONET + USGS M4.5+ als Artikel an Monitor-Lage 45
• Duplikat-Check per Headline, Locations mit Koordinaten
• Monitor verifiziert und erstellt Zusammenfassung

Monitor -> Globe (Feed, data_monitor.py)

• /api/public/globe-feed?incident_id=X liefert GeoJSON
• Pro Standort: Ortsspezifische Artikel (Headline, Quelle, Auszug, Datum)
• Lage-Auswahl im Globe-Header bestimmt welche Daten angezeigt werden
• Nur aktive Live-Monitorings in der Auswahl

Klick-Flow

1. User waehlt Lage im Header (z.B. Naturkatastrophen)
2. Monitor-Standorte erscheinen als rote Punkte
3. Klick auf Katastrophe zeigt NASA-Daten + passende Monitor-Artikel
4. Zuordnung ist ortsspezifisch (Kenia-Klick = Kenia-Artikel)

Auth-System

• Magic Link: E-Mail -> 6-stelliger Code -> JWT (24h)
• Prueft: users.is_active=1 UND users.globe_access=1
• Globe-Zugang: An/Aus-Button im Verwaltungsportal pro User
• Alle Daten-APIs hinter Auth-Middleware
• Akzeptiert auch Monitor-JWT-Tokens (Kompatibilitaet)

Rendering-Architektur

Performance (PointPrimitiveCollection, GPU-beschleunigt)

• Weit (>5.000km): 5-Grad-Raster-Cluster mit Count-Labels
• Mittel (1.000-5.000km): 2-Grad-Raster
• Nah (<1.000km): Einzelne Punkte, Details bei Klick

Visual Modes

• STD: Photorealistisch
• NVG: Nachtsicht (gruener Monochrom-Filter)
• FLIR: Thermal (invertiert, Infrarot-Look)
• CRT: Retro-Monitor (Scanlines, Vignette)

Bekannte Limitierungen

• Cesium Ion Free-Tier: Nicht fuer kommerziellen Vertrieb
• Satelliten-Positionen: Vereinfachte Kepler-Berechnung (nicht SGP4-exakt)
• AISStream: ~1-2min bis globale Abdeckung nach Restart
• Sentinel-2: Wolkenfreie Komposite, nicht tagesaktuell

Services

sudo systemctl restart globe              # Globe-App
sudo systemctl restart osint-monitor      # Monitor (API-Aenderungen)
sudo systemctl restart verwaltungsportal  # Verwaltung

Entwicklungshinweise

• Alle JS als statische Dateien (kein Build-Step)
• Cache-Busting: Ctrl+Shift+R im Browser
• JS-Syntax pruefen: node --check static/js/layers/DATEI.js
• Inkrementelle Patches vermeiden — Dateien komplett neu schreiben
• .env Aenderungen erfordern Service-Restart