sandrodach
0bdeb5f320
MindSift CI & Docker Release / Build, Test in Container & Push (push) Successful in 39s
132 lines
5.7 KiB
Markdown
132 lines
5.7 KiB
Markdown
# 📚 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
|
|
├── 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, Document Locking Mechanismen und Polling-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. **[Single-File Theming & Design-System](theming.md)**
|
|
1-Datei = 1-Theme Philosophie, die 6 CSS-Variablen-Blöcke, Semantische CSS-Klassen und Geometrie-Steuerung.
|
|
11. **[Technische Schwachstellen & Optimierungspotenziale (Flaws)](flaws.md)**
|
|
Kritische Analyse von Concurrency-Grenzen, WebSocket-Proxies, Undo/Redo, Volltextsuche 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 .
|
|
```
|