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
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.

📂 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	Content strukturieren-. primäres Werkzeug, um Wissen so zu strukturieren, so dass Mindnet die Persönlichkeit spiegelt, empathisch reagiert und strategisch berät

📂 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".

📂 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.

📂 04_Operations (Betrieb)

Zielgruppe: Administratoren

Datei	Inhalt & Zweck
04_admin_operations.md	Runbook. Installation, Docker-Setup, Backup/Restore, Troubleshooting Guide.

📂 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.

📂 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)
Deployment / Server	04_admin_operations.md
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."
   ---