docs: add ARCHITECTURE.md & ARCHITECTURE_QUICK.md, fix user pre bg

- ARCHITECTURE.md: comprehensive project documentation (868 lines) covering all 21 chapters (data model, services, endpoints, chat pipeline, tool system, agents, memory, skills, telegram, cronjobs, krea, auth, workspace, deployment, config) - ARCHITECTURE_QUICK.md: compact quick-reference (223 lines) for fast lookups during development - chat.css: add .msg.user.markdown pre selector so code blocks in user messages get correct background color (was only on code)
2026-03-04 20:43:14 +01:00
1 parent 26da25967d
commit 4e915f76af
@@ -0,0 +1,223 @@
+# ARCHITECTURE_QUICK.md – Schnellreferenz
+
+> Kurzfassung der [ARCHITECTURE.md](ARCHITECTURE.md) für schnelles Nachschlagen beim Entwickeln.
+
+---
+
+## Tech-Stack
+
+**.NET 10** Minimal API · **SQLite** + Dapper · **Anthropic Claude API** (SSE Streaming) · **Vanilla JS** SPA · **Kestrel** auf Port 19000
+
+---
+
+## Verzeichnisstruktur (nur Schlüssel-Dateien)
+
+```
+gott/
+├── Program.cs                  # Startup, DI, Middleware, Routing
+├── appsettings.json            # Tokens, API-Keys, Limits
+├── Models/                     # Records (reine Daten)
+├── Services/                   # Business-Logic (alle Singletons)
+├── Endpoints/                  # HTTP API (Minimal API MapXxx-Pattern)
+├── Middleware/                  # AuthMiddleware
+├── Templates/                  # Vorlagen für neue Agents (IDENTITY, SOUL, USER)
+├── wwwroot/                    # ⚠️ HIER Frontend editieren!
+│   ├── js/app.js               # App-Init
+│   ├── js/router.js            # Hash-basiertes SPA-Routing
+│   ├── js/api.js               # fetch()-Wrapper
+│   ├── js/chat.js              # SSE-Stream, Markdown-Rendering
+│   ├── js/pages/               # Seiten-Komponenten
+│   └── css/                    # Styles (theme.css = CSS Variables)
+├── WindowsApp/                 # WPF + WebView2 Desktop Client
+└── publish/                    # ⛔ NICHT editieren!
+    └── data/
+        ├── gott.db             # SQLite DB
+        ├── agents/{id}/        # Memory-Dateien pro Agent
+        ├── skills/{slug}/      # Skill-Dateien
+        └── images/             # Krea-generierte Bilder
+```
+
+---
+
+## Datenmodell (Kurzform)
+
+```
+User 1──* Agent 1──* Session 1──* Chain 1──* Message 1──* Attachment
+                     Agent *──* Skill (via agent_skills)
+                     Session 1──* Cronjob
+                     Session 1──* Archive
+```
+
+| Tabelle | Zweck |
+|---------|-------|
+| `users` | Login, Persona, Settings (JSON) |
+| `tokens` | Auth-Tokens → User |
+| `agents` | AI-Agenten (Model, Tools, Config) |
+| `sessions` | Chat-Sessions (Workspace, Context, Telegram) |
+| `chains` | Ein Request-Response-Zyklus (Tokens, Timing, Iterations) |
+| `messages` | Einzelne Nachrichten (text / tool_use / tool_result / error) |
+| `attachments` | Base64-Anhänge (Bilder, Dokumente) |
+| `archives` | Archivierte Chain-Gruppen |
+| `cronjobs` | Geplante Tasks (Cron-Expression + Prompt) |
+| `agent_skills` | N:M Agent ↔ Skill |
+| `telegram_links` | Telegram Chat-ID ↔ Session |
+
+---
+
+## API-Endpunkte (Übersicht)
+
+| Gruppe | Route | Wichtigstes |
+|--------|-------|-------------|
+| Auth | `/api/auth/` | `POST login`, `POST logout`, `GET me` |
+| Chat | `/api/chat` | `POST` → SSE Stream |
+| History | `/api/history` | GET history, poll, archive, marks, delete |
+| Sessions | `/api/sessions/` | CRUD + system-prompt, exec, git-status |
+| Agents | `/api/agents/` | CRUD |
+| Workspace | `/api/workspace/` | tree, file read/write, browse, agent-files |
+| Telegram | `/api/telegram/` | webhook (unauth), config, registration |
+| Cronjobs | `/api/cronjobs/` | CRUD + toggle, manual run |
+| Krea | `/api/images/` | generate, list, file-serve |
+| Skills | `/api/skills` | list, agent-mapping, output-files |
+| Profile | `/api/profile` | GET, PUT, password |
+| Settings | `/api/settings` | GET, PUT (JSON blob) |
+| Backup | `/api/backup` | POST → tar.gz download (Admin) |
+| Info | `/api/info` | GET → Build-Zeitstempel |
+
+---
+
+## Services (alle Singletons)
+
+| Service | Was es tut |
+|---------|-----------|
+| **DatabaseService** | Alles DB: Schema, Migrationen, CRUD |
+| **AuthService** | Token-Auth, Passwort-Hashing (SHA256) |
+| **ChatService** | Chat-Kontext aufbauen, History aus DB laden |
+| **AnthropicService** | Claude API: SSE Streaming + Non-Streaming |
+| **ToolService** | Tool-Definitionen + Ausführung (12 Tools) |
+| **SystemPromptBuilder** | System-Prompt aus modularen Blöcken zusammenbauen (static) |
+| **MemoryService** | Agent-Gedächtnis auf Dateisystem |
+| **SkillService** | Skill-Discovery aus Dateisystem |
+| **TelegramService** | Telegram Bot API |
+| **CronjobService** | BackgroundService, minütlicher Cron-Check |
+| **KreaService** | Krea API Bildgenerierung + Job-Polling |
+| **ImageService** | Bild-Resize (ImageSharp, max 512px) |
+| **StreamingTracker** | ConcurrentDict: wer streamt gerade? |
+
+---
+
+## Chat-Pipeline (Flow)
+
+```
+User-Input → POST /api/chat (SSE)
+  → ChatService.BuildContext()
+    → History aus DB laden (letzte N Chains)
+    → SystemPromptBuilder: 12 Blöcke zusammensetzen
+    → Tool-Definitionen vom ToolService holen
+  → AnthropicService.StreamChat()
+    → Claude API Call (SSE)
+    → Token-für-Token an Client streamen
+    → Bei tool_use → ToolService.Execute() → Ergebnis zurück → neuer API Call
+    → Loop bis end_turn oder max_iterations (50)
+  → Chain + Messages in DB speichern
+```
+
+**History-Optimierung:** Ältere Nachrichten werden auf 20% gekürzt, Tool-Results auf 500 Zeichen. Neueste 3 Chains bleiben vollständig.
+
+---
+
+## Tool-System (12 Tools)
+
+| Tool | Funktion |
+|------|----------|
+| `read_file` | Datei lesen |
+| `write_file` | Datei erstellen/überschreiben |
+| `edit_file` | Exakten Textabschnitt ersetzen |
+| `list_files` | Verzeichnisinhalt auflisten |
+| `delete_file` | Datei/leeres Verzeichnis löschen |
+| `execute` | Shell-Befehl ausführen (bash, 180s Timeout) |
+| `glob` | Dateien per Glob-Pattern finden |
+| `grep` | Dateien per Regex/Text durchsuchen |
+| `todo_write` | Aufgabenliste schreiben (wird im Prompt angezeigt) |
+| `memory_read` | Memory-Datei lesen |
+| `memory_write` | Memory-Datei schreiben/appenden |
+| `memory_list` | Memory-Dateien auflisten |
+
+**Sicherheit:** Alle Pfade werden auf das Workspace-Verzeichnis beschränkt (`..` wird blockiert). Tools sind pro Agent konfigurierbar (Feld `tools` als komma-separierte Liste).
+
+**Tool-Choice:** Standard `auto`. Wird zu `none` bei `/no-tools`. Einzelne Tools forcierbar via `/tool:toolname`.
+
+---
+
+## System-Prompt (12 Blöcke, in Reihenfolge)
+
+1. **Identity** – `IDENTITY.md` des Agents
+2. **Soul** – `SOUL.md` des Agents
+3. **User** – `USER.md` (globale User-Infos) + Persona
+4. **Rules** – Verhaltensregeln (Tool-Nutzung, Workspace)
+5. **Context** – Session-Kontext (custom system prompt)
+6. **Marked Messages** – Als wichtig markierte Nachrichten
+7. **Memory** – Aktueller MEMORY.md-Inhalt
+8. **Skills** – Zugeordnete Skill-Prompts
+9. **Todos** – Aktuelle Todo-Liste
+10. **Tools** – Tool-Beschreibungen und -Regeln
+11. **Workspace** – Pfad-Info, Dateibaum des Workspace
+12. **Date** – Aktuelles Datum/Uhrzeit
+
+---
+
+## Frontend-Routing
+
+| Hash-Route | Page-Datei | Beschreibung |
+|------------|-----------|--------------|
+| `#/` | `dashboard.js` | Session-Übersicht |
+| `#/chat/{id}` | `chat-page.js` | Chat |
+| `#/session/{id}` | `session-page.js` | Session-Settings |
+| `#/agent/{id}` | `agent-page.js` | Agent-Editor |
+| `#/cronjobs` | `cronjob-page.js` | Cronjobs |
+| `#/profile` | `profile-page.js` | Profil |
+| `#/settings` | `settings-page.js` | Einstellungen |
+| `#/login` | `login-page.js` | Login |
+
+---
+
+## Auth-Flow
+
+1. `POST /api/auth/login` → Token generiert, als `gott_token` HttpOnly Cookie gesetzt
+2. Jeder `/api/`-Request → `AuthMiddleware` prüft Cookie → setzt `UserId` + `IsAdmin`
+3. Ausnahmen: Login + Telegram-Webhook brauchen kein Auth
+
+---
+
+## Konfiguration (appsettings.json)
+
+```json
+{
+  "AnthropicApiKey": "sk-ant-...",
+  "TelegramBotToken": "...",
+  "KreaApiKey": "...",
+  "DataDirectory": "data",
+  "MaxHistoryChains": 50,
+  "MaxIterations": 50,
+  "DefaultModel": "claude-sonnet-4-20250514"
+}
+```
+
+---
+
+## Deployment
+
+```bash
+./deploy.sh    # dotnet publish → systemctl restart gott
+```
+
+Läuft als `systemd`-Service, Kestrel auf Port 19000, typisch hinter Nginx/Caddy Reverse Proxy.
+
+---
+
+## Wichtige Regeln beim Entwickeln
+
+- ⚠️ **Quelldateien in `wwwroot/`** editieren, NICHT in `publish/wwwroot/`
+- ⛔ **`publish/data/gott.db`** niemals manuell modifizieren/löschen
+- ⛔ **`publish/`** generell nicht anfassen
+- 🔧 **.NET 10** ohne Nullable, ohne Implicit Usings
+- 📦 DB-Migrationen sind idempotent (IF NOT EXISTS Pattern in `DatabaseService`)