Surfwinddata
Surfwinddata ist eine Full-Stack-Anwendung für Wassersport-Spots,
Wettervorhersagen und Reiseplanung. Das Repository enthält die öffentliche
Website, das getrennt gebaute Admin-Dashboard, die FastAPI sowie Offline- und
Worker-Prozesse für Wetter-, Geodaten- und Gezeitenprodukte.
Dieses Repository ist die einzige kanonische Entwicklungsquelle. Das frühere
Repository surfwinddata wird nicht mehr gespiegelt. Beide Vercel-Projekte
werden aus diesem Repository gebaut.
Funktionsumfang
- öffentlicher Spot- und Regionenkatalog mit Karte und Suche
- Live-Wetter und stündliche Vorhersage für alle zehn Forecast-Tage
- saisonale Windklimatologie, Spot-Vergleiche und Alternativen
- öffentliche Konten, Favoriten und Community-Beiträge
- rollen- und sitzungsbasiertes Admin-Dashboard für Katalog, Medien,
Moderation, Nutzer und Betriebsaufgaben
- versionierte PostgreSQL/PostGIS-Migrationen sowie Redis-Caches
- getrennte Public- und Admin-Builds mit fail-closed API-Routing
Die laufende API-Dokumentation ist lokal unter /docs verfügbar. Eine statische
Aufzählung aller Routen im README wird bewusst vermieden, damit OpenAPI die
maßgebliche Schnittstellenbeschreibung bleibt.
Architektur
React/Vite browser
-> FastAPI (app/main.py)
-> PostgreSQL/PostGIS
-> Redis
-> weather, tide, geodata and media providers
Wichtige Einstiegspunkte:
Voraussetzungen
- Python 3.11 oder neuer
- Node.js 22
- Docker mit Compose für PostgreSQL/PostGIS und Redis
Lokale Einrichtung
-
Infrastruktur starten:
docker compose up -d db redis
-
Python-Umgebung erstellen und Abhängigkeiten installieren:
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
-
Lokale Konfiguration anlegen:
Copy-Item .env.example .env
Die Vorlagen enthalten ausschließlich lokale oder beispielhafte Werte.
Echte Secrets gehören in lokale Umgebungsvariablen beziehungsweise in die
Secret Stores von GitHub und Vercel und dürfen nie committed werden.
-
Schema migrieren und optionale Beispieldaten laden:
$env:DATABASE_URL='postgresql+psycopg://surf:surf@localhost:5432/surfwind'
alembic upgrade head
python -m app.seed.seed
-
Backend und Frontend in getrennten Terminals starten:
python -m uvicorn app.main:app --reload
npm --prefix frontend ci
npm --prefix frontend run dev
Lokale Standardports sind 8000 für die API, 5173 für Vite, 5432 für
PostgreSQL und 6379 für Redis.
Prüfungen
Für normale Änderungen zuerst den passenden fokussierten Check ausführen:
./scripts/check.ps1 frontend
./scripts/check.ps1 backend
./scripts/check.ps1 changed
Einzelne Prüfungen:
pytest -q
npm --prefix frontend run lint
npm --prefix frontend test
npm --prefix frontend run build
npm --prefix frontend run test:e2e
python -m pip_audit -r requirements.txt
npm --prefix frontend audit --audit-level=high
Die GitHub-CI prüft Backend, Frontend, Browser-Flows, Migrationen,
Abhängigkeiten und das Git-History-Secret-Scanning. Dependabot übernimmt
laufende Dependency-Aktualisierungen. Der CodeQL-Workflow wird über die
Repository-Variable CODEQL_ENABLED=true aktiviert, sobald GitHub Code Scanning
für die Repository-Sichtbarkeit beziehungsweise den Tarif verfügbar ist.
Deployment
Aus einem Commit entstehen zwei getrennte Vercel-Projekte:
| Projekt | Build | API |
|---|
| Public | öffentliche SPA ohne Admin-Code | Public- und Community-Routen |
| Admin | Dashboard-Bundle | zusätzlich Auth- und Admin-Routen |
Die Build- und Runtime-Schalter sowie die notwendigen Umgebungsvariablen sind in
DEPLOY-VERCEL.md beschrieben. Produktionsmigrationen laufen
nur über den geschützten Recovery-Workflow und die production-Umgebung.
Dokumentation
Historische Spezifikationen und Audits dokumentieren Entscheidungen, sind aber
keine aktuelle API- oder Betriebsreferenz.
Sicherheit und Lizenz
Sicherheitslücken bitte nach SECURITY.md vertraulich melden.
Produktionsdaten, Zugangsdaten und Laufzeitberichte gehören nicht in Git.
Der eigene Projektcode ist proprietär; siehe LICENSE. Hinweise und
Lizenztexte für Drittanbieter befinden sich in
THIRD_PARTY_NOTICES.md.
