HiveGrid Cloud ist die Produkt-Codebase fuer HiveGrid 2.0. Das Repo basiert historisch auf der HiveGrid-SaaS-Basis, wird aber als bespoke HiveGrid-Anwendung weitergebaut. Neue Arbeit passiert ticket-getrieben und muss den Projektregeln, dem gesperrten Entity-Modell und den Architekturentscheidungen folgen.

Codeumfang

Der Verlauf zaehlt nicht-leere Quellcodezeilen auf dem First-Parent-Pfad von main. Ausgangspunkt ist der Fork-/Code-Import vom 04.06.2026; die importierte Codebasis wird deshalb als Baseline und nicht als Wachstum gewertet. Die CSV-Rohdaten werden nach jedem Push auf main aktualisiert. Lokal laesst sich der Graph mit pnpm metrics:loc-history neu erzeugen; die Regeln stehen im Generator.

Die Commit-Aktivitaet zeigt die letzten 60 Kalendertage bis zur veroeffentlichten main-Revision. Gezaehlt werden alle von main erreichbaren Commits nach Berliner Kalendertag, inklusive Merge- und Branch-Commits; Tage ohne Commit bleiben als Null-Tage sichtbar. Die CSV-Rohdaten und das SVG werden mit jedem LOC-Lauf aktualisiert. Lokal laesst sich der Graph mit pnpm metrics:commit-history neu erzeugen; die Regeln stehen im Generator.

Zuerst lesen

AGENTS.md ist die zentrale Arbeitsregel fuer Coding-Agents und Menschen, inklusive Ticket-Scope, Plane-Tracking, DoD, Prisma-Regeln und EU-Stack.
CLAUDE.md ist der Claude-Code-Einstieg und importiert AGENTS.md, damit Claude dieselben Projektregeln nutzt.
Ticket-Docs README beschreibt den Einstieg in ein Ticket.
Entity Model ist die Datenmodell-Quelle der Wahrheit, besonders fuer P6-P9.
Architecture Decisions ist das kompakte Register mit AD-IDs, Gründen und Status; die operativen Regeln stehen in AGENTS.md.
Agent Checklist ist vor Commit und Push abzuarbeiten.

Arbeitsmodus

Gebaut wird nach Plane-Tickets und den zugehoerigen Ticket-Docs. AGENTS.md besitzt die repo-weiten Architektur- und Sicherheitsregeln, das Entity Model besitzt das Datenmodell, die Ticket-Doc besitzt Scope und DoD. Aeltere Specs sind nur historische Quellen.

Wichtig fuer neue Arbeit:

Strikt im Ticket-Scope bleiben.
DoD-Fortschritt als Prozent der Ticket-DoD melden.
UI-Routen importieren keine Subframe-Outputs direkt, sondern gehen ueber den Adapter-Layer.
Neue Fachmodelle werden typisiert in Prisma gebaut; der generische Entity-Builder ist Altlast und bekommt keine neuen Konsumenten.
Prisma-Modelle gehoeren in modulbezogene Dateien im Schema-Ordner.
US-Provider und Social-Login-Provider sind fuer HiveGrid nicht erlaubt.

Repo-Aufbau

apps/web enthaelt die React-Router-Web-App.
apps/api enthaelt die externe API.
apps/worker enthaelt Queue- und Hintergrundjobs.
packages/* enthaelt geteilte Runtime-, UI-, Config-, DB-, Mail- und View-Model-Pakete.
prisma/schema enthaelt das modulare Prisma-Schema.
docs und .planning enthalten Projektentscheidungen, Ticket-Docs und operative Runbooks.

Lokales Setup

Voraussetzungen: Node 24.18.0 (.nvmrc), Docker (fuer Postgres/Redis/ClamAV) und pnpm ueber corepack.

1. Abhaengigkeiten

corepack enable
corepack prepare pnpm@11.12.0 --activate
pnpm install

2. Infrastruktur starten

pnpm dev:services      # Postgres (pgvector) :5432, Redis :6379, ClamAV :3310
pnpm dev:services:mark-local # einmalig fuer ein bereits bestehendes lokales Postgres-Volume
pnpm dev:services:down # wieder stoppen

Alle drei binden nur auf 127.0.0.1. Zwei Dinge, die sonst Zeit kosten:

ClamAV laedt beim allerersten Start rund 250 MB Signaturen, bevor er auf Verbindungen hoert. Bis docker compose ps ihn als healthy zeigt, schlaegt jeder Upload mit Malware-Gate fehl (Profilbild, HR-Dokumente) — der Scan ist bewusst fail-closed, ein nicht erreichbarer Scanner ist eine Ablehnung, keine Ausnahme.
Meilisearch wird nur fuer die Volltextsuche gebraucht und ist deshalb nicht in dev:services: docker compose up -d meilisearch.

3. .env anlegen

Ohne Zugriff auf die geteilten Secrets — die Defaults aus .env.example passen genau zu pnpm dev:services:

cp .env.example .env

Mit Zugriff auf die geteilten Dev-Secrets (SOPS+age, siehe secrets/README.md):

pnpm env:pull

pnpm env:pull ueberschreibt .env komplett — auch DATABASE_URL. Der geteilte Blob zeigt auf einen PgBouncer (:6432), der lokal nicht laeuft (infra/pgbouncer/userlist.txt liegt nicht im Repo). Nach env:pull deshalb lokal auf die direkte Verbindung stellen: DATABASE_URL="postgres://hivegrid:hivegrid@127.0.0.1:5432/hivegrid".

Adressen konsequent als 127.0.0.1, nicht localhost: auf Windows loest localhost zuerst nach ::1 auf, waehrend die Container nur auf IPv4 veroeffentlichen.

4. Datenbank aufsetzen

pnpm dev:db:roles          # einmalig: RLS-Rollen anlegen
pnpm run db:migrate:deploy
pnpm seed
pnpm run permissions:sync

dev:db:roles muss vor der ersten Migration laufen: die RLS-Cutover-Migration vergibt Rechte an hivegrid_app/hivegrid_worker, und ohne diese Rollen bricht sie mittendrin ab und laesst die Datenbank in einem Failed-Migration-Zustand zurueck (P3009). Der Befehl ist ein lokaler Helfer, der Wegwerf-Passwoerter wuerfelt — lokal spielen sie keine Rolle, weil die App als DATABASE_URL-Besitzer verbindet und nicht als eine dieser Rollen. Staging und Produktion nutzen weiter pnpm run db:roles:provision mit verwalteten Secrets.

5. Starten

pnpm dev:local

Tenant-App: http://app.localhost:3000
Admin-App: http://admin.localhost:3000
API bei Bedarf separat: pnpm --filter @hivegrid/api dev
Login aus dem Seed: admin@email.com / password

pnpm dev:local stellt vor jedem Start den einzigen lokalen Plattform-Admin samt SuperAdmin-Rolle wieder her und setzt bei allen passwortfähigen Plattform- und Portal-Benutzern der lokalen Wegwerf-Datenbank das Passwort auf password. Passwortlose Magic-Link-Konten bleiben passwortlos. Der Guard verweigert CI-, Staging-/Production-, RLS-required-, nicht lokale und nicht explizit als wegwerfbar markierte Datenbankziele. Frische pnpm dev:services-Datenbanken tragen den Marker automatisch; fuer ein bestehendes lokales Compose-Volume ist einmalig pnpm dev:services:mark-local noetig. pnpm dev ist nur der rohe Web-Prozess ohne diesen lokalen Credential-Vertrag.

Row-Level-Security laeuft lokal auf RLS_RUNTIME_MODE=off (Default in .env.example); die Policies werden erst in Staging/Produktion erzwungen, wo die App als hivegrid_app ohne Bypass verbindet.

Verifikation

Vor Commit/Push mindestens:

pnpm typecheck
pnpm lint
pnpm test

Je nach Aenderung zusaetzlich die passenden verify:*-Gates aus der Agent-Checkliste. Haeufig relevant:

pnpm run verify:ci-baseline
pnpm run verify:env-drift
pnpm run verify:docs-links
pnpm run verify:deploy-readiness

Browser-/E2E-Pruefungen werden nur gezielt ausgefuehrt, wenn sie fuer das Ticket noetig oder explizit beauftragt sind.

Deployment

Deployment laeuft ueber Coolify und Gitea CI. Details stehen in Deployment, Database, Worker, Mail, Observability und Troubleshooting.

Produktionsdatenbank: pnpm run db:migrate:deploy fuer reviewed Migrations. Kein prisma db push gegen Production.

Hooks und CI

Lefthook wird durch pnpm install eingerichtet. Pre-commit und pre-push laufen lokal, CI wiederholt die wichtigen Gates. Bypass nur bewusst und nur kurzfristig, weil CI denselben Fehler spaeter wieder sichtbar macht.