From cf10bd4072daa41d55ff2364c4a57aef76b1e240 Mon Sep 17 00:00:00 2001 From: Debian Date: Fri, 8 May 2026 19:46:15 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=20+=20agent.md=20f=C3=BCr=20A?= =?UTF-8?q?gent-Factory=20Pipeline?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ agent.md | 102 +++++++++++++++++++++++++++ 2 files changed, 306 insertions(+) create mode 100644 CLAUDE.md create mode 100644 agent.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1b887c3 --- /dev/null +++ b/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="", 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 ` 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 diff --git a/agent.md b/agent.md new file mode 100644 index 0000000..08d7d29 --- /dev/null +++ b/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 -Agent für EdgeGuard Native (project_id=8, session=EdgeGuardNative-). + +Deine Aufgabe: + +Pflicht vor jeder Implementierung: +1. ac_search_code(query="", project_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/. +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 +```