AuthorBuddy/DOCUMENTATION.md

# AuthorBuddy.Web – Dokumentation

## Inhaltsverzeichnis

1. [Überblick](#1-überblick)
2. [Funktionsübersicht](#2-funktionsübersicht)
3. [Systemarchitektur](#3-systemarchitektur)
4. [Installation & Einrichtung](#4-installation--einrichtung)
5. [Bedienung](#5-bedienung)
   - [Projektverwaltung](#51-projektverwaltung)
   - [Editor](#52-editor)
   - [Assistent](#53-assistent)
   - [Einstellungen](#54-einstellungen)
   - [Modellverwaltung](#55-modellverwaltung)
   - [Benutzerverwaltung](#56-benutzerverwaltung)
   - [Datenbank-Administration](#57-datenbank-administration)
6. [Datenbank](#6-datenbank)
7. [Themes & Lokalisierung](#7-themes--lokalisierung)
8. [LLM-Backends](#8-llm-backends)
9. [Technische Referenz](#9-technische-referenz)

---

## 1. Überblick

**AuthorBuddy.Web** ist eine webbasierte Schreibumgebung für Autoren mit KI-Unterstützung. Die Anwendung läuft als Blazor Interactive Server (.NET 10.0) und nutzt lokale Large Language Models (LLMs) über **Ollama** oder **llama.cpp** für Textanalyse, Lektorat, Faktenabfrage und kreative Zusammenarbeit.

Daten werden in einer eingebetteten **LiteDB**-Datenbank (NoSQL) gespeichert – es wird kein externes Datenbanksystem benötigt.

### Zielgruppen

- **Autoren & Schriftsteller** – Romanvorlage mit Kapitelverwaltung, Exposé, Charakterentwicklung
- **Requirements Engineers** – Technische Vorlage für Lastenheft, Pflichtenheft, Use Cases uvm.
- **Administratoren** – Benutzerverwaltung mit 2FA, Datenbank-Administration

---

## 2. Funktionsübersicht

| Funktion | Beschreibung |
|----------|-------------|
| **Projektverwaltung** | Zwei Vorlagen: Roman (mit Drafts, Fakten, Charakteren, Archiv) und Technisch (mit Anforderungen, Use Cases, Architektur, Glossar) |
| **Markdown-Editor** | Vollbild-Editor mit Autosave, Versionierung, Diff-Ansicht |
| **KI-Assistent** | Mehrere Modi: Lektorat, Advocatus Diaboli, Hook-Finder, ELI5, Co-Author, RAG-Faktenabfrage |
| **Technische Assistenten** | Lastenheft, Pflichtenheft, Use Cases, Stakeholder-Analyse, Glossar, Qualitätsanforderungen, Risikoanalyse |
| **Rechtschreibprüfung** | KI-gestützte Korrektur über LLM |
| **Stilanalyse** | KI-gestütztes Lektorat |
| **RAG (Retrieval-Augmented Generation)** | Volltext-Suche über Projektdateien mit Embedding-Vektoren |
| **Wikipedia-Recherche** | Integrierte Wikipedia-Suche (DE/EN) mit „Als Fakt speichern" |
| **Datei-Kategorien** | Markdown-Dateien können als Charakter, Exposé, Fakt oder Dokument getaggt werden |
| **Benutzerverwaltung** | Multi-User mit Passwort-Hashing und TOTP-2FA |
| **Modellverwaltung** | LLM-Modelle via Ollama herunterladen und verwalten |
| **Zwei Backends** | Ollama (vollständig) und llama.cpp (OpenAI-kompatibel) |
| **Mehrere Themes** | Hell, Dunkel, Windows 95 Retro |
| **Zweisprachig** | Deutsch (Standard) und Englisch |
| **DB-Admin** | Datenbank-Tabellen einsehen, bearbeiten und löschen (nur Admin) |

---

## 3. Systemarchitektur

### 3.1 Technologie-Stack

| Komponente | Technologie |
|------------|-------------|
| **Framework** | .NET 10.0 – Blazor Interactive Server |
| **Sprache** | C# 13 |
| **UI** | Razor Components, CSS Custom Properties |
| **Datenbank** | LiteDB 5.0 (eingebettetes NoSQL-Dokumenten-DB) |
| **Text-Diff** | DiffPlex 1.9 |
| **Authentifizierung** | Cookie-basiert mit ClaimsPrincipal |
| **2FA** | TOTP (Time-based One-Time Password) |

### 3.2 Schichtenarchitektur

```
┌─────────────────────────────────────────────┐
│                  Pages (.razor)               │
│  Editor, Assistant, Settings, Models, ...     │
├─────────────────────────────────────────────┤
│              Shared Components                 │
│  CategorySelector, CopyCreateToolbar,         │
│  DiffView, RedirectToLogin                    │
├─────────────────────────────────────────────┤
│               Services                         │
│  AuthService  │  OllamaService                 │
│  SettingsService │  ProjectService             │
│  RagService │  WikipediaService                │
│  ThemeService │  LocalizationService            │
│  DbAdminService │  FileScannerService           │
│  OllamaSetupService                             │
├─────────────────────────────────────────────┤
│              Backends (ILLMBackend)             │
│  OllamaBackend  │  LlamaCppBackend              │
├─────────────────────────────────────────────┤
│              Daten (LiteDB)                     │
│  UserEntity, ProjectEntity, SettingEntity,      │
│  FileCategoryEntity, DocumentVector,            │
│  DocumentMetaEntity                             │
└─────────────────────────────────────────────┘
```

### 3.3 Abhängigkeits-Injektion (DI)

Die Anwendung verwendet das integrierte DI-System von ASP.NET Core:

- **Singleton** (`AddSingleton`): `ILiteDatabase`, `OllamaSettings`, `IOllamaService`, `ILLMBackend` (beide), `IProjectService`, `IRagService`, `IWikipediaService`, `IOllamaSetupService`, `IFileScannerService`, `OperationState`, `IDbAdminService`
- **Scoped** (`AddScoped`): `ISettingsService`, `IThemeService`, `IAuthService`, `ILocalizationService`, `CustomAuthStateProvider`

---

## 4. Installation & Einrichtung

### 4.1 Voraussetzungen

- **.NET 10.0 SDK** oder höher
- **Ollama** (empfohlen) oder **llama.cpp** für LLM-Unterstützung
- Ein moderner Webbrowser (Chrome, Edge, Firefox)

### 4.2 Schnellstart

```bash
# Repository klonen
git clone <repository-url>
cd AuthorBuddy.Web

# Bauen
dotnet build

# Starten
dotnet run
```

Die Anwendung ist standardmäßig unter `http://localhost:5000` erreichbar.

### 4.3 LLM-Modelle einrichten

1. Ollama installieren (https://ollama.com) oder llama.cpp konfigurieren
2. Modelle pullen, z.B.: `ollama pull llama3.2`, `ollama pull nomic-embed-text`
3. In der Anwendung unter **Einstellungen → Modelle** die Modelle auswählen
4. Verbindung testen mit dem **Test**-Button

### 4.4 Erstmaliger Start

Beim ersten Start wird automatisch ein Admin-Benutzer erstellt. Über den *Setup-Assistenten* (`/setup-assistant`) können die empfohlenen Einstellungen übernommen werden.

---

## 5. Bedienung

### 5.1 Projektverwaltung

**Neues Projekt anlegen:**

1. Klicke auf **Datei → Neues Projekt** in der Seitenleiste
2. Wähle eine Vorlage:
   - **📖 Roman** – Erzeugt Ordner für Drafts, Fakten, Charaktere, Archiv sowie Exposé- und Ideen-Vorlagen
   - **⚙️ Technische Vorlage** – Erzeugt Ordner für Anforderungen, Use Cases, Architektur, Glossar sowie Lastenheft- und Pflichtenheft-Vorlagen
3. Vergib einen Projektnamen und wähle einen Speicherort
4. Klicke auf **Erstellen**

**Projekt öffnen:**

In der Seitenleiste unter **Projekte** werden alle vorhandenen Projekte aufgelistet. Ein Klick öffnet das Projekt im Editor.

**Projekt kopieren:**

Rechtsklick (oder Kontextmenü) auf ein Projekt → **Projekt kopieren** – erstellt eine vollständige Kopie inkl. Dateistruktur, Kategorien und projektspezifischer Einstellungen.

### 5.2 Editor

Der Editor (`/editor`) ist der zentrale Arbeitsbereich.

**Funktionen:**

| Funktion | Beschreibung |
|----------|-------------|
| **Text eingeben** | Markdown-Editor im Vollbildmodus |
| **Autosave** | Speichert automatisch alle 2 Sekunden |
| **Manuell speichern** | `Strg+S` oder Klick auf **Speichern** |
| **Versionierung** | Klick auf **Version** erstellt einen Snapshot im Unterordner `_versions/` |
| **Versionen durchsuchen** | **Versionen** → Liste aller Snapshots mit Kommentar |
| **Diff-Ansicht** | **Vergleichen** zeigt Side-by-Side-Diff zwischen Versionen |
| **Version wiederherstellen** | **Wiederherstellen** lädt eine alte Version in den Editor |
| **Stil prüfen** | KI-Analyse des Schreibstils über das Stil-Modell |
| **Rechtschreibung prüfen** | KI-Korrektur über das Spelling-Modell |
| **RAG-Suche** | Durchsucht indexierte Projektinhalte nach ähnlichen Passagen |
| **Wikipedia-Suche** | Durchsucht Wikipedia (DE+EN) und kann Ergebnisse als Fakten speichern |
| **Assistent** | Öffnet den KI-Assistenten mit dem aktuellen Text als Eingabe |
| **Projekt indexieren** | Baut den Vektorindex für RAG auf (nach Projektänderungen nötig) |

**Datei-Kategorien:**

Im Dateibaum können `.md`-Dateien mit Kategorien versehen werden:

- 👤 **Charakter** – Personenprofil
- 📋 **Exposé** – Handlungsübersicht (nur eine Datei pro Projekt)
- 📌 **Fakt** – Hintergrundinformation
- 📄 **Dokument** – Allgemeines Dokument

Kategorien werden im Dateibaum als Badge angezeigt und können über das 🏷-Symbol bearbeitet werden.

### 5.3 Assistent

Der KI-Assistent (`/assistant`) bietet mehrere Arbeitsmodi:

**Roman-Modi:** (immer verfügbar)

| Modus | Beschreibung | Temp. |
|-------|-------------|-------|
| **Lektorat** | Stilistische Textoptimierung – lebendiger, anschaulicher Stil | 0.7 |
| **Advocatus Diaboli** | Radikale Gegenposition – Schwachstellen in der Argumentation | 0.9 |
| **Hook-Finder** | 5 emotionale Einstiegssätze für den Text | 0.9 |
| **ELI5** | Vereinfachung komplexer Passagen | 0.5 |
| **Co-Author** | Kreative Weiterentwicklung von Handlung/Charakteren | 1.0 |
| **RAG** | Faktenabfrage aus dem projekteigenen Index | 0.3 |

**Technische Modi:** (nur bei technischer Projektvorlage sichtbar)

| Modus | Beschreibung | Temp. |
|-------|-------------|-------|
| **📋 Lastenheft** | Erstellung eines Lastenhefts nach IREB-Standard | 0.3 |
| **⚙️ Pflichtenheft** | Detailliertes Pflichtenheft mit technischer Umsetzung | 0.3 |
| **🔄 Use Cases** | UML-Use-Case-Modellierung mit Akteuren und Abläufen | 0.4 |
| **👥 Stakeholder-Analyse** | Identifikation und Analyse aller Projekt-Stakeholder | 0.5 |
| **📖 Glossar** | Fachglossar mit Definitionen und Synonymen | 0.2 |
| **✅ Qualitätsanforderungen** | Qualitätsanforderungen nach ISO 25010 | 0.3 |
| **⚠️ Risikoanalyse** | Identifikation und Bewertung von Projektrisiken | 0.5 |

**Prompt-Editor:**

Jeder Modus hat einen konfigurierbaren System-Prompt. Klicke auf **Prompt bearbeiten**, um den Prompt für die aktuelle Session anzupassen. Mit **Zurücksetzen** wird der Standard-Prompt aus den Einstellungen geladen.

**Temperatur:**

Der Temperatur-Regler beeinflusst die Kreativität des Modells:
- **0.0–0.2**: Präzise, deterministisch
- **0.3–0.5**: Ausgewogen, faktennah
- **0.6–1.2**: Kreativ, überraschende Wendungen
- **1.3–2.0**: Chaotisch, experimentell

**Exposé-Kontext:**

In den Modi Lektorat, Co-Author und Hook-Finder wird automatisch das per Kategorie markierte Exposé als Kontext in den Prompt eingefügt.

### 5.4 Einstellungen

Die Einstellungsseite (`/settings`) ist in vier Spalten organisiert:

| Spalte | Inhalt |
|--------|--------|
| Links (Admin) | Modelle, Ollama-Server, Diagnose, Design, Sprache |
| Mitte-Links | Lektor-System-Prompt, Fact-Check-Vorlage, Rechtschreibungs-Prompt |
| Mitte-Rechts | Advocatus Diaboli, Hook-Finder, ELI5, Co-Author |
| Rechts | Alle 7 technischen Prompts mit Temperatur |

**Projektkontext:**

Wenn ein Projekt geladen ist, werden die Einstellungen für dieses Projekt gespeichert. Ohne Projekt gelten die benutzerspezifischen Einstellungen.

### 5.5 Modellverwaltung

Die Modellverwaltung (`/models`) zeigt alle lokal vorhandenen Ollama-Modelle mit Größe und Änderungsdatum an. Neue Modelle können direkt heruntergeladen werden:

1. Modellname eingeben (z.B. `llama3.2`, `mistral`, `gemma4`)
2. Auf **Herunterladen** klicken
3. Der Fortschritt wird in Echtzeit angezeigt

### 5.6 Benutzerverwaltung

Die Benutzerverwaltung (`/user-management`) ist nur für Administratoren zugänglich:

- Liste aller Benutzer mit Rolle und Status
- Benutzer aktivieren/deaktivieren
- Benutzer löschen (der eigene Account kann nicht gelöscht werden)

**Zwei-Faktor-Authentifizierung (2FA):**

Jeder Benutzer kann 2FA einrichten:
1. Unter **Einstellungen → 2FA einrichten** QR-Code scannen
2. Geheimen Schlüssel notieren
3. Code zur Bestätigung eingeben

### 5.7 Datenbank-Administration

Die DB-Admin-Seite (`/db-admin`) ist Administratoren vorbehalten und erlaubt:

- Auswahl der Datenbank-Tabelle (users, projects, settings, fileCategories, documentMeta, vectors)
- Anzeige aller Datensätze in einer Tabelle
- Bearbeiten von Feldwerten (Öffnet Bearbeitungs-Modal)
- Löschen von Datensätzen (mit Bestätigungsdialog)

> **Achtung:** Hier können kritische Daten verändert oder gelöscht werden. Nur durchführen, wenn du genau weißt, was du tust.

---

## 6. Datenbank

Die Anwendung verwendet **LiteDB** – eine eingebettete NoSQL-Dokumentendatenbank. Die Datenbankdatei (`author_brain.db`) liegt im Ausführungsverzeichnis der Anwendung.

### 6.1 Collections

| Collection | Entity | Zweck |
|------------|--------|-------|
| `users` | `UserEntity` | Benutzerkonten mit Passwort-Hash und 2FA-Secret |
| `projects` | `ProjectEntity` | Projekte mit Name, Pfad, Besitzer und Vorlagentyp |
| `settings` | `SettingEntity` | Key-Value-Einstellungen (global/benutzer-/projektspezifisch) |
| `fileCategories` | `FileCategoryEntity` | Datei-Kategorie-Zuordnungen |
| `documentMeta` | `DocumentMetaEntity` | Metadaten indexierter Dokumente (Hash, Änderungsdatum) |
| `vectors` | `DocumentVector` | Embedding-Vektoren für die RAG-Suche |

### 6.2 Einstellungshierarchie

Einstellungen werden mit absteigender Priorität aufgelöst:
1. **Projektspezifisch** (`UserId` + `ProjectId` gesetzt)
2. **Benutzerspezifisch** (`UserId` gesetzt, `ProjectId` null)
3. **Global** (beide null)

---

## 7. Themes & Lokalisierung

### 7.1 Themes

Drei CSS-Themes stehen zur Verfügung:

| Theme | Beschreibung |
|-------|-------------|
| **Hell** (Standard) | Helles Farbschema mit blauen Akzenten |
| **Dunkel** | Dark Mode, inspiriert von VS Code |
| **W95** | Windows 95 Retro-Stil |

Die Theme-Umschaltung erfolgt durch dynamisches Einfügen eines `<link>`-Elements in den Seitenkopf.

### 7.2 Lokalisierung

Unterstützte Sprachen:
- **Deutsch** (`de`) – Standard
- **Englisch** (`en`)

Die Übersetzungen liegen als JSON-Dateien im Ordner `Resources/`. Die Sprachumschaltung erfolgt in den Einstellungen und wird sofort wirksam. Für nicht gefundene Schlüssel gibt es eingebaute deutsche Fallback-Texte.

---

## 8. LLM-Backends

### 8.1 Ollama (Standard)

- **Status**: Voll unterstützt
- **Modellverwaltung**: Ja (Pull, Delete)
- **API**: REST (`/api/generate`, `/api/embeddings`, `/api/tags`, `/api/pull`, `/api/delete`, `/api/show`)
- **Standard-URL**: `http://localhost:11434`

### 8.2 llama.cpp

- **Status**: Basisfunktionen unterstützt
- **Modellverwaltung**: Nein
- **API**: OpenAI-kompatibel (`/v1/chat/completions`, `/v1/models`) + `/embedding`, `/slots`
- **Standard-URL**: `http://localhost:8080`

Voreingestellte Modelle (in `OllamaSettings`):

| Modell | Zweck |
|--------|-------|
| `gemma4:e4b` | Stil-Analyse (Lektorat) |
| `nomic-embed-text` | Embeddings (RAG) |
| `phi3:mini` | Rechtschreibprüfung |

---

## 9. Technische Referenz

### 9.1 Routen

| Route | Seite | Zugriff |
|-------|-------|---------|
| `/` | Dashboard | Authentifiziert |
| `/login` | Anmeldung | Öffentlich |
| `/register` | Registrierung | Öffentlich |
| `/editor` | Editor | Authentifiziert |
| `/editor/index/{id}` | Editor mit Projekt | Authentifiziert |
| `/editor/newproject` | Editor mit Erstell-Dialog | Authentifiziert |
| `/assistant` | KI-Assistent | Authentifiziert |
| `/settings` | Einstellungen | Authentifiziert |
| `/models` | Modellverwaltung | Authentifiziert |
| `/user-management` | Benutzerverwaltung | Authentifiziert |
| `/setup-2fa` | 2FA einrichten | Authentifiziert |
| `/setup-assistant` | Setup-Assistent | Authentifiziert |
| `/db-admin` | DB-Administration | Authentifiziert (Admin) |
| `/not-found` | 404 | Öffentlich |
| `/Error` | 500 | Öffentlich |

### 9.2 NuGet-Pakete

- **DiffPlex** 1.9.0 – Text-Differencing für die Diff-Ansicht
- **LiteDB** 5.0.21 – Eingebettete NoSQL-Dokumentendatenbank

### 9.3 Schlüssel-Klassen

| Namespace | Klasse | Zweck |
|-----------|--------|-------|
| `Models` | `Constants` | App-Konstanten (DB-Name, Ordnerstruktur) |
| `Models` | `OllamaSettings` | Zentrale Konfiguration (Singleton) |
| `Models` | `ProjectTemplate` | Vorlagentyp (Novel, Technical) |
| `Models` | `FileCategory` | Datei-Kategorien als Flags-Enum |
| `Models` | `FileTreeItem` | Baumstruktur für Projektdateien |
| `Data` | `UserEntity` | Benutzer-DB-Entity |
| `Data` | `ProjectEntity` | Projekt-DB-Entity |
| `Data` | `SettingEntity` | Einstellungs-DB-Entity |
| `Data` | `DocumentVector` | Embedding-Vektor-DB-Entity |
| `Services` | `AuthService` | Authentifizierung mit 2FA |
| `Services` | `SettingsService` | Einstellungs-Verwaltung |
| `Services` | `ProjectService` | Projekt-CRUD |
| `Services` | `OllamaService` | LLM-Kommunikation (Fassade) |
| `Services` | `RagService` | RAG-Indexierung und -Suche |
| `Services` | `DbAdminService` | DB-Administration |

### 9.4 Wichtige Konstanten

```csharp
Constants.DbFile        // "author_brain.db"
Constants.SubFolders    // Standard-Ordnerstruktur (Referenz)
```

Projekt-Ordnerstruktur bei **Roman**-Vorlage:
```
{rootPath}/
  ├── 00_Drafts/
  ├── 01_Fakten/
  ├── 02_Characters/
  ├── 03_Archive/
  ├── 00_Projekt_Info.md
  ├── Die Handlung (Das Exposé).md
  └── Ideen Sammlung.md
```

Projekt-Ordnerstruktur bei **Technischer** Vorlage:
```
{rootPath}/
  ├── 00_Anforderungen/
  ├── 01_UseCases/
  ├── 02_Architektur/
  ├── 03_Glossar/
  ├── 00_Projekt_Info.md
  ├── Lastenheft.md
  └── Pflichtenheft.md
```

---

## 10. Entwicklung & Erweiterung

### 10.1 Neuen Assistenten-Modus hinzufügen

1. **Prompt-Default** in `Models/OllamaSettings.cs` (DE + EN + Temp)
2. **Settings-Key** in `Services/SettingsService.cs` (Key-Konstante + Getter/Setter)
3. **Interface-Methoden** in `Services/ISettingsService.cs`
4. **Settings-UI** in `Components/Pages/Settings.razor`
5. **Mode-Dropdown** + `LoadPromptForMode` in `Components/Pages/OllamaAssistant.razor`
6. **Lokalisierung** in `Resources/de.json` + `Resources/en.json`
7. **DB-Seeding** in `SettingsService.InitializeAsync()` + `LoadProjectSettingsAsync()`

### 10.2 Neues Daten-Modell hinzufügen

1. Entity-Klasse in `Data/` anlegen
2. Collection-Namen in `Services/DbAdminService.KnownCollections` aufnehmen
3. Service-Methoden für CRUD-Operationen schreiben
4. Bei Bedarf UI-Komponente erstellen

---

*Dokumentation erstellt am 31.05.2026*