Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/README.md
T
2026-07-08 16:15:37 +02:00

111 lines
4.1 KiB
Markdown

# 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.
![coverage](https://img.shields.io/badge/coverage-see%20ci-blue)
## Zuerst lesen
- [`AGENTS.md`](AGENTS.md) ist die zentrale Arbeitsregel fuer Coding-Agents und Menschen, inklusive Ticket-Scope, Plane-Tracking, DoD, Prisma-Regeln und EU-Stack.
- [`CLAUDE.md`](CLAUDE.md) ist der Claude-Code-Einstieg und importiert `AGENTS.md`, damit Claude dieselben Projektregeln nutzt.
- [Ticket-Docs README](.planning/ticket-docs/README.md) beschreibt den Einstieg in ein Ticket.
- [Entity Model](.planning/ENTITY-MODEL.md) ist die Datenmodell-Quelle der Wahrheit, besonders fuer P6-P9.
- [Architecture Decisions](docs/ARCHITECTURE-DECISIONS.md) dokumentiert verbindliche Architekturentscheidungen.
- [Agent Checklist](docs/AGENT-CHECKLIST.md) 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
```sh
corepack enable
corepack prepare pnpm@10.33.0 --activate
pnpm install
```
Mit Zugriff auf die geteilten Dev-Secrets:
```sh
pnpm env:pull
```
Ohne Secrets fuer eine lokale Wegwerf-Umgebung:
```sh
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:
```sh
pnpm exec prisma migrate dev
pnpm seed
pnpm run permissions:sync
```
Web-App starten:
```sh
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:
```sh
pnpm typecheck
pnpm lint
pnpm test
```
Je nach Aenderung zusaetzlich die passenden `verify:*`-Gates aus der Agent-Checkliste. Haeufig relevant:
```sh
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](docs/deployment.md), [Database](docs/database.md), [Worker](docs/worker.md), [Mail](docs/mail.md), [Observability](docs/observability.md) und [Troubleshooting](docs/troubleshooting.md).
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.