mindnet/docs/mindnet_functional_architecture.md

# Mindnet – Fachliche Architektur
**Version:** 2.0 • **Datum:** 2025-11-09 • **Autor:** Fachkonzept (gemeinsam mit Owner)

---

## 0. Zweck dieses Dokuments
Dieses Dokument beschreibt **Fachdomäne, Funktionsräume, Prozesse und Regeln** von *mindnet*. Es ergänzt die technische Architektur und macht die ursprünglichen Ziele, Designentscheidungen, Anti‑Patterns und Umsetzungsstrategien explizit nachvollziehbar.

---

## 1. Vision & Leitplanken
- **Essenz bewahren:** Entscheidungen, Erlebnisse, Werte, Prinzipien und Konditionierungen so strukturieren, dass sie später erklärbar rekonstruiert werden können.  
- **Antworten im eigenen Stil:** Ergebnisse sollen die Persönlichkeit des Owners widerspiegeln (Sprache: **Deutsch**).  
- **Vertraulichkeit:** Aktuell einheitlich, aber mit **Stufen** (public/internal/sensitive) erweiterbar.  
- **Zeitliche Priorisierung:** Standard: jüngere Inhalte leichter gewichten; Ausnahmen konfigurierbar.  
- **Lokal zuerst**, später skalierbar.

---

## 2. Fachliches Datenmodell
### 2.1 Kernobjekte
- **Note**: Eintrag im Wissensnetz (z. B. Konzept, Projekt, Erfahrung, Ereignis, Aufgabe).  
- **Chunk**: semantischer Abschnitt einer Note (Antwortbaustein).  
- **Edge**: gerichtete Beziehung zwischen Notes/Chunks (mit Typ, Gewicht, Quelle).  
- **Run**: Importlauf (Audit).  
- **Config**: aktive Regel‑ und Typkonfigurationen.

### 2.2 Typen & Semantik (Auszug)
- `concept`: Begriff/These/Prinzip.  
- `experience`: Erlebnis/Beobachtung (zeitlich verankert).  
- `project`: Vorhaben mit Zielen/Abhängigkeiten.  
- `task`: Arbeitseinheit.  
- (erweiterbar: `event`, `decision`, `person`, `place`, `quote` …)

### 2.3 Relationen (fachlich)
- `references`: verweist inhaltlich auf …  
- `related_to`: thematische Nähe/Assoziation.  
- `depends_on`: fachliche/kausale Abhängigkeit.  
- `belongs_to`: Zugehörigkeit (Teil‑von, Kapitel‑zu).  
- `derived_from`: abgeleitet (z. B. Schluss aus Erfahrung).  
- `inspired_by`: Impuls/Idee aus Quelle.  
- `supports` / `contradicts`: argumentative Beziehung.

---

## 3. Funktionsräume
1. **Kurativer Raum**  
   - Schreiben/Überarbeiten von Notizen (Obsidian Templates, Frontmatter‑Guides).  
   - Plausibilisierung: Pflichtfelder, Dublettencheck, Warnungen (z. B. fehlende Relationen).

2. **Graphischer Raum**  
   - Relationen setzen (declared), Vorschläge prüfen (inferred).  
   - Subgraph‑Explorer je Frage/Entscheidung.

3. **Antwort‑Raum**  
   - Query‑Typen: *Faktenabruf*, *Erlebnisbasiert erklären*, *Planung/Entscheidung begründen*.  
   - Erklärpfad: Chunks → Kanten → Zeitfaktoren → Typgewichte.

4. **Governance‑Raum**  
   - Sichtbarkeit/ACL, Qualitätsflags, Review‑Queues.  
   - Versionsjournal, Import‑Runs, Config‑Historie.

---

## 4. Fachliche Regeln
### 4.1 Frontmatter‑Schema (Mindeststandard)
```yaml
id: "{deterministic}"
title: "…"
type: "concept|experience|project|task|…"
created: "YYYY-MM-DD"
modified: "YYYY-MM-DD"
visibility: "internal"        # default
retriever_weight: null        # optional override
chunk_profile: null           # optional override
tags: ["…"]
edge_hints:
  - relation: references
    target: "note-id-or-path"
  - relation: depends_on
    target: "…"
```

### 4.2 Typregeln (aus types.yaml)
- `chunk_profile`, `retriever_weight`, `edge_defaults` werden je Typ **automatisch** angewandt.  
- Aus `edge_defaults` abgeleitete Kanten werden **persistiert** (`source='rule'`).

### 4.3 Zeitgewichtung
- Default: **Exponential Decay** mit globalem λ; Override per `time_weight_override` möglich.  
- Erlebnisse (`experience`) erhalten standardmäßig leicht höheren **Base‑Impact** im Score, um Persönlichkeit abzubilden.

### 4.4 Qualitätsregeln
- Jede Note soll **mind. eine Relation** besitzen.  
- **Konflikte** (contradicts) werden nicht gefiltert, sondern sichtbar gemacht (mit Hinweis).  
- **Sichtbarkeit**: Antworten aus `sensitive` nur bei expliziter Freigabe.

---

## 5. Use Cases (repräsentativ)
1. **„Warum habe ich 2019 X entschieden?“**  
   - Abfrage auf `decision` + temporale Nachbarschaft zu `experience`/`principle`.  
   - Ausgabe mit Erklärpfad: *Erlebnis → Prinzip → Projekt → Entscheidung*.

2. **„Plane ein Trainingsprogramm“**  
   - Query kombiniert Konzepte/Erfahrungen/Projekte → Graph‑Walk + Typgewichtung, priorisiert jüngere Erkenntnisse.

3. **„Welche Ereignisse haben mein Leitbild geprägt?“**  
   - Subgraph über `derived_from`/`inspired_by` Ketten + Zeitachsen‑Visualisierung.

---

## 6. Anti‑Patterns (vermeiden)
- **Edges ohne Relation** („Dot‑Kanten“) – verhindern jede sinnvolle Auswertung.  
- **Nur Vektor‑Suche** ohne Graph / Zeitfaktor – verfälscht Persönlichkeit.  
- **Freies Tag‑Chaos** ohne Typregeln – mindert Reproduzierbarkeit.  
- **Heimliche Workarounds** (z. B. Felder mit Mehrdeutigkeit) – erschweren spätere Automatisierung.

---

## 7. Umsetzungsstrategie & Roadmap
### Phase 1 (Jetzt)
- Pflicht‑Frontmatter, deterministische IDs, Ingestion v2 (Chunks/Edges **persistiert**).  
- types.yaml + retrieval.yaml live‑fähig; Import‑Run‑Audit.  
- Tests (Parser/Chunker/Edge‑Rules), Regression auf Chunk‑Mengen.

### Phase 2
- Hybrid‑Retrieval mit Graph‑Boosts, Explain‑Traces in API.  
- Subgraph‑Explorer, Governance‑Views (Review‑Queues).

### Phase 3
- ML‑gestützte Edge‑Vorschläge, temporale Graphanalysen, Reasoning‑Chains.  
- ACL/Sharing‑Modelle, Export/Archiv‑Pipelines.

---

## 8. Beispiel‑Konfigurationen
### 8.1 types.yaml (Beispiel – wie technisch)
```yaml
version: 1.0
types:
  concept:
    chunk_profile: medium
    edge_defaults: ["references", "related_to"]
    retriever_weight: 0.33
  task:
    chunk_profile: short
    edge_defaults: ["depends_on", "belongs_to"]
    retriever_weight: 0.8
  experience:
    chunk_profile: medium
    edge_defaults: ["derived_from", "inspired_by"]
    retriever_weight: 0.9
  project:
    chunk_profile: long
    edge_defaults: ["references", "depends_on"]
    retriever_weight: 0.95
```

### 8.2 retrieval.yaml
```yaml
relation_weights:
  references: 1.0
  related_to: 0.6
  depends_on: 1.2
  belongs_to: 0.8
  derived_from: 1.1
  inspired_by: 0.8
  supports: 1.0
  contradicts: -0.9
mixing:
  alpha: 0.45
  beta:  0.25
  gamma: 0.20
  delta: 0.07
  epsilon: 0.03
time_decay:
  lambda: 0.0025
```

---

## 9. Governance & Nachvollziehbarkeit
- **Decision Log** (ADR‑ähnlich): jedes Regel‑/Schema‑Update mit Begründung.  
- **Import‑Protokolle** versioniert, inkl. geänderter Dateien, Chunk‑/Edge‑Zahlen.  
- **Explainability Standard** in jeder Antwort.

---

## Anhang A: Glossar
- **Chunk‑Profil**: Regelset zur Textteilung.  
- **Rule‑Edge**: automatisch erzeugte Kante auf Basis von Typregeln.  
- **Declared Edge**: explizit gesetzte Kante aus der Quelle.