docs: CLAUDE.md + agent.md für Agent-Factory Pipeline

CLAUDE.md

@@ -0,0 +1,204 @@
+# ⚠️ GOLDENE REGEL — NIEMALS RATEN. IMMER LESEN.
+
+**Nicht verhandelbar. Keine Ausnahmen.**
+
+Vor jeder Entscheidung über Feldwerte, API-Shapes, Dateinamen, Funktions-Signaturen, Konfigurationsparameter oder Architektur-Details: **erst Original lesen, dann arbeiten**.
+
+- **Referenz-Backend** (Go-Patterns, Migrations, Cluster, Packaging) → `ac_search_code(project_id=6)` oder direkt `/var/www/mail-gateway`
+- **Referenz-UI/Bootstrap** (React/AntD, i18n, Design-System, Install-Onliner) → `ac_search_code(project_id=5)` oder direkt `/var/www/netcell-webpanel`
+- **Alter Docker-Stack** (nur für Feature-Scope-Referenz!) → `ac_search_code(project_id=3)` oder `/var/www/proxy-lb-waf`
+- **Im Zweifel → Rückfrage statt Annahme.**
+
+---
+
+# EdgeGuard Native (`eg`)
+
+> Native Neufassung des Docker-basierten EdgeGuard-Stacks. Kein Docker, kein WAF in v1. Zielplattform: **Debian 13 (Trixie), amd64 + arm64**. Auslieferung als signiertes `.deb`.
+
+---
+
+## Repository & Server
+
+- **Gitea:** https://git.netcell-it.de/projekte/edgeguard-native
+- **SSH-Clone:** `ssh://git@git.netcell-it.de:1922/projekte/edgeguard-native.git`
+- **Lokal (Dev):** `/var/www/edgeguard-native` · `ssh linux@89.163.205.87`
+- **Architect Center:** Projekt ID **8**
+- **Git-Server:** git.netcell-it.de · SSH Port 1922 · `git push origin main`
+
+---
+
+## Arbeitsweise — Senior Engineer + MCP (PFLICHT)
+
+### Session-Bindung
+Sessions: `EdgeGuardNative-1` · project_id **8** · `$ARCHITECT_SESSION` im Env · MCP-Server `architect` verfügbar
+
+### Code-Suche — AUTOMATISCH nutzen
+
+Bei JEDER Code-bezogenen Frage **zuerst** `ac_search_code` aufrufen:
+
+```
+ac_search_code(query="<stichworte>", project_id=8, session_name=$(printenv ARCHITECT_SESSION), limit=6)
+```
+
+**Referenzen:**
+- Backend-Pattern → `project_id=6` (mail-gateway)
+- UI/Bootstrap-Pattern → `project_id=5` (netcell-webpanel)
+- Feature-Scope (was alt-EG konnte) → `project_id=3` (proxy-lb-waf)
+
+**Verboten:** direkt `grep` oder `read` ohne vorheriges `ac_search_code` bei Code-Fragen.
+
+---
+
+## Stack
+
+| Schicht | Technologie |
+|---------|-------------|
+| **API** | Go 1.25, Gin, GORM (Queries), goose (Migrations) |
+| **UI** | React 19, TypeScript strict, Vite, Ant Design 6, TanStack Query 5 |
+| **DB** | PostgreSQL 16 (Distro-Paket), goose-Migrations in `migrations/` |
+| **State/HA** | KeyDB Active-Active (Redis-kompatibel) |
+| **Proxy/LB** | HAProxy (Distro), Angie (eigenes APT-Repo) |
+| **VPN** | WireGuard (Kernel-Modul ab 5.6, `wireguard-tools`) |
+| **FW** | nftables (Distro) |
+| **Forward-Proxy** | Squid (Distro) |
+| **TLS** | certbot + webroot-Plugin |
+| **Packaging** | dpkg-deb (direkt, wie mail-gateway + netcell-webpanel) |
+| **Plattform** | Debian 13 Trixie · amd64 + arm64 |
+
+---
+
+## Nicht-Ziele (v1)
+
+- **Kein Docker** — alle Dienste nativ unter systemd
+- **Kein WAF** (kein Coraza, kein ModSecurity)
+- **Kein IDS/IPS** (kein Suricata, kein CrowdSec)
+- **Kein DHCP-Server** (kein Kea)
+- **Kein RADIUS** (kein FreeRADIUS)
+- **Keine Mail-Verarbeitung** (eigenes Produkt: mail-gateway)
+- **Nur Debian 13** — kein Ubuntu, kein Debian 12, kein RHEL
+
+---
+
+## Binaries & Ports
+
+| Binary | Beschreibung | Bindet | User |
+|--------|-------------|--------|------|
+| `edgeguard-api` | REST Management-API | `127.0.0.1:9443` | `edgeguard` |
+| `edgeguard-scheduler` | Cron-Jobs (ACME-Renew, Backup, Health) | — | `edgeguard` |
+| `edgeguard-ctl` | CLI: `initdb migrate cluster-join promote dump-config` | — | root/edgeguard |
+
+Angie terminiert TLS auf `:443` und proxied an `127.0.0.1:9443`.
+
+---
+
+## Build
+
+```bash
+make build            # Host-Architektur (amd64)
+make test             # go test ./...
+make lint             # golangci-lint
+make deb              # amd64 + arm64 .deb
+make publish          # deb + Upload Gitea Package Registry
+make install-local    # direkt auf Dev-Server installieren (kein .deb)
+
+# UI
+cd management-ui && bun install && bun run build
+```
+
+---
+
+## Dev-Server Quickstart
+
+```bash
+# Abhängigkeiten installieren
+sudo apt-get install -y postgresql-16 haproxy angie wireguard-tools squid nftables certbot
+
+# API starten (ohne systemd, für Entwicklung)
+go run ./cmd/edgeguard-api/
+
+# UI Dev-Server
+cd management-ui && bun run dev
+```
+
+---
+
+## Projektstruktur
+
+```
+/var/www/edgeguard-native/
+├── cmd/
+│   ├── edgeguard-api/         # Management-API (Gin, 127.0.0.1:9443)
+│   ├── edgeguard-scheduler/   # Cron-Jobs
+│   └── edgeguard-ctl/         # CLI
+├── internal/
+│   ├── models/                # GORM-Models
+│   ├── handlers/              # HTTP-Handler (REST)
+│   ├── services/              # Business-Logik
+│   ├── haproxy/               # Config-Generator
+│   ├── angie/                 # Config-Generator
+│   ├── squid/                 # Config-Generator
+│   ├── wireguard/             # Config-Generator
+│   ├── firewall/              # nftables-Generator
+│   ├── cluster/               # Join/Promote/Peer-Discovery
+│   ├── proxy/                 # Write-Proxy → Cluster-Primary
+│   ├── aggregator/            # Cluster-View APIs
+│   └── license/               # Lizenz-Validierung
+├── management-ui/             # React 19 + AntD 6 (1:1 enconf-Pattern)
+├── migrations/                # SQL (goose-Format)
+├── packaging/debian/          # control, postinst, postrm, systemd-Units
+├── deploy/
+│   ├── systemd/               # *.service, *.target, *.timer
+│   ├── haproxy/               # haproxy.cfg.tpl
+│   ├── angie/                 # vhost.conf.tpl, sni-map.tpl
+│   ├── squid/                 # squid.conf.tpl
+│   └── nftables/              # ruleset.nft.tpl
+├── scripts/
+│   ├── apt-repo/              # build-package.sh, publish.sh
+│   └── install.sh             # Bootstrap curl-Onliner
+├── docs/
+│   └── architecture.md        # Vollständige Architektur-Spec
+├── go.mod
+├── Makefile
+├── CLAUDE.md                  # Diese Datei
+└── agent.md                   # Agent-Factory Pipeline
+```
+
+---
+
+## Key Conventions
+
+### Go-Code
+- **Migrations:** goose SQL-Dateien in `migrations/` — NICHT GORM AutoMigrate
+- **ORM:** GORM für Queries, nicht für Schema-Verwaltung
+- **Config-Generierung:** Template-Datei in `deploy/*/`, Generator in `internal/*/`
+- **Config-Reload:** `systemctl reload <service>` nach Config-Schreiben
+- **Cluster-Writes:** immer über `internal/proxy` → Primary-URL aus KeyDB `cluster:pg-primary-url`
+
+### Packaging
+- `dpkg-deb` direkt (wie mail-gateway) — kein dh_make/debhelper/fpm
+- postinst: User anlegen → Dirs → initdb (idempotent) → migrate → systemctl
+- postrm purge: nur bei `purge` DB + User entfernen
+
+### UI
+- 100% enconf-Pattern (netcell-webpanel/management-ui/) — keine eigenen Design-Entscheidungen
+- `import type` für alle Type-Imports (verbatimModuleSyntax!)
+- AntD 6, kein Tailwind, kein Material UI
+
+### Auth
+- JWT-basiert (analog enconf), Secret in `/var/lib/edgeguard/.jwt_fingerprint`
+- Admin-Check: immer aus DB-User-Row, nie aus JWT-Payload
+
+---
+
+## Vollständige Architektur
+
+→ `docs/architecture.md`
+
+---
+
+## Vor jeder Änderung
+
+1. Referenz-Pattern in mail-gateway oder netcell-webpanel lesen
+2. `ac_search_code` vor neuem Code — Pattern existiert meist schon
+3. `make test` nach Backend-Änderungen
+4. `cd management-ui && npx tsc --noEmit` nach Frontend-Änderungen

agent.md

@@ -0,0 +1,102 @@
+# agent.md — EdgeGuard Native: Agent-Factory Pipeline
+
+> Dieses Dokument beschreibt wie das Projekt über den Architect Center Orchestrator mit spezialisierten Agenten aufgebaut wird. Jeder Agent hat einen klar abgegrenzten Scope und kann parallel zu anderen arbeiten.
+
+---
+
+## Idee
+
+Der Architect Center Orchestrator dispatcht mehrere Claude Code Agenten, jeder spezialisiert auf eine Schicht des Projekts. Alle Agenten haben Zugriff auf:
+- **RAG (Qdrant):** Code-Index von mail-gateway (project_id=6) und netcell-webpanel (project_id=5) als Referenz
+- **MCP-Server `architect`:** ac_search_code, ac_send_instruction, ac_read_file
+- **Session:** eigene tmux-Session pro Agent (EdgeGuardNative-1 … N)
+
+---
+
+## Agent-Rollen
+
+| Agent | Scope | Referenz-Projekt |
+|-------|-------|-----------------|
+| **DB-Architect** | Datenbankschema, goose-Migrations, GORM-Models | mail-gateway models/ |
+| **API-Engineer** | Gin-Router, alle Handler, Middleware (Auth/JWT/RBAC) | mail-gateway handlers/ |
+| **Config-Generator** | HAProxy, Angie, Squid, WireGuard, nftables Templates + Renderer | mail-gateway config/ |
+| **Cluster-Engineer** | KeyDB AA, PG Streaming Replication, Join/Promote, Write-Proxy | mail-gateway cluster/ |
+| **Scheduler-Engineer** | ACME-Renewal, Backup, Health-Aggregation, License-Heartbeat | mail-gateway scheduler |
+| **CLI-Engineer** | edgeguard-ctl: initdb, migrate, cluster-join, promote, dump-config | mail-gateway cmd/nmg-ctl/ |
+| **Frontend-Engineer** | React 19 + AntD 6 UI (1:1 enconf-Pattern), alle Seiten v1 | netcell-webpanel management-ui/ |
+| **Packaging-Engineer** | .deb-Pakete (dpkg-deb), postinst, systemd-Units, APT-Repo | mail-gateway packaging/ |
+| **Bootstrap-Engineer** | install.sh Onliner, Cluster-Join-Script | netcell-webpanel install.sh |
+
+---
+
+## Abhängigkeiten (Build-Order)
+
+```
+Phase 1 (parallel):
+  DB-Architect      → migrations/ + internal/models/
+  Packaging-Engineer → packaging/debian/ + deploy/systemd/
+
+Phase 2 (parallel, braucht Phase 1):
+  API-Engineer       → internal/handlers/ + cmd/edgeguard-api/
+  Config-Generator   → internal/{haproxy,angie,squid,wireguard,firewall}/
+  CLI-Engineer       → internal/services/ + cmd/edgeguard-ctl/
+
+Phase 3 (parallel, braucht Phase 2):
+  Cluster-Engineer   → internal/{cluster,proxy,aggregator,license}/
+  Scheduler-Engineer → cmd/edgeguard-scheduler/
+  Frontend-Engineer  → management-ui/
+
+Phase 4 (braucht Phase 3):
+  Bootstrap-Engineer → scripts/install.sh, scripts/apt-repo/
+  Integration-Tests  → make test + make deb
+```
+
+---
+
+## Orchestrator-Prompt-Template
+
+```
+Du bist der <ROLE>-Agent für EdgeGuard Native (project_id=8, session=EdgeGuardNative-<N>).
+
+Deine Aufgabe: <SCOPE>
+
+Pflicht vor jeder Implementierung:
+1. ac_search_code(query="<keywords>", project_id=<REF_ID>, limit=6) — Pattern aus Referenz lesen
+2. Erst dann implementieren, NIEMALS raten
+
+Referenz-Projekte: mail-gateway (id=6) für Backend-Patterns, netcell-webpanel (id=5) für UI/Bootstrap.
+
+Arbeite in /var/www/edgeguard-native/<deinem Scope>.
+Nach jedem Abschnitt: make test (Backend) oder npx tsc --noEmit (Frontend).
+```
+
+---
+
+## RAG-Collections (Qdrant auf Architect Center Server)
+
+| Collection | Inhalt | Wird genutzt von |
+|-----------|--------|-----------------|
+| `project_mail_gateway` | mail-gateway Code-Index | DB-, API-, Config-, Cluster-, Scheduler-, CLI-Agent |
+| `project_netcell_webpanel` | netcell-webpanel Code-Index | Frontend-, Bootstrap-Agent |
+| `project_edgeguard_native` | edgeguard-native eigener Index (live, wird gefüllt) | alle Agenten ab Phase 2 |
+
+**Code-Indexer starten:**
+```bash
+# Auf Architect Center Server
+python3 /var/www/architect-center/scripts/code_indexer.py --project-id 8
+```
+
+---
+
+## Start-Befehl (via Architect Center Orchestrator)
+
+1. Architect Center UI → Orchestrator → Neue Pipeline
+2. Template: `edgeguard-native-v1`
+3. Phase 1 starten → bei Completion Phase 2, etc.
+
+Oder manuell per Session:
+```bash
+tmux new-session -d -s EdgeGuardNative-2 -c /var/www/edgeguard-native
+# Claude Code in Session starten:
+tmux send-keys -t EdgeGuardNative-2 'ARCHITECT_SESSION=EdgeGuardNative-2 ARCHITECT_PROJECT_ID=8 claude' Enter
+```