mindnet_obsidian/docs/04_Architektur.md

Mindnet Causal Assistant - Architektur-Dokumentation

Version: 1.0.0
Stand: 2025-01-XX
Zielgruppe: Architekten, Entwickler, System-Designer

---

Inhaltsverzeichnis

1. System-Überblick
2. Architektur-Prinzipien
3. Komponenten-Architektur
4. Datenfluss
5. Konfigurations-Management
6. Erweiterbarkeit

---

System-Überblick

Zweck

Das Mindnet Causal Assistant Plugin ist ein Authoring-Tool für Obsidian, das kausale/argumentative Zusammenhänge als Graph abbildet und daraus nützliche Diagnosen ableitet.

Kern-Funktionen

1. Note-Erstellung: Strukturierte Notes mit Frontmatter, IDs, Typen
2. Interview-Wizard: Konfigurierbare Interviews zur Inhaltserfassung
3. Semantic Mapping: Section-basierte Gruppierung von Links nach Edge-Typen
4. Chain Inspector: Analyse kausaler Ketten mit Template Matching
5. Findings & Fixes: Automatische Erkennung und Behebung von Problemen

Technologie-Stack

• Sprache: TypeScript (strict mode)
• Framework: Obsidian Plugin API
• Bundler: esbuild
• Testing: Vitest
• Config-Format: YAML, Markdown

---

Architektur-Prinzipien

1. Modularität

Prinzip: Klare Trennung von Verantwortlichkeiten

• Analysis: Chain Inspector, Template Matching
• Dictionary: Config Loading & Parsing
• Graph: Graph Building & Traversal
• Interview: Wizard & State Management
• Mapping: Semantic Mapping Builder
• Parser: Markdown Parsing

2. Konfigurierbarkeit

Prinzip: Externe Konfiguration über Vault-Dateien

• Edge Vocabulary: Edge-Typen & Aliases
• Graph Schema: Empfehlungen für Edge-Types
• Interview Config: Profile, Steps, Loops
• Chain Roles: Edge-Type → Role Mapping
• Chain Templates: Vordefinierte Kettenmuster

3. Live-Reload

Prinzip: Automatisches Neuladen bei Config-Änderungen

• Debounced Reload: 200ms Delay für Performance
• Last-Known-Good: Fallback bei Fehlern
• Error-Handling: Graceful Degradation

4. Extensibility

Prinzip: Erweiterbar durch neue Module

• Lint Rules: Neue Regeln hinzufügbar
• Findings: Neue Finding-Codes definierbar
• Templates: Neue Chain-Templates konfigurierbar
• UI Components: Modals/Views erweiterbar

---

Komponenten-Architektur

High-Level-Architektur

┌─────────────────────────────────────────────────────────┐
│                    Obsidian Plugin API                   │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│              MindnetCausalAssistantPlugin                │
│                   (main.ts)                             │
│  - Settings Management                                  │
│  - Command Registration                                 │
│  - Event Handlers                                       │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  Analysis    │   │  Dictionary  │   │    Graph     │
│              │   │              │   │              │
│ - Inspector  │   │ - Loaders    │   │ - Builder    │
│ - Matching   │   │ - Parsers    │   │ - Traversal  │
│ - Findings   │   │ - Types      │   │ - Index      │
└──────────────┘   └──────────────┘   └──────────────┘
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  Interview   │   │   Mapping    │   │    Parser    │
│              │   │              │   │              │
│ - Wizard     │   │ - Builder    │   │ - Edges      │
│ - State      │   │ - Extractor  │   │ - Frontmatter│
│ - Renderer   │   │ - Selector   │   │ - Links      │
└──────────────┘   └──────────────┘   └──────────────┘
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  Vocabulary  │   │    Lint      │   │    Export    │
│              │   │              │   │              │
│ - Loader     │   │ - Engine     │   │ - Graph      │
│ - Normalize  │   │ - Rules      │   │ - Serialize  │
│ - Cache      │   │ - Findings   │   │ - JSON       │
└──────────────┘   └──────────────┘   └──────────────┘
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│   Schema     │   │UnresolvedLink│   │EntityPicker  │
│              │   │              │   │              │
│ - Loader     │   │ - Handler    │   │ - Index      │
│ - Lookup     │   │ - Adoption   │   │ - Filters   │
│ - Cache      │   │ - Resolution │   │ - Tree       │
└──────────────┘   └──────────────┘   └──────────────┘

Komponenten-Details

1. Plugin Core (main.ts)

Verantwortlichkeiten:

• Plugin Lifecycle (onload/onunload)
• Settings Management
• Command Registration
• Event Handler Registration
• Config Loading Coordination

Abhängigkeiten:

• Obsidian Plugin API
• Alle anderen Module

2. Analysis (src/analysis/)

Verantwortlichkeiten:

• Chain Inspector (Haupt-Analyse-Engine)
• Template Matching (Slot-basiertes Matching)
• Graph Indexierung (für Traversal)
• Section Context Extraction
• Findings Generation

Abhängigkeiten:

• Dictionary (Chain Roles, Templates)
• Graph (Traversal, Index)
• Parser (Edge Extraction)

Datenfluss:

Context → Graph Building → Traversal → Template Matching → Findings

3. Dictionary (src/dictionary/)

Verantwortlichkeiten:

• Config Loading (YAML, Markdown)
• Config Parsing (YAML → TypeScript Types)
• Error Handling (Last-Known-Good)
• Live-Reload Coordination

Abhängigkeiten:

• Obsidian Vault API
• YAML Parser

Datenfluss:

Vault File → Loader → Parser → TypeScript Types → Cache

4. Graph (src/graph/)

Verantwortlichkeiten:

• Graph Building (aus Vault)
• Graph Indexierung (für Traversal)
• Traversal (BFS/DFS)
• Target Resolution (Link → File)
• Report Rendering

Abhängigkeiten:

• Parser (Edge Extraction)
• Obsidian Metadata Cache

Datenfluss:

Vault → Graph Builder → Graph Index → Traversal → Paths

5. Interview (src/interview/)

Verantwortlichkeiten:

• Wizard State Management
• Loop State Management (nested loops)
• Output Rendering (Section-basiert)
• Frontmatter Writing
• Section Key Resolution
• Target Extraction from Anchors

Abhängigkeiten:

• Dictionary (Interview Config)
• UI (Wizard Modal)
• Parser (Frontmatter)

Datenfluss:

Config → Wizard State → User Input → Loop State → Renderer → Note Content

Hauptkomponenten:

• InterviewConfigLoader.ts - Lädt interview_config.yaml
• parseInterviewConfig.ts - YAML → InterviewConfig Parser
• wizardState.ts - Wizard State Management (Steps, Loops)
• loopState.ts - Loop State Management (nested loops)
• renderer.ts - Output-Rendering (Section-basiert)
• writeFrontmatter.ts - Frontmatter-Generierung
• sectionKeyResolver.ts - Section-Key-Auflösung
• extractTargetFromAnchor.ts - Target-Extraktion aus Anchors
• slugify.ts - Slug-Generierung für Dateinamen

6. Mapping (src/mapping/)

Verantwortlichkeiten:

• Semantic Mapping Builder
• Mapping Extraction (aus existierenden Blöcken)
• Edge Type Selection (UI)
• Mapping Block Updates

Abhängigkeiten:

• Parser (Link Extraction)
• Schema (Graph Schema für Empfehlungen)
• UI (Edge Type Selector)

Datenfluss:

Note Content → Link Extraction → Edge Type Assignment → Mapping Blocks

7. Parser (src/parser/)

Verantwortlichkeiten:

• Edge Extraction (aus Callouts)
• Frontmatter Parsing
• Link Parsing (Relative Links)
• Section Detection

Abhängigkeiten:

• Obsidian Metadata Cache
• Vocabulary (Edge Normalization)

Datenfluss:

Markdown → Parser → Structured Data (Edges, Links, Frontmatter)

8. Vocabulary (src/vocab/)

Verantwortlichkeiten:

• Edge Vocabulary Loading (aus Markdown)
• Edge Type Normalization (Alias → Canonical)
• Inverse Edge Type Resolution
• Vocabulary Caching

Abhängigkeiten:

• Obsidian Vault API
• Markdown Parser

Datenfluss:

Vault File → VocabularyLoader → Parser → Vocabulary Instance → Cache

Hauptkomponenten:

• Vocabulary.ts - Wrapper-Klasse für Lookup-Methoden
• VocabularyLoader.ts - Lädt Vocabulary-Datei
• parseEdgeVocabulary.ts - Parst Markdown zu EdgeVocabulary-Struktur

9. Lint (src/lint/)

Verantwortlichkeiten:

• Linting Engine für Note-Validierung
• Regel-basierte Prüfungen
• Findings Generation

Abhängigkeiten:

• Vocabulary (Edge Type Validation)
• Parser (Edge Extraction)
• Obsidian Metadata Cache

Datenfluss:

Note Content → Parser → Lint Rules → Findings

Hauptkomponenten:

• LintEngine.ts - Haupt-Linting-Engine
• rules/ - Einzelne Lint-Regeln
  • rule_hub_has_causality.ts - Prüft auf kausale Edges
  • rule_missing_target.ts - Prüft auf fehlende Targets
  • rule_unkown_edge.ts - Prüft auf unbekannte Edge-Types

10. Export (src/export/)

Verantwortlichkeiten:

• Graph Export zu JSON
• Node/Edge Serialisierung
• Export-Datei-Erstellung

Abhängigkeiten:

• Graph (Graph Building)
• Vocabulary (Edge Normalization)
• Parser (Edge Extraction)

Datenfluss:

Vault → Graph Builder → Export Serialization → JSON File

Hauptkomponenten:

• exportGraph.ts - Haupt-Export-Funktion
• types.ts - Export-Types (ExportBundle, ExportNode, ExportEdge)

11. Schema (src/schema/)

Verantwortlichkeiten:

• Graph Schema Loading (aus Markdown)
• Schema-basierte Empfehlungen für Edge-Types
• Typical/Prohibited Edge-Type-Lookup

Abhängigkeiten:

• Obsidian Vault API
• Markdown Parser

Datenfluss:

Vault File → GraphSchemaLoader → Schema Instance → Cache

Hauptkomponenten:

• GraphSchemaLoader.ts - Lädt Graph-Schema-Datei
• Verwendet von mapping/graphSchema.ts für Empfehlungen

12. Unresolved Link (src/unresolvedLink/)

Verantwortlichkeiten:

• Unresolved Link Detection
• Link Click Interception (Reading View, Editor)
• Note Adoption Flow
• Link Target Resolution

Abhängigkeiten:

• Obsidian Metadata Cache
• Interview (Note Creation)
• Entity Picker (Target Selection)

Datenfluss:

Link Click → Detection → Profile Selection → Note Creation → Adoption

Hauptkomponenten:

• unresolvedLinkHandler.ts - Haupt-Handler für Link-Clicks
• linkHelpers.ts - Link-Parsing und -Normalisierung
• adoptHelpers.ts - Note-Adoption-Logik

13. Entity Picker (src/entityPicker/)

Verantwortlichkeiten:

• Entity Selection UI (Notes, Folders)
• Note Index Building
• Folder Tree Navigation
• Wikilink Parsing

Abhängigkeiten:

• Obsidian Vault API
• UI (EntityPickerModal)

Datenfluss:

Vault → Note Index → Filters → Entity Selection → Result

Hauptkomponenten:

• noteIndex.ts - Baut Index aller Notes
• folderTree.ts - Folder-Tree-Struktur
• filters.ts - Filter-Logik für Entity-Selection
• wikilink.ts - Wikilink-Parsing

14. Commands (src/commands/)

Verantwortlichkeiten:

• Command Implementations
• Command Execution Coordination
• Error Handling für Commands

Abhängigkeiten:

• Alle anderen Module (je nach Command)

Hauptkomponenten:

• inspectChainsCommand.ts - Chain Inspector Command
• fixFindingsCommand.ts - Fix Findings Command

---

Datenfluss

Workflow 1: Chain Inspector

1. User: Command "Inspect Chains"
   ↓
2. main.ts: executeInspectChains()
   ↓
3. sectionContext.ts: Extract Context (file, heading)
   ↓
4. parser/: Extract Edges from Section
   ↓
5. graphIndex.ts: Build Index from Edges
   ↓
6. traverse.ts: BFS/DFS Traversal
   ↓
7. templateMatching.ts: Match Templates
   ↓
8. chainInspector.ts: Generate Findings
   ↓
9. Console: Output Report

Workflow 2: Note Creation

1. User: Command "Create Note from Profile"
   ↓
2. main.ts: Profile Selection Modal
   ↓
3. dictionary/: Load Interview Config
   ↓
4. interview/: Write Frontmatter
   ↓
5. vault.create(): Create File
   ↓
6. interview/: Start Wizard (if enabled)
   ↓
7. wizardState.ts: Collect User Input
   ↓
8. renderer.ts: Render Output
   ↓
9. vault.modify(): Write Content
   ↓
10. mapping/: Run Edger (if enabled)

Workflow 3: Semantic Mapping

1. User: Command "Build Semantic Mapping"
   ↓
2. mappingExtractor.ts: Extract Existing Mappings
   ↓
3. sectionParser.ts: Parse Sections
   ↓
4. parseRelLinks.ts: Extract Links
   ↓
5. edgeTypeSelector.ts: Assign Edge Types
   ↓
6. mappingBuilder.ts: Build Mapping Blocks
   ↓
7. updateMappingBlocks.ts: Update Note
   ↓
8. vault.modify(): Write Content

Workflow 4: Config Reload

1. Vault: File Modified (edge_vocabulary.md)
   ↓
2. main.ts: Vault Modify Event
   ↓
3. Debounce Timer (200ms)
   ↓
4. VocabularyLoader: Load File
   ↓
5. parseEdgeVocabulary: Parse Markdown
   ↓
6. Vocabulary: Create Instance
   ↓
7. Cache: Update Vocabulary
   ↓
8. Notice: "Vocabulary reloaded"

---

Konfigurations-Management

Config-Loading-Pattern

Basis-Pattern:

interface DictionaryLoadResult<T> {
  status: "loaded" | "error" | "using-last-known-good";
  data: T | null;
  errors: string[];
  warnings: string[];
  resolvedPath: string;
  loadedAt: number | null;
}

Last-Known-Good:

• Bei Fehlern wird letzte gültige Config verwendet
• lastKnownGood Parameter für Fallback
• Graceful Degradation statt Crash

Live-Reload:

• Debounced (200ms) für Performance
• Automatisches Neuladen bei Dateiänderungen
• Error-Handling mit Last-Known-Good

Config-Hierarchie

1. Vault File (YAML/Markdown)
   ↓
2. Loader (File → Text)
   ↓
3. Parser (Text → TypeScript Types)
   ↓
4. Validator (Type Checking)
   ↓
5. Cache (In-Memory)
   ↓
6. Consumer (Plugin Components)

---

Erweiterbarkeit

Erweiterungspunkte

1. Lint Rules

Schnittstelle:

interface LintRule {
  id: string;
  name: string;
  severity: "ERROR" | "WARN" | "INFO";
  check: (app: App, file: TFile, vocabulary: Vocabulary) => Promise<LintFinding[]>;
}

Erweiterung:

• Neue Regel-Datei in src/lint/rules/
• Regel in src/lint/rules/index.ts registrieren

2. Findings

Schnittstelle:

interface Finding {
  code: string;
  severity: "ERROR" | "WARN" | "INFO";
  message: string;
  evidence: Record<string, unknown>;
}

Erweiterung:

• Neuen Finding-Code definieren
• Finding in Chain Inspector generieren
• Optional: Fix Action hinzufügen

3. Chain Templates

Erweiterung:

• Neues Template in chain_templates.yaml hinzufügen
• Slots und Links definieren
• Template Matching unterstützt automatisch

4. UI Components

Schnittstelle:

class MyModal extends Modal {
  constructor(app: App, onResult: (result: MyResult) => void);
  onOpen(): void;
  onClose(): void;
}

Erweiterung:

• Neue Modal-Klasse erstellen
• In Commands verwenden

---

Performance-Überlegungen

Optimierungen

1. Debouncing: Config-Reload (200ms)
2. Caching: In-Memory Cache für Configs
3. Lazy Loading: Configs werden bei Bedarf geladen
4. BFS-Limit: Template Matching (max 30 Nodes)
5. Tree-Shaking: Unused Code wird entfernt

Bottlenecks

1. Graph Building: Kann bei großen Vaults langsam sein
2. Template Matching: Backtracking kann bei vielen Templates langsam sein
3. Live-Reload: Zu viele Reloads können Performance beeinträchtigen

---

Sicherheit & Robustheit

Error-Handling

• Last-Known-Good: Fallback bei Config-Fehlern
• Try-Catch: Alle async Operations
• Graceful Degradation: Plugin funktioniert auch bei Teilfehlern

Validierung

• YAML-Syntax: Wird beim Laden geprüft
• Type-Checking: TypeScript strict mode
• Runtime-Validierung: Config-Struktur wird geprüft

Isolation

• Module-Grenzen: Klare Trennung von Verantwortlichkeiten
• Keine zirkulären Dependencies
• Obsidian API: Isoliert von anderen Plugins

---

Weitere Ressourcen

• Benutzerhandbuch: Endnutzer-Workflows
• Administratorhandbuch: Konfiguration und Wartung
• Entwicklerhandbuch: Code-Struktur und Erweiterungen
• Installation & Deployment: Setup-Anleitung

---

Ende der Architektur-Dokumentation