Lars
97c3461685
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 4s
113 lines
5.7 KiB
Markdown
113 lines
5.7 KiB
Markdown
# 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)<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) |
|
||
| **Frontend / Visualisierung** | 1. `03_tech_frontend.md` (Technische Details)<br>2. `01_chat_usage_guide.md` (Bedienung) |
|
||
| **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) |
|
||
| **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.
|
||
|
||
```yaml
|
||
---
|
||
doc_type: technical_reference
|
||
audience: developer
|
||
context: "Beschreibung der Scoring-Formel."
|
||
---
|
||
``` |