--- doc_type: developer_guide audience: developer scope: workflow, testing, architecture, modules status: active version: 2.6 context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna, 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! * **Raspberry Pi (Gitea):** Der "Safe". Speichert den Code und verwaltet Versionen. * **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`. --- ## 2. Projektstruktur & Core-Module Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt. ### 2.1 Verzeichnisbaum ```text mindnet/ ├── app/ │ ├── core/ # Kernlogik │ │ ├── ingestion.py # Async Ingestion Service mit Change Detection │ │ ├── chunker.py # Smart Chunker Orchestrator │ │ ├── derive_edges.py # Edge-Erzeugung (WP03 Logik) │ │ ├── retriever.py # Scoring & Hybrid Search │ │ └── qdrant.py # DB-Verbindung │ ├── routers/ # FastAPI Endpoints │ │ ├── query.py # Suche │ │ ├── chat.py # Hybrid Router v5 & Interview Logic │ │ └── feedback.py # Feedback (WP04c) │ ├── services/ # Interne & Externe Dienste │ │ ├── llm_service.py # Ollama Client mit Traffic Control │ │ ├── semantic_analyzer.py# LLM-Filter für Edges (WP15) │ │ ├── embeddings_client.py# Async Embeddings (HTTPX) │ │ └── discovery.py # Intelligence Logic (WP11) │ ├── frontend/ # UI Logic (WP19 Modularisierung) │ │ ├── ui.py # Main Entrypoint & Routing │ │ ├── ui_config.py # Styles & Constants │ │ ├── ui_api.py # Backend Connector │ │ ├── ui_callbacks.py # State Transitions │ │ ├── ui_utils.py # Helper & Parsing │ │ ├── ui_graph_service.py # Graph Data Logic │ │ ├── ui_graph_cytoscape.py # Modern Graph View (St-Cytoscape) │ │ └── ui_editor.py # Editor View │ └── main.py # Entrypoint der API ├── config/ # YAML-Konfigurationen (Single Source of Truth) ├── scripts/ # CLI-Tools (Import, Diagnose, Reset) ├── tests/ # Pytest Suite & Smoke Scripts └── vault/ # Dein lokaler Markdown-Content ``` ### 2.2 Modul-Details (Wie es funktioniert) **Das Frontend (`app.frontend`) - *Neu in v2.6*** * **Router (`ui.py`):** Entscheidet, welche View geladen wird. * **Service-Layer (`ui_graph_service.py`):** Kapselt die Qdrant-Abfragen. Liefert rohe Nodes/Edges, die dann von den Views visualisiert werden. * **Graph Engine:** Wir nutzen `st-cytoscape` für das Layout. Die Logik zur Vermeidung von Re-Renders (Stable Keys, CSS-Selektion) ist essentiell. * **Data Consistency:** Der Editor (`ui_editor.py`) liest Dateien bevorzugt direkt vom Dateisystem ("File System First"), um Datenverlust durch veraltete DB-Einträge zu vermeiden. **Der Importer (`scripts.import_markdown`)** * Das komplexeste Modul. * Nutzt `app.core.chunker` und `app.services.semantic_analyzer` (Smart Edges). * **Idempotenz:** Nutzt deterministische UUIDv5 IDs. Kann beliebig oft laufen. * **Robustheit:** Implementiert Change Detection (Hash) und Retry-Logik. **Der Hybrid Router (`app.routers.chat`)** * Hier liegt die Logik für Intent Detection (WP06). * **Question Detection:** Prüft auf `?` und W-Wörter. * **Priority:** Ruft `llm_service` mit `priority="realtime"` auf (umgeht Import-Warteschlange). **Der Retriever (`app.core.retriever`)** * Implementiert die Scoring-Formel (`Semantik + Graph + Typ`). * **Hybrid Search:** Lädt dynamisch den Subgraphen (`graph_adapter.expand`). **Traffic Control (`app.services.llm_service`)** * Stellt sicher, dass der Chat responsive bleibt, auch wenn ein Import läuft. * Nutzt `asyncio.Semaphore` (`MINDNET_LLM_BACKGROUND_LIMIT`), um Hintergrund-Jobs zu drosseln. --- ## 3. Lokales Setup (Development) **Voraussetzungen:** Python 3.10+, Docker, Ollama. **Installation:** ```bash # 1. Repo & Venv git clone mindnet cd mindnet python3 -m venv .venv source .venv/bin/activate # 2. Dependencies (inkl. st-cytoscape) pip install -r requirements.txt # 3. Ollama (Nomic ist Pflicht!) ollama pull phi3:mini ollama pull nomic-embed-text ``` **Konfiguration (.env):** ```ini 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 ``` --- ## 4. Der Entwicklungs-Zyklus ### Phase 1: Windows (Code) 1. **Basis holen:** `git checkout main && git pull`. 2. **Branch:** `git checkout -b feature/mein-feature`. 3. **Code & Push:** `git push origin feature/mein-feature`. ### Phase 2: Beelink (Test) 1. **SSH:** `ssh user@beelink`. 2. **Ordner:** `cd ~/mindnet_dev`. 3. **Checkout:** `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 ...` und chatte gleichzeitig im UI (Port 8502). * **API Check:** `curl -X POST "http://localhost:8002/ingest/analyze" ...` ### Phase 3: Release & Deploy 1. **Gitea:** Pull Request erstellen und mergen. 2. **Beelink (Prod):** ```bash cd ~/mindnet git pull origin main sudo systemctl restart mindnet-prod ``` 3. **Cleanup:** Branch löschen. --- ## 5. Erweiterungs-Guide: "Teach-the-AI" Mindnet lernt durch Konfiguration, nicht durch Training. ### Workflow A: Neuen Typ implementieren (z. B. `type: risk`) 1. **Physik (`types.yaml`):** ```yaml risk: retriever_weight: 0.90 edge_defaults: ["blocks"] detection_keywords: ["gefahr", "risiko"] ``` 2. **Strategie (`decision_engine.yaml`):** ```yaml DECISION: inject_types: ["value", "risk"] # Füge 'risk' hinzu ``` 3. **Visualisierung (`ui_config.py`):** Füge dem `GRAPH_COLORS` Dictionary einen Eintrag hinzu: ```python "risk": "#ff6b6b" ``` ### Workflow B: Interview-Schema anpassen (WP07) Wenn Mindnet neue Fragen stellen soll (z.B. "Budget" bei Projekten): 1. **Schema (`types.yaml`):** ```yaml project: schema: - "Titel" - "Ziel" - "Budget (Neu)" ``` 2. **Kein Code nötig:** Der `One-Shot Extractor` liest dies dynamisch. --- ## 6. Tests & Debugging **Unit Tests:** ```bash pytest tests/test_retriever_basic.py pytest tests/test_chunking.py ``` **Pipeline Tests:** ```bash # 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:** ```bash # 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 ``` --- ## 7. Troubleshooting & One-Liners **DB komplett zurücksetzen (Vorsicht!):** ```bash python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes ``` **Einen einzelnen File inspizieren (Parser-Sicht):** ```bash python3 tests/inspect_one_note.py --file ./vault/MeinFile.md ``` **Live-Logs sehen:** ```bash journalctl -u mindnet-dev -f journalctl -u mindnet-ui-dev -f ``` **"Read timed out" im Frontend:** * Ursache: Backend braucht für Smart Edges länger als 60s. * Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env` setzen.