HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud

HiveGrid Cloud

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.

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 dokumentiert verbindliche Architekturentscheidungen.
• Agent Checklist ist vor Commit und Push abzuarbeiten.

Arbeitsmodus

Wir nutzen die .planning/-Struktur als Projektgedaechtnis, aber keine GSD-Slash-Commands. Gebaut wird nach Plane-Tickets und den zugehoerigen Ticket-Docs. Wenn Ticket-Doc, Entity Model und aeltere Specs widersprechen, gewinnt das Entity Model beziehungsweise AGENTS.md.

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

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

Mit Zugriff auf die geteilten Dev-Secrets:

pnpm env:pull

Ohne Secrets fuer eine lokale Wegwerf-Umgebung:

cp .env.example .env

Danach die lokalen Werte in .env setzen. Mindestens relevant sind DATABASE_URL, SESSION_SECRET, CRYPTO_SECRET, APP_BASE_DOMAIN, WEB_APP_HOST, ADMIN_APP_HOST, API_HOST, APP_PROTOCOL und JWT_SECRET. Worker/Redis ist nur noetig, wenn Worker-Flows lokal getestet werden.

Datenbank und Seed:

pnpm exec prisma migrate dev
pnpm seed
pnpm run permissions:sync

Web-App starten:

pnpm dev

Standard lokal:

• Tenant-App: http://app.localhost:3000
• Admin-App: http://admin.localhost:3000
• API bei Bedarf separat: pnpm --filter @hivegrid/api dev

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:production-docs
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.