# 📚 MindSift Technische Dokumentation & Wiki

Willkommen in der zentralen technischen Dokumentation von **MindSift**. Dieses Wiki dient als verbindliche, tiefgehende Referenz für Entwickler, DevOps-Ingenieure und Systemadministratoren. Es dokumentiert die Architektur, das Datenmodell, APIs, Echtzeit-Protokolle, Kernmodule sowie bekannte technische Schwachstellen der Plattform.

---

## 🧭 Inhaltsverzeichnis (Wiki-Navigation)

```
Doku/
├── README.md                  # Einstieg, Inhaltsverzeichnis & Gesamtübersicht (dieses Dokument)
├── architecture.md            # Systemarchitektur, Schichtenmodell, Concurrency & Stack
├── database.md                # SQLite-Datenbankdesign, Schemas, Indizes & Migrationen
├── api/
│   ├── rest.md                # Vollständige REST-API Referenz aller Endpunkte
│   └── websocket.md           # WebSocket-Echtzeitprotokoll, Rooms & Document Locking
├── modules/
│   ├── triage.md              # Modul 1: Triage & Quick-Dump (State Machine & Audio)
│   ├── tasks.md               # Modul 2: Aufgaben & Kanban-System (Alarme & Scheduler)
│   ├── workspace.md           # Modul 3: Workspace Outliner-Engine, Wiki-Links & Pure-DB Storage
│   └── lists.md               # Modul 4: Geteilte Listen (Live-Kollaboration & D&D)
├── sharing-and-permissions.md # Synchrones Teilen, Rollen, Isolation & Mount-Entkopplung
├── reverse-proxy.md           # Nginx, Traefik, Caddy, Cloudflare Konfiguration & SSE
├── theming.md                 # Single-File CSS Theme-Engine & Design-System
└── flaws.md                   # Technische Schwachstellen, Risiken & zukünftige Optimierungen
```

### 📑 Kapitel im Detail
1. **[Systemarchitektur & Technologie-Stack](architecture.md)**  
   Schichtenmodell, Go-Backend, React-Frontend, Concurrency-Handling und Thread-Safety.
2. **[Datenbank-Design & SQLite Schema](database.md)**  
   Vollständiges relationales Datenmodell, ER-Diagramm, Tabellendefinitionen, Indizes und Migrationsstrategie.
3. **[REST-API Referenz](api/rest.md)**  
   Spezifikation aller Endpunkte für Authentifizierung, Gedanken, Aufgaben, Dokumente, Listen, Teams und Webhooks.
4. **[WebSocket & Echtzeit-Synchronisation](api/websocket.md)**  
   Gorilla WebSocket Hub, Rooms, Presence-Tracking, Yjs CRDT Kollaboration und SSE Fallback.
5. **[Kernmodul: Triage & Quick-Dump](modules/triage.md)**  
   Instant-Capture-Pipeline, Finite State Machine, Gestensteuerung, Spracheingabe und Webhook-Ingestion.
6. **[Kernmodul: Aufgaben & Kanban-System](modules/tasks.md)**  
   Multi-Listen-Konzept, 3-Spalten Kanban-Board, Subtasks, Fälligkeiten und Multi-Channel Alarm-Ticker (SMTP, Discord, Webhooks).
7. **[Kernmodul: Workspace & Outliner-Engine](modules/workspace.md)**  
   Logseq-inspirierte hierarchische Block-Engine, Zoom-Hoisting, Wiki-Links, Pure-Database Storage und Globales To-Do Rollup.
8. **[Kernmodul: Geteilte Listen & Kollaboration](modules/lists.md)**  
   Listen-Typen, Mengen, Kategorien, Live-Checkoff und Drag & Drop Sortierung.
9. **[Synchrones Teilen & Berechtigungskonzept](sharing-and-permissions.md)**  
   Rollenmodell (Admin/Member), System-Isolations-Modi (`strict_private`, `teams_only`, `open`), entkoppelte Ordner-Mounts und Notizen-Freigaben.
10. **[Reverse-Proxy- & Ingress-Handbuch](reverse-proxy.md)**  
    Produktionsfertige Konfigurationen für Nginx, Traefik, Caddy, Cloudflare und Apache mit WebSocket-Upgrades und SSE-Streaming.
11. **[Single-File Theming & Design-System](theming.md)**  
    1-Datei = 1-Theme Philosophie, die 6 CSS-Variablen-Blöcke, Semantische CSS-Klassen und Geometrie-Steuerung.
12. **[Technische Schwachstellen & Optimierungspotenziale (Flaws)](flaws.md)**  
    Kritische Analyse von Concurrency-Grenzen, Volltextsuche, Viewport-Anpassung und Skalierungs-Engpässen.

---

## 🏛️ Systemübersicht (High-Level Architektur)

```mermaid
graph TB
    subgraph Client ["Client Layer (Browser / PWA)"]
        UI["React 18 SPA (Vite, TS, Tailwind)"]
        WSClient["WebSocket Client (Auto-Reconnect)"]
        Cache["IndexedDB / Offline Queue"]
    end

    subgraph ReverseProxy ["Reverse Proxy / Gateway"]
        Traefik["Traefik / Nginx (HTTPS, WSS, Rate Limits)"]
    end

    subgraph Backend ["Backend Layer (Go 1.23 Engine)"]
        ChiRouter["Chi Router (REST API)"]
        WSHub["Gorilla WebSocket Hub & Lock Manager"]
        AlarmTicker["Alarm Scheduler (Background Ticker)"]
        StorageEngine["Storage Layer (Domain & Repositories)"]
    end

    subgraph Storage ["Storage Layer"]
        SQLite[("SQLite WAL Database (/data/mindsift.db)")]
    end

    subgraph External ["Externe Schnittstellen"]
        HomeAssistant["Home Assistant / Webhooks"]
        Discord["Discord Webhooks"]
        SMTPServer["SMTP Server (E-Mail Alarme)"]
    end

    UI -->|HTTPS REST| Traefik
    WSClient -->|WSS Realtime| Traefik
    Traefik --> ChiRouter
    Traefik --> WSHub
    ChiRouter --> StorageEngine
    StorageEngine --> SQLite
    AlarmTicker --> Discord
    AlarmTicker --> SMTPServer
    HomeAssistant -->|POST /api/v1/inbox| Traefik
    HomeAssistant -->|POST /api/v1/webhooks/ingest| Traefik
```

---

## 🛠️ Schnellstart für Entwickler

### Voraussetzungen
- **Go:** 1.22 oder 1.23+
- **Node.js:** 20+ (LTS) & npm
- **Container-Runtime:** Docker oder Podman

### Lokale Entwicklung ohne Container
```bash
# 1. Repository klonen
git clone https://git.dsit.me/sandrodach/MindSift.git
cd MindSift

# 2. Frontend Abhängigkeiten installieren & Dev-Server starten
cd frontend
npm install
npm run dev

# 3. Backend starten (in neuem Terminal)
cd ..
go run ./cmd/server
```

### Container Build & Testlauf (wie in der CI/CD)
```bash
# Backend-Tests ausführen
podman run --rm -v $(pwd):/app:z -w /app golang:1.23 go test -v ./internal/...

# Frontend Typecheck & Build testen
podman run --rm -v $(pwd):/app:z -w /app/frontend node:20 sh -c "npx tsc --noEmit && npm run build"

# Komplettes Multi-Stage Image bauen
podman build -t mindsift:dev .
```