mindnet/docs/00_General/00_documentation_map.md

Mindnet v2.6 – Documentation Map & Governance

Status: Active Context: Central Navigation & Maintenance Guide

1. Zweck dieses Dokuments

Diese Karte dient Entwicklern, dem Mindmaster und KI-Agenten als zentraler Einstiegspunkt. Sie beantwortet zwei Fragen:

1. Navigation: In welcher Datei finde ich Informationen zu Thema X?
2. Wartung: Ich arbeite an Feature Y – welche Dateien muss ich aktualisieren?

---

2. Verzeichnisstruktur & Inhalte

Das Repository ist in logische Domänen unterteilt.

📂 00_General (Grundlagen)

Zielgruppe: Alle

Datei	Inhalt & Zweck
README.md	Einstiegspunkt. Übersicht über die Dokumentationsstruktur, Schnellzugriff nach Rollen und Navigation.
00_quickstart.md	Schnellstart. Installation und erste Schritte in 15 Minuten. Ideal für neue Benutzer.
00_vision_and_strategy.md	Strategie. Warum bauen wir das? Prinzipien (Privacy, Local-First), High-Level Architektur.
00_glossary.md	Definitionen. Was bedeutet "Smart Edge", "Traffic Control", "Chunk"? Verhindert Begriffsverwirrung.
00_documentation_map.md	Dieser Index. Navigationshilfe.
00_quality_checklist.md	Qualitätsprüfung. Systematische Checkliste zur Vollständigkeitsprüfung für alle Rollen.

📂 01_User_Manual (Anwendung)

Zielgruppe: Mindmaster, Autoren, Power-User

Datei	Inhalt & Zweck
01_chat_usage_guide.md	Bedienung. Wie steuere ich die Personas (Berater, Spiegel)? Wie nutze ich das Feedback?
01_knowledge_design.md	Content-Regeln. Die "Bibel" für den Vault. Erklärt Note-Typen, Matrix-Logik und Markdown-Syntax.
01_authoring_guidelines.md	Content strukturieren. Primäres Werkzeug, um Wissen so zu strukturieren, dass Mindnet die Persönlichkeit spiegelt, empathisch reagiert und strategisch berät.
01_obsidian_integration_guide.md	Obsidian Setup. Technische Anleitung für die Integration von Mindnet mit Obsidian (Templater, Skripte, Workflows).

📂 02_Concepts (Fachliche Logik)

Zielgruppe: Architekten, Product Owner

Datei	Inhalt & Zweck
02_concept_graph_logic.md	Graph-Theorie. Abstrakte Erklärung von Knoten, Kanten, Provenance und Idempotenz.
02_concept_ai_personality.md	KI-Verhalten. Konzepte hinter dem Hybrid Router, Empathie-Modell und "Teach-the-AI".
02_concept_architecture_patterns.md	Architektur-Patterns. Design-Entscheidungen, modulare Struktur (WP-14), Resilienz-Patterns und Erweiterbarkeit.

📂 03_Technical_Reference (Technik & Code)

Zielgruppe: Entwickler, DevOps. (Enthält JSON/YAML Beispiele)

Datei	Inhalt & Zweck
03_tech_data_model.md	Datenbank. Exakte Qdrant-Schemas (Payloads) und Index-Anforderungen.
03_tech_ingestion_pipeline.md	Import. Ablauflogik (13 Schritte), Chunker-Profile, Smart Edge Allocation.
03_tech_retrieval_scoring.md	Suche. Die mathematischen Formeln für Scoring, Hybrid Search und Explanation Layer.
03_tech_chat_backend.md	API & LLM. Implementation des Routers, Traffic Control (Semaphore) und Feedback-Traceability.
03_tech_frontend.md	UI & Graph. Architektur des Streamlit-Frontends, State-Management, Cytoscape-Integration und Editor-Logik.
03_tech_configuration.md	Config. Referenztabellen für .env, types.yaml und retriever.yaml.
03_tech_api_reference.md	API-Referenz. Vollständige Dokumentation aller Endpunkte (/query, /chat, /ingest, /graph, etc.).

📂 04_Operations (Betrieb)

Zielgruppe: Administratoren

Datei	Inhalt & Zweck
04_admin_operations.md	Runbook. Installation, Docker-Setup, Backup/Restore, Troubleshooting Guide.
04_server_operation_manual.md	Server-Betrieb. Detaillierte Dokumentation für den Betrieb auf llm-node (Systemd, Borgmatic, Disaster Recovery).
04_deployment_guide.md	Deployment. CI/CD-Pipelines, Rollout-Strategien, Versionierung, Rollback und Pre/Post-Deployment-Checklisten.

📂 05_Development (Code)

Zielgruppe: Entwickler

Datei	Inhalt & Zweck
05_developer_guide.md	Workflow. Hardware-Setup (Win/Pi/Beelink), Git-Flow, Test-Befehle, Modul-Interna.
05_genai_best_practices.md	AI Workflow. Prompt-Library, Templates und Best Practices für die Entwicklung mit LLMs.
05_testing_guide.md	Testing. Umfassender Test-Guide: Strategien, Frameworks, Test-Daten, Best Practices.

📂 06_Roadmap & 99_Archive

Zielgruppe: Projektleitung

Datei	Inhalt & Zweck
06_active_roadmap.md	Zukunft. Aktive Workpackages (WP16+), Release-Planung und WP-Historie (Tabelle).
99_legacy_workpackages.md	Vergangenheit. Detaillierte Archivdaten zu abgeschlossenen WPs (WP01–WP15).

---

3. Maintenance Guide: "Welche Datei muss ich ändern?"

Nutze diese Matrix, wenn du ein Workpackage bearbeitest, um die Dokumentation konsistent zu halten.

Wenn du arbeitest an...	...aktualisiere diese Dateien:
Neuen Note-Typen	1. 01_knowledge_design.md (Für Autoren) 2. 03_tech_configuration.md (Technische Referenz) 3. 05_developer_guide.md (Erweiterungs-How-To)
Importer / Parsing	03_tech_ingestion_pipeline.md
Datenbank-Schema	03_tech_data_model.md (Payloads anpassen)
Retrieval / Scoring	03_tech_retrieval_scoring.md (Formeln anpassen)
Frontend / Visualisierung	1. 03_tech_frontend.md (Technische Details) 2. 01_chat_usage_guide.md (Bedienung)
Chat-Logik / Prompts	1. 02_concept_ai_personality.md (Konzept) 2. 03_tech_chat_backend.md (Tech) 3. 01_chat_usage_guide.md (User-Sicht)
Architektur / Design-Patterns	1. 02_concept_architecture_patterns.md (Patterns & Entscheidungen) 2. 02_concept_graph_logic.md (Graph-Theorie) 3. 05_developer_guide.md (Modulare Struktur)
Deployment / Server	1. 04_deployment_guide.md (CI/CD, Rollout) 2. 04_admin_operations.md (Installation, Wartung) 3. 04_server_operation_manual.md (Server-Betrieb)
Testing / QA	1. 05_testing_guide.md (Test-Strategien & Frameworks) 2. 05_developer_guide.md (Test-Befehle)
Neuen Features (Allg.)	06_active_roadmap.md (Status Update)

---

4. Prinzipien für die Dokumentation (Governance)

Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten folgende Regeln:

1. Single Source of Truth: Kopiere keine Informationen. Referenziere sie.

   • Ausnahme: Konkrete JSON-Beispiele in 03_Technical_Reference. Diese müssen dort stehen, damit Entwickler nicht suchen müssen.

2. Konkrete Beispiele: Technische Dokumente (03_*) müssen immer Code-Snippets (JSON, YAML, Shell) enthalten. Abstrakte Beschreibungen reichen nicht für die Implementierung.

3. Human Readable: User Manuals (01_*) müssen Narrative und Szenarien enthalten ("Stell dir vor..."), keine technischen Auflistungen.

4. KI-Optimiert (Context Header): Jede Datei muss mit einem YAML-Frontmatter beginnen, der context, audience und scope definiert. Dies hilft RAG-Systemen, den Inhalt korrekt einzuordnen.

   ---
   doc_type: technical_reference
   audience: developer
   context: "Beschreibung der Scoring-Formel."
   ---
   

---

5. Schnellzugriff & Empfehlungen

Für neue Benutzer

1. Starte mit Schnellstart für die Installation
2. Lese Vision & Strategie für das große Bild
3. Nutze Chat Usage Guide für die ersten Schritte

Für Entwickler

1. Developer Guide - Umfassender technischer Guide
2. Technical References - Detaillierte API- und Architektur-Dokumentation
3. GenAI Best Practices - Workflow mit LLMs

Für Administratoren

1. Admin Operations - Installation und Wartung
2. Server Operations Manual - Server-Betrieb und Disaster Recovery
3. Troubleshooting Guide - Häufige Probleme und Lösungen

Für Autoren

1. Knowledge Design - Content-Regeln und Best Practices
2. Authoring Guidelines - Strukturierung für den Digitalen Zwilling
3. Obsidian Integration - Workflow-Optimierung

---

6. Dokumentations-Status

Aktuelle Version: 2.9.1
Letzte Aktualisierung: 2025-01-XX
Status: ✅ Vollständig und aktiv gepflegt

Hinweis: Diese Dokumentation wird kontinuierlich aktualisiert. Bei Fragen oder Verbesserungsvorschlägen bitte im Repository melden.