# 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)

## Verzeichnisstruktur

```
AegisSight-Globe/
  .env                        # API-Keys (nicht in Git)
  CLAUDE.md                   # Diese Datei
  src/
    main.py                   # FastAPI-App, Router-Einbindung, Background-Tasks
    config.py                 # DB-Pfad, JWT, SMTP, URLs
    database.py               # aiosqlite async DB-Dependency
    auth.py                   # JWT create/decode, get_current_user, Cross-Service-Auth
    auth_router.py            # Magic Link Login (request-link, verify, me)
    email_utils.py            # Magic Link E-Mail-Versand
    data_flights.py           # Ziviler Flugverkehr (adsb.lol + adsb.one Fallback)
    data_ships.py             # Schiffsverkehr (AISStream WebSocket, Dark-Ship-Erkennung)
    data_military.py          # Militaerflugzeuge (adsb.lol /v2/mil)
    data_quakes.py            # Erdbeben (USGS GeoJSON)
    data_disasters.py         # Naturkatastrophen (NASA EONET v3)
    data_satellites.py        # Satelliten-Orbits (CelesTrak TLE)
    data_gdelt.py             # Geokodierte Nachrichten (GDELT GEO 2.0)
    data_monitor.py           # OSINT-Daten vom AegisSight Monitor
    data_push.py              # Auto-Push: EONET+USGS M4.5+ -> Monitor Lage 45
    data_infra.py             # Seekabel, AKWs, Militaerbasen, ISS
    data_geoint.py            # EXIF-Extraktion, Sonnenstand, Hoehenprofil, Funkmasten
    data_vlm.py               # VLM-Bildanalyse (Claude Code headless -> Geolocation)
    data_overpass.py           # Overpass Turbo Queries + Template-Bibliothek
    milship_db.py             # Militaerschiff-DB (~200 MID-Codes, 17 Marinen)
  static/
    index.html                # Haupt-App (Auth, Header, Layer-Panel, Bottom Bar)
    login.html                # Magic-Link Login-Seite
    favicon.svg               # AegisSight Logo
    css/
      globe.css               # Taktisches Dark Theme, alle UI-Styles
    js/
      app.js                  # Globe-Objekt: Viewer, Layer-Toggles, Gruppen, Stats
      layers/
        flights.js            # FlightsLayer (zoom-adaptiv, Grid-Cluster)
        ships.js              # ShipsLayer (Typfilter, Kurslinien, Dark-Ship)
        military.js           # MilitaryLayer (rote Punkte + Labels)
        quakes.js             # QuakesLayer (farbcodiert nach Alter)
        disasters.js          # DisastersLayer (EONET + USGS + Monitor-Kontext)
        firms.js              # FirmsLayer (NASA VIIRS Thermal Anomalies 375m)
        buildings.js          # BuildingsLayer (OSM 3D-Gebaeude, farbcodiert)
        satellites.js         # SatellitesLayer (Kreisbahnen, Orbitlinien)
        gdelt.js              # GdeltLayer (orangene News-Punkte)
        monitor.js            # MonitorLayer (OSINT-Artikel nach Lage)
        cables.js             # CablesLayer (Seekabel GeoJSON)
        infra.js              # InfraLayer (AKWs + Militaerbasen)
        nightlights.js        # NightlightsLayer (NASA VIIRS Black Marble NRT)
        celltowers.js         # CelltowersLayer (viewport-basiert, Overpass)
        iss.js                # ISSLayer (Echtzeit-Position)
        weather.js            # WeatherLayer (RainViewer Regenradar)
        terminator.js         # TerminatorLayer (Tag/Nacht-Grenze)
        timezones.js          # TimezonesLayer (24 UTC-Linien)
        overpass.js           # OverpassLayer (Renderer fuer VLM-Ergebnisse)
        visualmodes.js        # VisualModes (STD/NVG/FLIR/CRT)
      ui/
        vlm.js                # VlmUI (Drag&Drop Upload, Analyse, Overpass-Kopplung)
        geoint.js             # GeointTools (Sonnenstand, Hoehenprofil)
        imagery.js            # ImagerySwitch (13 Quellen inkl. NASA GIBS)
        sidebar.js            # Sidebar (rechts, Datenpunkt-Uebersicht)
        search.js             # SearchUI (Nominatim + City Quick-Links)
        crosshairs.js         # CrosshairsUI (Fadenkreuz-Overlay)
```

## Datenquellen & Layer

| Layer | Quelle | Refresh | Menge |
|-------|--------|---------|-------|
| Flugverkehr | adsb.lol (Fallback: adsb.one) | 12s | ~10.000+ |
| Militaerflug | adsb.lol /v2/mil | 15s | ~190 |
| Schiffsverkehr | AISStream.io WebSocket | Echtzeit | ~15.000+ |
| Nachrichten | GDELT GEO 2.0 | 60s | ~200 |
| Katastrophen | NASA EONET v3 + USGS | 10min | ~50-100 |
| Feuer (VIIRS) | NASA GIBS WMTS (Thermal Anomalies 375m) | Taeglich | Overlay |
| 3D-Gebaeude | Cesium Ion OSM Buildings | Statisch | Weltweit |
| Satelliten | CelesTrak TLE | 1h | ~500 |
| Seekabel | submarinecablemap.com | 24h | GeoJSON |
| AKWs/Basen | Overpass API | 24h | Punkte |
| ISS | open-notify.org | 5s | 1 |
| Nachtlichter | NASA VIIRS Black Marble NRT | Taeglich | Overlay |
| Funkmasten | Overpass API (viewport-basiert) | On-Demand | Variabel |
| Regenradar | RainViewer | 5min | Overlay |
| Monitor OSINT | AegisSight Monitor API | 2-5min | Nach Lage |

## Satellitenbilder (Imagery Switcher)

| Quelle | Typ | Update | Auth |
|--------|-----|--------|------|
| Cesium Ion (Standard) | Default Base Layer | - | Ion Token |
| Esri World Imagery | URL-Template | Statisch | Keine |
| NASA MODIS Terra (Heute) | GIBS WMTS REST | Taeglich ~3h | Keine |
| NASA VIIRS SNPP (Heute) | GIBS WMTS REST | Taeglich ~3h | Keine |
| NASA GOES East (Live) | GIBS WMTS REST | ~10-15 Min | Keine |
| NASA GOES West (Live) | GIBS WMTS REST | ~10-15 Min | Keine |
| Sentinel-2 (2018-2024) | EOX WMTS | Jaehrlich | Keine |
| OpenTopoMap | URL-Template | Statisch | Keine |
| OpenStreetMap | URL-Template | Laufend | Keine |

NASA GIBS Layer nutzen REST-URL mit Datum im Pfad (wie nightlights.js):
`https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/{Layer}/default/{Date}/{TileMatrixSet}/{TileMatrix}/{TileRow}/{TileCol}.{ext}`

## UI-Architektur

### Layer-Panel (links, einklappbar)
5 Gruppen mit Auf-/Zuklapp-Funktion und Aktiv-Zaehler:
- **ECHTZEIT** (gruen): Flugverkehr, Militaerflug, Schiffsverkehr
- **INTELLIGENCE** (orange): Nachrichten, Katastrophen, Feuer (VIIRS)
- **GEOINT** (lila): Bildanalyse, Nachtlichter, Funkmasten, Sonne/Hoehe
- **INFRASTRUKTUR** (gelb): Satelliten, Seekabel, AKWs/Basen, ISS, 3D-Gebaeude
- **UMGEBUNG** (blau): Regenradar, Tag/Nacht, Terminatur, Zeitzonen

Immer sichtbar: Satellitenbilder-Dropdown (oben), Fadenkreuz + Ortsnamen (unten), Koordinaten

### Bottom Bar
Visual Modes (STD/NVG/FLIR/CRT) links, Stats rechts

### Rechte Sidebar
Datenpunkt-Uebersicht mit Sections, FlyTo bei Klick, 5s Auto-Update

## VLM-Bildanalyse

### Workflow
1. Bild hochladen (Drag&Drop, PNG/JPG/WEBP, max 10MB)
2. Claude Code headless (Sonnet, --json-schema) analysiert das Bild
3. Ergebnis: Szene, Objekte, Terrain, geschaetzte Koordinaten, Landschaftsmerkmale
4. User waehlt Objekte aus -> Overpass-Queries werden generiert
5. OSM-Treffer werden auf dem Globe gerendert + Suchbereich visualisiert

### Prompt-Regeln
- objects-Array: NUR OSINT-relevante Infrastruktur (Flughaefen, Militaer, Haefen, etc.)
- Generische Natur (forest, mountain, farmland) gehoert in terrain/landscape_clues
- Bei reinen Landschaftsfotos: objects = [] (leeres Array)
- Frontend zeigt "Keine OSINT-relevante Infrastruktur erkannt" und graut Button aus

### BBox-Aufloesung (Prioritaet)
1. EXIF-GPS (verifiziert)
2. estimated_coordinates mit confidence_radius_km
3. identified_features (Gewaesser, Region -> _REGION_BBOX)
4. estimated_location_type (Kontinent/Region)
5. Weltweit (kein BBox)

### Overpass-Integration
- Nur ueber VLM erreichbar (kein standalone)
- 30+ OSINT-Templates in 6 Kategorien
- _OBJECT_TO_OVERPASS: ~35 Objekttypen -> OverpassQL-Tags
- Generische Tags (building, highway, landuse) werden gefiltert
- Rate-Limit 10s, Cache 5min, Fallback-Server

## 3D-Gebaeude

- Cesium Ion OSM Buildings Tileset (createOsmBuildingsAsync)
- Farbcodiert: Militaer (rot), Industrie (orange), Regierung/Oeffentlich (blau), Rest (grau)
- Toggle in Gruppe INFRASTRUKTUR

## 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

## Bidirektionale Monitor-Verbindung

### Globe -> Monitor (Auto-Push)
- data_push.py sendet alle 10min NASA EONET + USGS M4.5+ an Monitor
- Ziel-Lage: ID 45 (Naturkatastrophen international)
- Duplikat-Check per Headline im Monitor

### Monitor -> Globe (Feed)
- /api/public/globe-feed?incident_id=X liefert GeoJSON
- Lage-Auswahl im Globe-Header bestimmt welche Daten angezeigt werden

## Auth-System

- Magic Link Login: E-Mail -> Link per Mail -> JWT
- Prueft: users.is_active=1 UND users.globe_access=1
- JWT-Tokens: 24h Gueltigkeit, akzeptiert auch Monitor-Tokens (Cross-Service)
- Alle Daten-APIs hinter Auth-Middleware

## Rendering-Architektur

### Performance
- Flugzeuge/Schiffe: PointPrimitiveCollection (GPU-beschleunigt)
- Zoom-adaptiv: Cluster bei Uebersicht, Einzelpunkte bei Detail
- Katastrophen/Satelliten: Entity API (kleinere Mengen)
- 3D-Gebaeude: Cesium3DTileset (Streaming, LOD)

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

## Services neustarten

```bash
sudo systemctl restart globe.service
systemctl status globe.service --no-pager
journalctl -u globe -f  # Live-Logs
```

## Entwicklungshinweise

- **CLAUDE.md aktuell halten:** Nach JEDER Aenderung (neue Dateien, Layer, Features, Strukturaenderungen) diese Datei aktualisieren. Sie ist die zentrale Referenz fuer alle Sessions.
- Alle JS-Dateien werden als statische Dateien ausgeliefert (kein Build-Step)
- Cache-Busting: Browser-Cache manuell mit Ctrl+Shift+R leeren
- JS-Syntax pruefen: node --check ~/AegisSight-Globe/static/js/layers/DATEI.js
- Python-Syntax: ~/.venvs/globe/bin/python -c 'import py_compile; py_compile.compile("src/DATEI.py", doraise=True)'
- Inkrementelle Patches vermeiden — bei groesseren Aenderungen Datei komplett neu schreiben
- .env Aenderungen erfordern Service-Restart
- NASA GIBS WMTS: Kostenlos, kein API-Key, kein Rate-Limit, CORS offen

## Bekannte Limitierungen

- Cesium Ion Free-Tier: Nicht fuer kommerziellen Vertrieb (Commercial License noetig)
- Satelliten-Positionen: Vereinfachte Kepler-Berechnung (nicht SGP4-exakt)
- AISStream: Schiffsdaten brauchen ~1-2min bis globale Abdeckung nach Restart
- NASA GIBS NRT-Layer: Tagesaktuelle Bilder haben ~3-12h Verzoegerung
- VLM-Bildanalyse: Max 1 gleichzeitig (Semaphore), Timeout 90s