docs: rewrite documentation and README from current codebase, add flaw analysis
MindSift CI & Docker Release / Build, Test in Container & Push (push) Successful in 8s
MindSift CI & Docker Release / Build, Test in Container & Push (push) Successful in 8s
Remove outdated claims (CRDT, DocRooms, presence, .md files on disk) and document the actual architecture, API, permissions and known flaws. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
sandrodachandClaude Sonnet 5.5 committed
1 parent
4e9c4ffa8c
commit
bc13235da6
14 files changed
+733
-1618
No files matched your search
+29
-123
@@ -1,134 +1,40 @@
|
||||
# 📚 MindSift Technische Dokumentation & Wiki
|
||||
# MindSift Technische Dokumentation
|
||||
|
||||
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.
|
||||
Referenz für Entwickler und Administratoren. Alle Angaben wurden gegen den Code im Branch `dev` geprüft (Stand Oktober 2026). Abweichungen zwischen Doku und Code melde bitte als Fehler in [flaws.md](flaws.md).
|
||||
|
||||
---
|
||||
## Inhalt
|
||||
|
||||
## 🧭 Inhaltsverzeichnis (Wiki-Navigation)
|
||||
| Dokument | Inhalt |
|
||||
|---|---|
|
||||
| [architecture.md](architecture.md) | Aufbau, Technologie-Stack, Start, Konfiguration, Build |
|
||||
| [database.md](database.md) | SQLite-Schema, Migrationen, Datenmodell |
|
||||
| [api/rest.md](api/rest.md) | Alle REST-Endpunkte |
|
||||
| [api/websocket.md](api/websocket.md) | Echtzeit über WebSocket und SSE, Ereignisse |
|
||||
| [modules/triage.md](modules/triage.md) | Schnellerfassung und Triage |
|
||||
| [modules/tasks.md](modules/tasks.md) | Aufgaben, Kanban, Alarme |
|
||||
| [modules/workspace.md](modules/workspace.md) | Outliner-Notizen, Ordner, Tags |
|
||||
| [modules/lists.md](modules/lists.md) | Geteilte Listen |
|
||||
| [sharing-and-permissions.md](sharing-and-permissions.md) | Rollen, Gruppen, Freigaben |
|
||||
| [reverse-proxy.md](reverse-proxy.md) | Nginx, Traefik, Caddy, Cloudflare |
|
||||
| [theming.md](theming.md) | Themes und Design-Variablen |
|
||||
| [flaws.md](flaws.md) | Bekannte Schwachstellen und technische Schulden |
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
## Überblick in 60 Sekunden
|
||||
|
||||
### 📑 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.
|
||||
- **Ein Go-Binary** liefert REST-API, WebSocket/SSE und das eingebettete React-Frontend (`go:embed`). Es gibt genau einen Container und eine SQLite-Datei (`/data/mindsift.db`).
|
||||
- **Datenhaltung:** vollständig in SQLite. Es gibt keine `.md`-Dateien auf der Platte; Markdown wird bei Bedarf aus den Blöcken erzeugt (`documents.markdown_cache`, Export als `.md`).
|
||||
- **Echtzeit:** ein Hub mit Räumen und Benutzer-Kanälen. Verteilt werden Ereignisse nach REST-Änderungen. Es gibt keine CRDTs, Sperren oder Cursor-Presence.
|
||||
- **Auth:** JWT (HS256, 30 Tage) mit `token_version` und Sperrliste, dazu API-Keys (`mindsift_sec_…`) für Webhooks.
|
||||
- **Freigaben:** Aufgabenlisten und geteilte Listen mit Rolle Bearbeiter oder Leser, Notizen und Ordner nur lesend.
|
||||
|
||||
---
|
||||
## Entwickeln
|
||||
|
||||
## 🏛️ 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
|
||||
# Backend (Go 1.23)
|
||||
go vet ./... && go test ./...
|
||||
|
||||
# 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
|
||||
# Frontend (Node 22)
|
||||
cd frontend && npm ci && npx tsc --noEmit && npm run build
|
||||
```
|
||||
|
||||
### 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 .
|
||||
```
|
||||
Das Frontend wird für das Binary nach `cmd/server/dist` gebaut (siehe `Dockerfile`). Die CI läuft unter `.gitea/workflows/build-and-publish.yaml`.
|
||||
Reference in new issue
Block a user