backend/: HTTP-API, Auth/JWT-Validierung, RBAC, DB-Zugriff und Proxmox-Orchestrierung
worker/: asynchrone Jobs fuer Proxmox-Tasks, Reconciliation und Cleanup
console-proxy/: Websocket-Proxy fuer noVNC/xterm.js ohne direkte Proxmox-Verbindung im Browser
platform/: gemeinsame Go-Bausteine fuer Konfiguration, Logging und spaetere Querschnittsfunktionen
frontend/: React/TypeScript/Vite-App fuer Kunden- und Admin-Workflows
migrations/: versionierte SQL-Migrationen
deploy/: lokale und spaetere Deployment-Artefakte

Lokales Setup

Go >= 1.22 installieren.
Node.js >= 20 und npm installieren.
Docker Desktop oder kompatible Docker Engine installieren.
.env.example nach .env kopieren und lokale Werte setzen.
Abhaengigkeiten installieren: npm install --prefix frontend.
Go-Abhaengigkeiten installieren: go work sync.
Lokale Infrastruktur starten: make dev.
Migrationen ausfuehren: make migrate.
Backend starten: go run ./backend/cmd/api.
Console-Proxy starten: go run ./console-proxy/cmd/console-proxy.
Frontend starten: npm run dev --prefix frontend.

Supabase self-hosted liegt unter deploy/supabase/. Die lokale deploy/supabase/.env wird aus der offiziellen Vorlage erzeugt und nicht committed. Fuer App-.env die Werte POSTGRES_PASSWORD, ANON_KEY und SERVICE_ROLE_KEY aus deploy/supabase/.env uebernehmen.

Migrationen nutzen MIGRATE_DATABASE_URL, falls gesetzt. Andernfalls wird DATABASE_DIRECT_URL aus .env oder eine lokale Supavisor-URL aus deploy/supabase/.env verwendet.

Das Backend validiert Supabase-JWTs ueber SUPABASE_JWKS_URL und SUPABASE_ISSUER. Fuer das lokale Self-Hosted-Setup mit leerem JWKS wird zusaetzlich SUPABASE_JWT_SECRET als HS256-Fallback genutzt. Beim ersten authentifizierten Request synchronisiert das Backend den Supabase-User lazy nach public.profiles.

Cluster-Tokens werden mit AES-256-GCM verschluesselt. MASTER_KEY_BASE64 muss ein base64-kodierter 32-Byte-Key sein, zum Beispiel erzeugt mit openssl rand -base64 32. Ohne gueltigen Master-Key bricht der Backend-Start ab.

Das Cluster-Repository speichert Proxmox-Token-Secrets nur als Ciphertext in public.clusters.encrypted_token. Entschluesselte Tokens bleiben interne Runtime-Daten und werden nicht in API-DTOs dokumentiert.

Lokale Dienste:

Supabase API Gateway: http://localhost:8000
Supabase Studio: http://localhost:8000/project/default
Supavisor Session Pooler: localhost:5432
Supavisor Transaction Pooler: localhost:6543

Aktuelle Targets:

make test: Go-Tests
make build: Go-Builds
make frontend-build: Frontend-Production-Build
make lint: Go Vet und Frontend-ESLint
make verify: Lint, Tests und Builds
make dev-down: Supabase-Stack stoppen
make dev-logs: Supabase-Logs verfolgen
make migrate: Migrationen auf den aktuellen Stand bringen
make migrate-down: letzte Migration zurueckrollen
make migrate-version: aktuelle Migrationsversion anzeigen

Backend-Endpunkte:

GET /healthz: oeffentlicher Healthcheck
GET /me: geschuetzt, synchronisiert profiles und gibt den authentifizierten Principal aus dem JWT zurueck
GET /tenants/{tenantID}/membership: geschuetzt, synchronisiert profiles, prueft Tenant-Mitgliedschaft und gibt Rolle/Tenant zurueck

Tenant-gescoped Backend-Routen laufen ueber JWT-Auth, Profil-Sync, Membership-Resolver und deklarative RBAC-Pruefung.

Frontend-Prototyp:

Supabase Login/Registrierung ueber VITE_SUPABASE_URL und VITE_SUPABASE_ANON_KEY
Backend-Profilcheck ueber GET /me
Platzhalter-Ansichten fuer Projekte, VMs, SSH-Keys, Audit und Konsole

CI

Forgejo Actions laufen unter .forgejo/workflows/ci.yml.

verify: installiert Go/Node-Abhaengigkeiten und fuehrt make verify aus.
secret-scan: fuehrt zricethezav/gitleaks:v8.28.0 mit .gitleaks.toml aus. Die Konfiguration erlaubt nur dokumentierte Beispielwerte aus den offiziellen Supabase-Upstream-Dateien.

Sicherheitsregeln

Nur Backend, Worker und Console-Proxy sprechen mit Proxmox.
Proxmox-Tokens werden nie im Frontend sichtbar und nie unverschluesselt gespeichert.
Tenant-bezogene Queries muessen immer tenant-gefiltert sein.
Secrets gehoeren in .env oder einen Secret-Manager, nie ins Repo.