157 lines
8.4 KiB
Markdown
157 lines
8.4 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.
|
|
|
|
|
|
|
|
## Codeumfang
|
|
|
|
[](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/releases/download/loc-metrics/loc-history.csv)
|
|
|
|
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](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/releases/download/loc-metrics/loc-history.csv) werden nach jedem Push auf `main` aktualisiert. Lokal laesst sich der Graph mit `pnpm metrics:loc-history` neu erzeugen; die Regeln stehen im [Generator](scripts/metrics/loc-history.mjs).
|
|
|
|
[](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/releases/download/loc-metrics/commit-history.csv)
|
|
|
|
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](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/releases/download/loc-metrics/commit-history.csv) 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](scripts/metrics/commit-history.mjs).
|
|
|
|
## 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) ist das kompakte Register mit AD-IDs,
|
|
Gründen und Status; die operativen Regeln stehen in `AGENTS.md`.
|
|
- [Agent Checklist](docs/AGENT-CHECKLIST.md) 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**
|
|
|
|
```sh
|
|
corepack enable
|
|
corepack prepare pnpm@11.12.0 --activate
|
|
pnpm install
|
|
```
|
|
|
|
**2. Infrastruktur starten**
|
|
|
|
```sh
|
|
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`:
|
|
|
|
```sh
|
|
cp .env.example .env
|
|
```
|
|
|
|
Mit Zugriff auf die geteilten Dev-Secrets (SOPS+age, siehe [`secrets/README.md`](secrets/README.md)):
|
|
|
|
```sh
|
|
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**
|
|
|
|
```sh
|
|
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**
|
|
|
|
```sh
|
|
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:
|
|
|
|
```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: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.
|