# 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 · **KaTeX** (Math) · **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 + WorkspaceHelper)
├── 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/ui.js                # UI-Helpers, buildAgentCard(), buildSessionCard(), Review-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
                     User 1──* SharedMessage ──1 Message
```

| Tabelle | Zweck |
|---------|-------|
| `users` | Login, Persona, Settings (JSON), DefaultPath |
| `tokens` | Auth-Tokens → User |
| `agents` | AI-Agenten (Model, Tools, Config, AvatarScale, AvatarOffsetX/Y) |
| `sessions` | Chat-Sessions (Workspace, Context, Telegram, AvatarScale, AvatarOffsetX/Y, AllowedChatIds, ReviewAgentId, MaxReviewIterations, FinalizerAgentId) |
| `chains` | Ein Request-Response-Zyklus (Tokens, Timing, Iterations) |
| `messages` | Einzelne Nachrichten (text / tool_use / tool_result / error / web_search_result) |
| `attachments` | Base64-Anhänge (Bilder, Dokumente) |
| `archives` | Archivierte Chain-Gruppen |
| `cronjobs` | Geplante Tasks (Cron-Expression + Prompt) |
| `agent_skills` | N:M Agent ↔ Skill |
| `shared_messages` | Geteilte Nachrichten (öffentliche Links via Share-Token) |
| `telegram_links` | Telegram Chat-ID ↔ Session |

---

## API-Endpunkte (Übersicht)

| Gruppe | Route | Wichtigstes |
|--------|-------|-------------|
| Auth | `/api/auth/` | `POST login`, `POST logout`, `GET me`, `GET autologin` |
| Chat | `/api/chat` | `POST` → SSE Stream, `POST stop` |
| History | `/api/history` | GET history, poll, archive, marks, delete |
| Sessions | `/api/sessions/` | CRUD + system-prompt, exec, git-status |
| Agents | `/api/agents/` | CRUD |
| Admin | `/api/admin/` | User CRUD, impersonate, login-link (Admin-only) |
| Workspace | `/api/workspace/` | tree, file read/write, mkdir, rmdir, browse, agent-files |
| Telegram | `/api/telegram/` | webhook (unauth), config, registration |
| Cronjobs | `/api/cronjobs/` | CRUD + toggle, manual run |
| Krea | `/api/images/` | generate, list, file-serve, thumb, status (file/* ohne Auth) |
| 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) |
| Shared | `/api/shared/`, `/api/messages/{id}/share` | Share erstellen, öffentlich abrufen, löschen |
| Info | `/api/info` | GET → Build-Zeitstempel |
| ServerSettings | `/api/admin/server-settings` | `GET`, `PUT` (Admin-only, liest/schreibt `appsettings.Production.json`) |

---

## 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) |
| **WorkspaceHelper** | Workspace-Pfad-Auflösung (relativ → absolut), Path-Traversal-Schutz (static) |
| **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** | Tracking aktiver Streams + CancellationTokenSource pro Session für Stop |

---

## 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 (100)
    → Bei end_turn + ReviewAgent → Review-Phase:
      → Review-Agent prüft (eigene Tools, max 25 Iterationen)
      → [APPROVED] → Fertig | Feedback → Worker korrigiert → erneuter Review
    → Bei FinalizerAgent → Finalizer-Phase:
      → Finalizer-Agent arbeitet (eigene Tools, z.B. git commit)
      → Einmalig, kein Feedback-Loop
    → Stop-Button: POST /api/chat/stop → StreamingTracker.Cancel()
    → CancellationToken durchgereicht bis ToolService → Prozess-Kill
    → client_disconnected
  → Chain + Messages in DB speichern
```

**History-Optimierung:** Ältere Chains nur Text-Messages (keine Tool-Calls). Letzte Chain vollständig. Tool-Results auf 20.000 Zeichen gekürzt. Attachments nur für letzte User-Message.

**Rendering:** Markdown via marked.js + LaTeX via KaTeX (`$$...$$` Block, `$...$` Inline). Timestamps im Format `dd.MM.yyyy HH:mm:ss` on hover.

---

## 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 |
| `#/admin` | `admin-page.js` | Benutzerverwaltung (Admin) |
| `#/server-settings` | `server-settings-page.js` | Servereinstellungen (Admin) |
| `#/login` | `login-page.js` | Login |
| `#/shared/{token}` | `shared-page.js` | Geteilte Nachricht (öffentlich, kein Auth) |

---

## 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, Autologin, Telegram-Webhook, `GET /api/shared/{token}`, `GET /api/images/file/*` brauchen kein Auth
4. **Krea API-Key**: `/api/images/`-Routen akzeptieren `X-Api-Key`-Header (Config: `KreaApiKey`) für Automation ohne User-Kontext
5. **Impersonate**: Admin kann via `POST /api/admin/users/{id}/impersonate` als anderer User einloggen
6. **Login-Link**: Admin generiert via `POST /api/admin/users/{id}/login-link` einen Autologin-Link (Token-basiert, `GET /api/auth/autologin?token=xxx`)
7. **DefaultPath**: Pro User ein Basis-Ordner (nur vom Admin setzbar), Session-Workspaces sind relativ dazu

---

## Konfiguration (appsettings.json)

```json
{
  "Port": 19000,                // Server-Port (erfordert Neustart)
  "AnthropicToken": "",         // Anthropic API Key (REQUIRED)
  "MaxIterations": 100,         // Max Tool-Loop Iterationen pro Chat
  "PayloadLogging": false,      // API-Payloads loggen (Debug)
  "PayloadLoggingGzip": false,  // Payload-Logs als .gz komprimieren
  "KreaToken": "",               // Krea API Token (optional)
  "KreaApiKey": ""               // API-Key für Krea-Endpoints ohne User-Auth (optional)
}
```

Verwaltung über **Admin-UI** (`#/server-settings`): Liest `appsettings.Production.json` (Fallback: `appsettings.json` → Default). Schreibt immer in `appsettings.Production.json`. Die Datei wird **nicht** beim Publish mitkopiert.

---

## Deployment

```bash
./deploy.sh    # dotnet publish → systemctl restart gott
```

Läuft als `systemd`-Service, Kestrel auf konfigurierbarem Port (Default 19000), typisch hinter Nginx/Caddy Reverse Proxy.

---

## Multi-Agent System (Review + Finalizer)

Eine Session kann optional einen **Review-Agent** (`review_agent_id`, `max_review_iterations`) und/oder einen **Finalizer-Agent** (`finalizer_agent_id`) haben.

**Flow:** Worker-Agent arbeitet → `end_turn` → Review-Agent prüft → `[APPROVED]` / Feedback-Loop → Finalizer-Agent arbeitet (einmalig, kein Loop) → Fertig.

**Backend:** `ChatService` baut `ReviewContext` + `FinalizerContext`. `RunReview()` orchestriert Review-Runden. `RunFinalizer()` führt Finalizer aus. Beide nutzen die generische `RunAgentChat()` Methode (eigener Claude-API-Call mit Tool-Loop).

**SSE-Events:**
- Review: `review_start`, `review_text`, `review_tool_use`, `review_feedback`, `review_approved`
- Finalizer: `finalizer_start`, `finalizer_text`, `finalizer_tool_use`, `finalizer_done`

**Frontend-Rendering:**
- Streaming: `chat.js` rendert Review-/Finalizer-Events als eigene Bubbles (`.review-bubble` / `.finalizer-bubble`)
- History: `renderMarkdown` parst `[Review: AgentName]`, `[Finalizer: AgentName]`, `[Review-Feedback ...]`, filtert `[APPROVED]`
- `history.js` + `shared-page.js`: Review-/Finalizer-Nachrichten mit eigenen Bubble-Klassen, kein Merging

**Web-Search Sources:**
- `web_search_result`-Messages in DB gespeichert (Sources als JSON-Array, leere werden übersprungen)
- History + Shared-Page: Tool-Box mit klickbaren Source-Links (Domain + Title)
- Streaming: `pauseStreamBubble()` hält Bubble offen zwischen Web-Searches (keine Doppel-Bubbles)

---

## 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`)