StaySense (MVP NRW)

StaySense bewertet fuer die Nacht (22:00-06:00) die voraussichtliche Ruhe eines Spots in NRW (Pilot: Kreis Mettmann).

MVP Status

Implementiert:

• Night Safety Score (0-100) mit Ampel (green, yellow, red)
• Begruendung mit Top-Faktoren (OSM-Typ, Distanz-POIs, Zeitlogik, Events, Community)
• API: GET /spot/score, POST /spot/signal
• Kartenwahl via OpenStreetMap (Leaflet), inkl. Klickauswahl und Ortssuche
• API: GET /geocode/search (Nominatim-Proxy), GET /map/tile/{z}/{x}/{y}.png (OSM-Tile-Proxy)
• PWA-Basis (Manifest, Service Worker, iOS-Standalone-Meta, Offline-Shell)
• Admin-Bereich (Setup/Login, geschuetzt per User/Passwort + Session-Token)
• Admin-API fuer Uebersicht und Event-Verwaltung (/admin/*)
• Anti-Spam ohne Account: lokaler Token + serverseitiger HMAC-Hash
• Quick Decision UI mit Signal-Buttons
• Offline-First im Frontend: Score-Cache + Signal-Queue
• Echter OSM-Import via Overpass (POIs, Landuse-Zonen, Highway-Typen)
• OpenData-Connectoren (CSV/JSON aus URL oder Datei)
• Automatischer Import-Job-Runner (once oder daemon)

Nicht im MVP:

• Accounts/Login
• Chat/Kommentare
• Stellplatz-Portal
• Routenplanung

Start

1. Datenbank initialisieren:
   • cd StaySense/backend
   • python3 -c "from db import init_db; init_db()"
2. OSM importieren (Pilot-BBox Mettmann):
   • python3 import_osm_overpass.py
3. OpenData-Connectoren aus Konfig ausfuehren:
   • python3 run_import_jobs.py --config ../docs/open_data_sources.json --prune-legacy
4. Optional: periodische Imports (alle 6h) inkl. OSM:
   • python3 run_import_jobs.py --config ../docs/open_data_sources.json --with-osm --prune-legacy --daemon --interval-seconds 21600
5. API starten:
   • python3 server.py
6. Frontend starten (zweites Terminal):
   • cd ../src
   • python3 -m http.server 8080
7. App oeffnen:
   • http://localhost:8080
8. PWA-Test:
   • iOS Safari: Seite aufrufen -> Teilen -> "Zum Home-Bildschirm"
   • Danach aus Home-Screen starten (Standalone-Modus)

OpenData Connector Config

Datei: docs/open_data_sources.json

• enabled: Quelle aktivieren/deaktivieren
• format: csv oder json
• url oder file: Quelle
• field_map: Mapping auf StaySense-Felder
• event_type_map: optionale Typ-Normalisierung
• json_path: Pfad auf Array bei JSON-Feeds
• Validierung aktiv:
  • Koordinaten muessen in DE-Bounds liegen
  • start_datetime < end_datetime
  • Event-Typ muss auf market|waste|event|construction normalisiert werden

Live-Beispiel fuer echte NRW-OpenData-Quellen:

• Datei: docs/open_data_sources_nrw_live.json
• Enthalten:
  • Koeln Verkehrsbeeintraechtigungen (ArcGIS JSON)
  • Koeln Baustellen Notfall (WFS GeoJSON)
• Import:
  • cd StaySense/backend
  • python3 run_import_jobs.py --config ../docs/open_data_sources_nrw_live.json --prune-legacy

Tests

• Backend Unit-Tests:
  • cd StaySense/backend
  • python3 -m unittest discover -s tests -p \"test_*.py\"

API Beispiele

Score holen:

• curl "http://127.0.0.1:8787/spot/score?lat=51.25&lon=6.97&at=2026-02-15T20:00:00Z"

Signal senden:

• curl -X POST "http://127.0.0.1:8787/spot/signal" -H "Content-Type: application/json" -d '{"spot_id":"<ID>","signal_type":"noise","device_token":"<uuid-v4>","timestamp":"2026-02-15T20:15:00Z"}'

Ortssuche:

• curl "http://127.0.0.1:8787/geocode/search?q=Mettmann%20Bahnhof"

Tile-Proxy:

• curl -I "http://127.0.0.1:8787/map/tile/12/2149/1387.png"

Admin-Setup (nur beim ersten Start):

• curl -X POST "http://127.0.0.1:8787/admin/bootstrap" -H "Content-Type: application/json" -d '{"username":"admin","password":"<starkes-passwort>"}'

DSGVO-Hinweise im MVP

• Kein Login
• Keine IP-Speicherung in der Anwendung
• Kein Device Fingerprinting
• Missbrauchsschutz nur ueber hashed_device = HMAC_SHA256(device_token, server_salt)

Attribution (Rechtliches)

Unter Attribution muessen die verwendeten Datenquellen und Lizenzen klar genannt werden:

• OpenStreetMap-Mitwirkende + ODbL-Hinweis
• Geocoding-Dienst (Nominatim) als Quelle
• Jede OpenData-Quelle mit Lizenzhinweis (z. B. Datenlizenz Deutschland Zero/By)

In der App ist dafuer die Seite quellen.html vorgesehen.

Produktion

• STAYSENSE_SERVER_SALT zwingend als geheimes Env setzen
• HTTPS-only bereitstellen
• OpenStreetMap-/Open-Data-Attribution in App verpflichtend sichtbar halten

Doku Uebersicht

• Architektur / Umsetzung: docs/IMPLEMENTATION_PLAN.md
• Server-Deployment (Linux + Nginx + systemd): docs/DEPLOYMENT.md
• CloudPanel-Setup (Hetzner): docs/CLOUDPANEL_SETUP.md
• Betrieb / Runbook: docs/OPERATIONS.md
• GitHub Publish Ablauf: docs/GITHUB_PUBLISH.md
• Connector-Konfiguration: docs/open_data_sources.json
• Event-Template: docs/open_data_events_template.csv