adminroot/AuthorBuddy
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
AuthorBuddy/DOCUMENTATION.md
Roland c790274f87 Almost done
2026-05-31 19:31:27 +02:00

19 KiB
Raw Permalink Blame History

AuthorBuddy.Web – Dokumentation

Inhaltsverzeichnis

  1. Überblick
  2. Funktionsübersicht
  3. Systemarchitektur
  4. Installation & Einrichtung
  5. Bedienung
  6. Datenbank
  7. Themes & Lokalisierung
  8. LLM-Backends
  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

# 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

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