diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..224ad14 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,168 @@ +# 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 + +```bash +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