2025-12-13 18:38:37 +01:00
# Mindnet v2.6 –
**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 –
---
## 2. Verzeichnisstruktur & Inhalte
Das Repository ist in **logische Domänen** unterteilt.
### 📂 00_General (Grundlagen)
*Zielgruppe: Alle*
| Datei | Inhalt & Zweck |
| :--- | :--- |
2025-12-28 10:56:34 +01:00
| `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. |
2025-12-13 18:38:37 +01:00
| `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. |
2025-12-28 10:56:34 +01:00
| `00_quality_checklist.md` | **Qualitätsprüfung.** Systematische Checkliste zur Vollständigkeitsprüfung für alle Rollen. |
2025-12-13 18:38:37 +01:00
### 📂 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. |
2025-12-28 10:56:34 +01:00
| `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). |
2025-12-13 18:38:37 +01:00
### 📂 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". |
2025-12-28 10:56:34 +01:00
| `02_concept_architecture_patterns.md` | **Architektur-Patterns.** Design-Entscheidungen, modulare Struktur (WP-14), Resilienz-Patterns und Erweiterbarkeit. |
2025-12-13 18:38:37 +01:00
### 📂 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. |
2025-12-14 20:47:49 +01:00
| `03_tech_frontend.md` | **UI & Graph.** Architektur des Streamlit-Frontends, State-Management, Cytoscape-Integration und Editor-Logik. |
2025-12-13 18:38:37 +01:00
| `03_tech_configuration.md` | **Config.** Referenztabellen für `.env` , `types.yaml` und `retriever.yaml` . |
2025-12-28 10:56:34 +01:00
| `03_tech_api_reference.md` | **API-Referenz.** Vollständige Dokumentation aller Endpunkte (`/query`, `/chat` , `/ingest` , `/graph` , etc.). |
2025-12-13 18:38:37 +01:00
### 📂 04_Operations (Betrieb)
*Zielgruppe: Administratoren*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `04_admin_operations.md` | **Runbook.** Installation, Docker-Setup, Backup/Restore, Troubleshooting Guide. |
2025-12-28 10:56:34 +01:00
| `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. |
2025-12-13 18:38:37 +01:00
### 📂 05_Development (Code)
*Zielgruppe: Entwickler*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `05_developer_guide.md` | **Workflow.** Hardware-Setup (Win/Pi/Beelink), Git-Flow, Test-Befehle, Modul-Interna. |
2025-12-15 17:32:38 +01:00
| `05_genai_best_practices.md` | **AI Workflow.** Prompt-Library, Templates und Best Practices für die Entwicklung mit LLMs. |
2025-12-28 10:56:34 +01:00
| `05_testing_guide.md` | **Testing.** Umfassender Test-Guide: Strategien, Frameworks, Test-Daten, Best Practices. |
2025-12-13 18:38:37 +01:00
### 📂 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–
---
## 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)< br > 2. `03_tech_configuration.md` (Technische Referenz)< br > 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) |
2025-12-14 20:47:49 +01:00
| **Frontend / Visualisierung** | 1. `03_tech_frontend.md` (Technische Details)< br > 2. `01_chat_usage_guide.md` (Bedienung) |
2025-12-13 18:38:37 +01:00
| **Chat-Logik / Prompts** | 1. `02_concept_ai_personality.md` (Konzept)< br > 2. `03_tech_chat_backend.md` (Tech)< br > 3. `01_chat_usage_guide.md` (User-Sicht) |
2025-12-28 10:56:34 +01:00
| **Architektur / Design-Patterns** | 1. `02_concept_architecture_patterns.md` (Patterns & Entscheidungen)< br > 2. `02_concept_graph_logic.md` (Graph-Theorie)< br > 3. `05_developer_guide.md` (Modulare Struktur) |
| **Deployment / Server** | 1. `04_deployment_guide.md` (CI/CD, Rollout)< br > 2. `04_admin_operations.md` (Installation, Wartung)< br > 3. `04_server_operation_manual.md` (Server-Betrieb) |
| **Testing / QA** | 1. `05_testing_guide.md` (Test-Strategien & Frameworks)< br > 2. `05_developer_guide.md` (Test-Befehle) |
2025-12-13 18:38:37 +01:00
| **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.
```yaml
---
doc_type: technical_reference
audience: developer
context: "Beschreibung der Scoring-Formel."
---
2025-12-28 10:56:34 +01:00
```
---
## 5. Schnellzugriff & Empfehlungen
### Für neue Benutzer
1. Starte mit ** [Schnellstart ](00_quickstart.md )** für die Installation
2. Lese ** [Vision & Strategie ](00_vision_and_strategy.md )** für das große Bild
3. Nutze ** [Chat Usage Guide ](../01_User_Manual/01_chat_usage_guide.md )** für die ersten Schritte
### Für Entwickler
1. ** [Developer Guide ](../05_Development/05_developer_guide.md )** - Umfassender technischer Guide
2. ** [Technical References ](../03_Technical_References/ )** - Detaillierte API- und Architektur-Dokumentation
3. ** [GenAI Best Practices ](../05_Development/05_genai_best_practices.md )** - Workflow mit LLMs
### Für Administratoren
1. ** [Admin Operations ](../04_Operations/04_admin_operations.md )** - Installation und Wartung
2. ** [Server Operations Manual ](../04_Operations/04_server_operation_manual.md )** - Server-Betrieb und Disaster Recovery
3. ** [Troubleshooting Guide ](../04_Operations/04_admin_operations.md#33-troubleshooting-guide )** - Häufige Probleme und Lösungen
### Für Autoren
1. ** [Knowledge Design ](../01_User_Manual/01_knowledge_design.md )** - Content-Regeln und Best Practices
2. ** [Authoring Guidelines ](../01_User_Manual/01_authoring_guidelines.md )** - Strukturierung für den Digitalen Zwilling
3. ** [Obsidian Integration ](../01_User_Manual/01_obsidian_integration_guide.md )** - Workflow-Optimierung
---
## 6. Dokumentations-Status
2026-01-01 20:24:09 +01:00
**Aktuelle Version:** 2.9.3
**Letzte Aktualisierung:** 2025-12-31
2025-12-28 10:56:34 +01:00
**Status:** ✅ Vollständig und aktiv gepflegt
**Hinweis:** Diese Dokumentation wird kontinuierlich aktualisiert. Bei Fragen oder Verbesserungsvorschlägen bitte im Repository melden.
