> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pharen.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Lokales Setup und Contribution
> Richte das Pharen Hub Monorepo mit Django, Nuxt und Nx lokal ein, führe Quality Checks aus und arbeite mit denselben Regeln wie Maintainer und Agents.
Diese Seite ist für alle, die am Pharen Hub Code arbeiten.
Das Repo ist ein Monorepo mit Django, Celery, PostgreSQL, Nuxt, Vue, TypeScript, Tailwind und Nx. Das ist viel Technik. Der lokale Workflow soll trotzdem einfach bleiben: Make-Befehle nutzen, Änderungen klein halten und Nx die Frontend-Tasks steuern lassen.
## Repo-Struktur
Das App-Repo heißt `PharenIT/ELEV8-Labs`.
```text theme={null}
src/apps/app-server/ Django Backend, API, Celery Tasks, Tests
src/apps/hub/ Nuxt Hub App
src/apps/realtime-service/ Realtime Collaboration Service
src/packages/ Geteilte Frontend Packages
src/nx.json Nx Workspace Konfiguration
Makefile Hauptoberfläche für lokale Befehle
.quality-rules.json Regeln für Datei- und Symbolgrößen
scripts/quality-guardrails.mjs
```
## Wichtigste Regel
Nutze Make-Befehle aus dem Repo Root.
```bash theme={null}
make up
make down
make restart
make logs
make lint
make test
make quality
```
Rufe Docker, pnpm, uv, pytest oder Nx nicht direkt auf, außer du debugst den Wrapper selbst. Das Makefile hält Docker-Services, Node-Tooling, Backend-Umgebungen und Nx-Targets zusammen.
## Erstes lokales Setup
Nutze Node 22, pnpm 9, Python 3.12, Docker und Docker Compose.
Wenn du `nvm` nutzt, installiere die Version aus der `.nvmrc`, bevor du Frontend-Abhängigkeiten installierst.
Kopiere die Beispiel-Datei, falls dein Checkout noch keine `.env` hat.
```bash theme={null}
cp .env.example .env
```
Starte die lokalen Services:
```bash theme={null}
make up
```
Bereite die Datenbank vor:
```bash theme={null}
make migrate
```
Für lokale Frontend-Entwicklung:
```bash theme={null}
TMPDIR=/tmp make serve
```
Das kurze `TMPDIR` verhindert auf macOS ein Nuxt/Vite-Socket-Problem, bei dem der Dev Server sonst HTTP 500 zurückgeben kann.
## Schneller Entwicklungsloop
Nutze beim Coden den kleinsten sinnvollen Check.
Für Frontend-Packages:
```bash theme={null}
make nx PKG=@pharen/chat T=test
make nx PKG=@pharen/chat T=lint
make nx PKG=@pharen/chat T=typecheck
```
Für Backend-Änderungen:
```bash theme={null}
make test-backend-file FILE=api/agents/tests/test_run_service.py
make test-backend-paths PATHS="api/agents api/workspace"
```
Für einen committed Branch, den Nx mit einer Base vergleichen kann:
```bash theme={null}
make affected B=origin/test H=HEAD
```
Vor Übergabe oder Pull Request:
```bash theme={null}
make quality
```
## Quality Guardrails
Pharen hat ausführbare Regeln für Dateigrößen und Python-Funktions- oder Klassengrößen. Sie existieren, weil große Dateien schnell entstehen, wenn Menschen oder Agents unter Zeitdruck arbeiten.
Starte sie so:
```bash theme={null}
make quality-rules
```
Das ruft ein Nx Target auf:
```bash theme={null}
cd src
pnpm exec nx run pharen-hub:quality-rules
```
Das Target startet `scripts/quality-guardrails.mjs` und liest `.quality-rules.json`.
### Wie die Regeln funktionieren
Jede Regel hat zwei Werte:
* `target`: gewünschte Größe. Darüber gibt es eine Warnung.
* `max`: harte Grenze. Neue Änderungen darüber schlagen fehl.
Dateien, die schon vorher zu groß waren, dürfen nur geändert werden, wenn sie nicht noch größer werden. So blockiert alter Code nicht jede Änderung, wächst aber auch nicht weiter.
## Größenregeln
Standard-Erwartungen:
* Backend-Dateien bleiben ungefähr bei 300 Zeilen und unter 500 Zeilen.
* Backend-Funktionen bleiben unter 40 Zeilen.
* Backend-Klassen bleiben unter 200 Zeilen.
* Vue-Dateien bleiben unter 500 Zeilen.
* Frontend-Composables und Services bleiben unter 300 Zeilen.
* Frontend-Stores bleiben unter 400 Zeilen.
* Testdateien dürfen größer sein, sollten aber nach Verhalten oder Verträgen gesplittet werden.
Splitte nach Verantwortung, nicht nach beliebiger Zeilenzahl.
## Wo Code hingehört
Backend-Änderungen folgen diesem Pfad:
```text theme={null}
model -> serializer -> service -> view -> url -> test -> migrate
```
Grenzen:
* Views kümmern sich um Request und Response.
* Services schreiben Daten und führen Side Effects aus.
* Selectors lesen Daten und formen Queries.
* Tasks kümmern sich um async Ausführung und Retries.
* Tests prüfen Rechte, Tenant Scope, Validierung, Status Codes und Response-Verträge.
Frontend-Änderungen folgen diesem Pfad:
```text theme={null}
types -> mapper/service/composable -> component -> page
```
Grenzen:
* Services sprechen mit APIs und externen Systemen.
* Mappers wandeln API-Daten in Frontend-Daten um.
* Composables halten State und User Actions.
* Components rendern UI und senden Events.
* Pages verbinden Route, Daten und Layout.
## Contribution-Checkliste
Vor Pull Request oder Übergabe:
Vermeide fremde Refactors. Wenn eine große Datei gesplittet wird, dann entlang einer echten Verantwortung.
Starte die kleinsten Frontend- oder Backend-Checks, die zum geänderten Bereich passen.
Starte `make quality-rules`, wenn du Dateien hinzufügst, Dateien splittest oder große Module berührst.
Starte `make quality`. Für breite Dependency-, Package- oder Config-Änderungen nutze `QUALITY_FORCE_ALL=1 make quality`.
Wenn ein wiederkehrender lokaler Fehler nichts mit deiner Änderung zu tun hat, dokumentiere ihn in `.Agents.md`.
Review-Agents sind opt-in. Nutze Quality-, Security-, Performance- oder Pre-Push-Review-Agents nur, wenn jemand diesen Review ausdrücklich will oder wenn ein Push beziehungsweise Pull Request vorbereitet wird.