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](#system-überblick)
2. [Architektur-Prinzipien](#architektur-prinzipien)
3. [Komponenten-Architektur](#komponenten-architektur)
4. [Datenfluss](#datenfluss)
5. [Konfigurations-Management](#konfigurations-management)
6. [Erweiterbarkeit](#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:**
```typescript
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:**
```typescript
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:**
```typescript
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:**
```typescript
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**