CLAUDE.md: Vollstaendige Entwicklungsdokumentation
Dieser Commit ist enthalten in:
Claude Dev
168
CLAUDE.md
Normale Datei
168
CLAUDE.md
Normale Datei
@@ -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
|
||||
In neuem Issue referenzieren
Einen Benutzer sperren