adminroot/AuthorBuddy
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
AuthorBuddy/DOCUMENTATION.md

473 lines
19 KiB
Markdown
Raw Normal View History

Almost done
2026-05-31 19:31:27 +02:00
# 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*
Reference in a new issue Copy permalink