mindnet/docs/05_Development/05_developer_guide.md

doc_type	audience	scope	status	version	context
developer_guide	developer	workflow, testing, architecture, modules	active	2.6	Umfassender Guide für Entwickler: Architektur, Modul-Interna (Deep Dive), Setup, Git-Workflow und Erweiterungs-Anleitungen.

Mindnet Developer Guide & Workflow

Quellen: developer_guide.md, dev_workflow.md

Dieser Guide vereint das technische Verständnis der Module mit dem operativen Workflow zwischen Windows (Dev) und Linux (Runtime).

---

1. Die physische Architektur

Mindnet läuft in einer verteilten Umgebung (Post-WP15 Setup).

• Windows 11 (VS Code): Hier schreibst du Code. Nie direkt auf main arbeiten!
• Beelink (Runtime): Der Server. Hier läuft die Software. Wir nutzen Systemd-Services:
  • PROD: API (8001) + UI (8501). Ordner: ~/mindnet.
  • DEV: API (8002) + UI (8502). Ordner: ~/mindnet_dev.
• Gitea: Der "Safe" (Raspberry Pi). Speichert den Code und verwaltet Versionen.

---

2. Projektstruktur & Referenz

2.1 Verzeichnisbaum

mindnet/
├── app/
│   ├── core/           # Ingestion, Chunker, Qdrant Wrapper
│   ├── routers/        # FastAPI Endpoints
│   ├── services/       # Ollama Client, Traffic Control
│   ├── models/         # Pydantic DTOs
│   └── frontend/       # Streamlit UI Module
├── config/             # YAML Configs (Single Source of Truth)
├── scripts/            # CLI Tools (Import, Diagnose, Reset)
├── tests/              # Pytest Suite & Smoke Scripts
└── vault/              # Lokaler Test-Content

2.2 Vollständige Datei-Referenz (Auto-Scan)

Eine Übersicht aller Skripte und Module im System.

Datei/Pfad	Typ	Beschreibung
Backend Core
app/main.py	Skript	Bootstrap der FastAPI API.
app/config.py	Config	Zentrale Konfiguration (Pydantic Settings).
app/core/ingestion.py	Core Modul	Async Ingestion Service & Change Detection.
app/core/chunker.py	Core Modul	Smart Chunker Orchestrator.
app/core/retriever.py	Core Modul	Hybrider Such-Algorithmus (Semantik + Graph).
app/core/ranking.py	Core Modul	Kombiniertes Scoring (WP-04).
app/core/graph_adapter.py	Core Modul	Adjazenzaufbau & Subgraph-Expansion.
app/core/qdrant.py	Core Modul	Qdrant Client Wrapper.
app/core/qdrant_points.py	Core Modul	Robuste Point-Helper für Qdrant (Retry-Logik).
app/core/derive_edges.py	Core Modul	Edge-Erzeugung aus Markdown.
app/core/edges.py	Core Modul	Datenstrukturen für Kanten.
app/core/edges_writer.py	Core Modul	Schreibt Kanten in die DB.
app/core/note_payload.py	Core Modul	Builder für Note-Metadaten.
app/core/chunk_payload.py	Core Modul	Builder für Chunk-Payloads.
app/core/type_registry.py	Core Modul	Logik zum Laden der types.yaml.
app/core/schema_loader.py	Core Modul	Lädt JSON-Schemas für Validierung.
app/core/env_vars.py	Core Modul	Environment-Variablen Konstanten.
API Router
app/routers/chat.py	API Router	RAG Endpunkt & Hybrid Router.
app/routers/query.py	API Router	Query-Endpunkte (WP-04).
app/routers/graph.py	API Router	Graph-Endpunkte (WP-04).
app/routers/ingest.py	API Router	Ingestion-Trigger & Analyse.
app/routers/feedback.py	API Router	Feedback-Endpunkt.
app/routers/tools.py	API Router	Tool-Definitionen für Ollama/n8n/MCP.
app/routers/admin.py	API Router	Admin-/Monitoring-Endpunkte.
Services
app/services/llm_service.py	Service	LLM Client mit Traffic Control.
app/services/llm_ollama.py	Service	Legacy: Ollama-Integration & Prompt-Bau.
app/services/embeddings_client.py	Service	Async Text→Embedding Service.
app/services/semantic_analyzer.py	Service	Smart Edge Validation & Filtering.
app/services/discovery.py	Service	Backend Intelligence (Matrix-Logik).
app/services/feedback_service.py	Service	Schreibt JSONL-Logs.
Frontend
app/frontend/ui.py	Frontend	Entrypoint (Streamlit).
app/frontend/ui_editor.py	Frontend	Editor-View & Logic.
app/frontend/ui_chat.py	Frontend	Chat-View.
app/frontend/ui_graph_cytoscape.py	Frontend	Graph-Visualisierung (Modern).
app/frontend/ui_graph.py	Frontend	Graph-Visualisierung (Legacy).
app/frontend/ui_graph_service.py	Frontend	Datenaufbereitung für Graphen.
app/frontend/ui_callbacks.py	Frontend	Event-Handler.
app/frontend/ui_api.py	Frontend	Backend-Bridge.
app/frontend/ui_utils.py	Frontend	Helper (Healing Parser).
app/frontend/ui_config.py	Frontend	Konstanten (Farben, URLs).
CLI & Scripts
scripts/import_markdown.py	Skript	Haupt-Importer CLI.
scripts/reset_qdrant.py	Skript	Löscht Collections (--mode wipe).
scripts/payload_dryrun.py	Skript	Zeigt Payloads VOR dem Upsert.
scripts/edges_dryrun.py	Skript	Erzeugt Edges ohne DB-Write.
scripts/edges_full_check.py	Skript	Prüft Graph-Integrität.
scripts/resolve_unresolved_references.py	Skript	Löst Wikilinks nachträglich auf.
scripts/audit_vault_vs_qdrant.py	Skript	Konsistenz-Check File vs. DB.
scripts/audit_edges_vs_expectations.py	Skript	Prüft Kanten gegen Erwartungswert.
scripts/setup_mindnet_collections.py	Skript	Richtet Collections initial ein.
scripts/export_markdown.py	Skript	Exportiert Qdrant zurück zu Markdown.
scripts/wp04_smoketest.py	Skript	E2E-Schnelltest der WP-04 Endpunkte.
scripts/health_check_mindnet.py	Skript	System Health Check.
scripts/report_hashes.py	Skript	Übersicht bei Mehrfach-Hashes.
scripts/make_test_vault.py	Skript	Erzeugt minimalen Test-Vault.
scripts/ollama_tool_runner.py	Skript	Minimaler Tool-Caller für Ollama.

---

3. Core-Module im Detail (Architektur)

Hier wird erklärt, wie die wichtigsten Komponenten unter der Haube arbeiten.

3.1 Der Importer (scripts.import_markdown)

Dies ist das komplexeste Modul.

• Orchestrierung: Es ruft app.core.chunker für die Textzerlegung und app.services.semantic_analyzer für Smart Edges auf.
• Idempotenz: Der Importer kann beliebig oft laufen. Er nutzt deterministische IDs (UUIDv5) und überschreibt vorhandene Einträge konsistent.
• Robustheit: In ingestion.py sind Mechanismen wie Change Detection (Hash-Vergleich) und Robust File I/O implementiert.

3.2 Der Hybrid Router (app.routers.chat)

Hier liegt die Logik für Intent Detection (WP06) und Interview-Modus (WP07).

• Question Detection: Prüft zuerst regelbasiert, ob der Input eine Frage ist (?, W-Wörter). Falls ja -> RAG.
• Keyword Match: Prüft Keywords aus decision_engine.yaml und types.yaml.
• Priority: Ruft llm_service mit priority="realtime" auf, um die Import-Warteschlange zu umgehen.

3.3 Der Retriever (app.core.retriever)

Hier passiert das Scoring (WP04a).

• Hybrid Search: Der Chat-Endpoint erzwingt mode="hybrid".
• Strategic Retrieval: In chat.py wird der Retriever ggf. zweimal aufgerufen, wenn ein Intent (z.B. DECISION) eine Injection (value) erfordert.

3.4 Das Frontend (app.frontend.ui)

Eine Streamlit-App (WP10/19).

• Resurrection Pattern: Das UI nutzt ein spezielles State-Management (st.session_state), um Eingaben bei Tab-Wechseln (Chat <-> Editor) zu erhalten. Widgets synchronisieren sich via Callbacks.
• Healing Parser: Die Funktion parse_markdown_draft repariert defekte YAML-Frontmatter (z.B. fehlendes ---) vom LLM automatisch.

3.5 Traffic Control (app.services.llm_service)

Neu in v2.6. Stellt sicher, dass Batch-Prozesse (Import) den Live-Chat nicht ausbremsen.

• Methode: generate_raw_response(..., priority="background") aktiviert eine Semaphore.
• Limit: Konfigurierbar über MINDNET_LLM_BACKGROUND_LIMIT (Default: 2).

---

4. Lokales Setup (Development)

Voraussetzungen: Python 3.10+, Docker, Ollama.

Installation:

# 1. Repo & Venv
git clone <repo> mindnet
cd mindnet
python3 -m venv .venv
source .venv/bin/activate

# 2. Dependencies
pip install -r requirements.txt

# 3. Ollama (Nomic ist Pflicht!)
ollama pull phi3:mini
ollama pull nomic-embed-text

Konfiguration (.env):

QDRANT_URL="http://localhost:6333"
COLLECTION_PREFIX="mindnet_dev"
VECTOR_DIM=768
MINDNET_LLM_BACKGROUND_LIMIT=2
MINDNET_API_URL="http://localhost:8002"
MINDNET_LLM_TIMEOUT=300.0

---

5. Der Entwicklungs-Zyklus (Workflow)

Phase 1: Windows (Code)

1. Basis aktualisieren: git checkout main && git pull.
2. Branch erstellen: git checkout -b feature/mein-feature.
3. Coden & Committen.
4. Push: git push origin feature/mein-feature.

Phase 2: Beelink (Test / Dev)

Hier prüfst du, ob dein Code auf Linux läuft.

1. Einloggen: ssh user@beelink.
2. Ordner: cd ~/mindnet_dev.
3. Code holen: git fetch && git checkout feature/mein-feature && git pull.
4. Dependencies: pip install -r requirements.txt.
5. Restart: sudo systemctl restart mindnet-dev.
6. Validierung (Smoke Tests):
   • Last-Test: Starte python3 -m scripts.import_markdown ... im Terminal und chatte gleichzeitig im UI (Port 8502).
   • API Check: curl -X POST "http://localhost:8002/ingest/analyze" ...

Phase 3: Release & Deployment (Prod)

Wenn alles getestet ist:

1. Gitea: Pull Request erstellen und mergen.
2. Deploy auf Prod (Beelink):

   cd ~/mindnet
   git pull origin main
   
   # Sicherstellen, dass Prod-Dependencies aktuell sind
   source .venv/bin/activate
   pip install -r requirements.txt
   ollama pull nomic-embed-text # Falls neue Modelle nötig sind
   
   # Restart
   sudo systemctl restart mindnet-prod
   sudo systemctl restart mindnet-ui-prod
   

3. Cleanup: Branch löschen (lokal und remote).

---

6. Erweiterungs-Guide: "Teach-the-AI"

Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch Konfiguration und Vernetzung.

Workflow A: Neuen Typ implementieren (z. B. type: risk)

1. Physik (config/types.yaml):

   risk:
     retriever_weight: 0.90       # Sehr wichtig
     edge_defaults: ["blocks"]    # Automatische Kante
     detection_keywords: ["gefahr", "risiko"]
   

2. Strategie (config/decision_engine.yaml):

   DECISION:
     inject_types: ["value", "risk"] # <--- "risk" hinzufügen
   

   Ergebnis: Wenn der Intent DECISION erkannt wird, sucht das System nun auch aktiv nach Risiken.

Workflow B: Interview-Schema anpassen (WP07)

Wenn Mindnet neue Fragen stellen soll (z.B. "Budget" bei Projekten):

1. Schema (config/types.yaml):

   project:
     schema: 
       - "Titel"
       - "Ziel"
       - "Budget (Neu)"
   

2. Kein Code nötig: Der One-Shot Extractor (Prompt Template) liest diese Liste dynamisch.

---

7. Tests & Debugging

Unit Tests (Pytest):

pytest tests/test_retriever_basic.py
pytest tests/test_chunking.py

Pipeline Tests (Integration):

# JSON-Schema prüfen
python3 -m scripts.payload_dryrun --vault ./test_vault

# Graph-Integrität prüfen
python3 -m scripts.edges_full_check

E2E Smoke Tests:

# Decision Engine
python tests/test_wp06_decision.py -p 8002 -e DECISION -q "Soll ich X tun?"

# Feedback
python tests/test_feedback_smoke.py --url http://localhost:8002/query

---

8. Troubleshooting & One-Liners

DB komplett zurücksetzen (Vorsicht!):

# --yes überspringt die Bestätigung
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes

Einen einzelnen File inspizieren (Parser-Sicht):

python3 tests/inspect_one_note.py --file ./vault/MeinFile.md

Live-Logs sehen:

journalctl -u mindnet-dev -f
journalctl -u mindnet-ui-dev -f

"UnicodeDecodeError in .env":

• Ursache: Umlaute oder Sonderzeichen in der .env.
• Lösung: Datei bereinigen (nur ASCII) und sicherstellen, dass UTF-8 ohne BOM genutzt wird.