MindSift/BRAIN.md

🧠 BRAIN.md — MindSift Internal Dev Cheat Sheet

Zweck: Rein internes, ungeschöntes Nachschlagewerk für uns Entwickler. Keine Marketing-Texte, nur knallharte Fakten, Farbwerte, State-Machines, Namenskonventionen und Quick-Commands.

---

🎨 1. Design-Tokens & Template-Aesthetic (Copy & Paste)

Farbpalette (Deep Dark Theme & Squircles)

/* Backgrounds (Canvas & Surfaces) */
--bg-canvas:     #16171a;  /* Deep Charcoal Canvas */
--bg-surface:    #222428;  /* Card & Capsule Surface */
--bg-elevated:   #282a2f;  /* Elevated Container / Hover */
--bg-field:      #1a1b1e;  /* Input Field Fill */

/* Borders & Dividers */
--border-subtle: rgba(255, 255, 255, 0.08); /* 1px Hairline Kante */
--border-focus:  rgba(29, 140, 248, 0.50);  /* Electric Blue Hairline */

/* Akzente & Status */
--color-primary: #1d8cf8;  /* Electric Blue Primary */
--color-on-pri:  #ffffff;  /* Text on Primary */
--color-success: #22c55e;  /* Vivid Green (Kept / Check / Done) */
--color-danger:  #ef4444;  /* Vibrant Red (Discard / Delete) */
--color-warning: #f97316;  /* Vivid Orange (High Priority) */
--color-purple:  #a855f7;  /* Accent Purple */

/* Typografie */
--text-primary:   #ffffff;  /* High Emphasis */
--text-secondary: #d1d5db;  /* Medium Emphasis */
--text-muted:     #9ca3af;  /* Low Emphasis / Subtle */

UI-Regeln & Radien

• Keine grellen Farbverläufe: Niemals Blau-zu-Lila-Gradienten wie billige AI-Templates. Strikte neutrale Anthrazit-Flächen mit satten Einzelfarben (#1d8cf8, #22c55e, #f97316).
• Squircles für Icons: w-10 h-10 oder w-9 h-9 mit rounded-xl in soliden Farben.
• Pill-Buttons: rounded-full (border-radius: 9999px) mit reinweißem Text auf #1d8cf8.
• Karten: rounded-2xl (16px) oder rounded-3xl (24px), bg-[#222428], feine Hairline-Border 1px solid rgba(255, 255, 255, 0.08).
• Fokus/Active Outline: border border-[#22c55e]/70 mit dezentem Glow für aktive Elemente.
• Floating Bottom Dock: Feste Daumenleiste mit zentriertem runden + Button in #1d8cf8.
• Gesten-Physik (Framer Motion):
  • Swipe-Schwellenwert: dragConstraints={{ left: -150, right: 150 }}
  • Spring-Config: { type: "spring", stiffness: 350, damping: 25 }
  • Swipe-Winkel-Rotation: rotate = x * 0.1

---

⚙️ 2. State-Machine: Gedanken-Lifecycle

           [ INSTANT CAPTURE ]
                    │
                    ▼
             status: 'inbox'
                    │
        ┌───────────┴───────────┐
        │ (Swipe Left)          │ (Swipe Right)
        ▼                       ▼
 status: 'discarded'      status: 'kept'
 (Soft Delete)                  │
                        ┌───────┴───────┐
                        │ (Convert)     │ (Direct Task)
                        ▼               ▼
           status: 'converted'     due_date != null
           ├── target: 'task'
           ├── target: 'document'
           └── target: 'list_item'

Gültige Status-Enums

• inbox – Frisch eingekippt, wartet auf Triage.
• discarded – Nach links gewischt (bleibt für 30 Tage im Papierkorb, dann Hard Delete).
• kept – Nach rechts gewischt, bleibt als To-Do oder Gedanke archiviert.
• converted – In vollwertiges Dokument, Aufgabe oder Listen-Item transformiert.

---

📡 3. WebSocket Realtime Protocol (Family Lists)

Verbindungs-URL: wss://<host>/api/v1/ws/spaces/:spaceId

Nachrichten-Format (JSON)

interface WSMessage<T = unknown> {
  event: 'ITEM_CREATED' | 'ITEM_UPDATED' | 'ITEM_TOGGLED' | 'ITEM_DELETED' | 'USER_PRESENCE';
  space_id: string;
  list_id: string;
  payload: T;
  timestamp: string; // ISO 8601
}

Schnelle Event-Referenz

• ITEM_TOGGLED: Wenn jemand die Hafermilch abhakt: { "item_id": "itm_123", "is_completed": true, "completed_by": "usr_sandro" }
• Optimistic UI: Frontend schlägt das Item sofort lokal durch und rollt nur bei WebSocket-Fehler zurück.

---

🗂️ 4. Ordnerstruktur & Code-Konventionen

mindsift/
├── cmd/
│   └── server/             # Go Main Entrypoint (bindet embed.FS ein)
├── internal/
│   ├── api/                # HTTP Chi Handler, Routing & Middleware
│   ├── domain/             # Entities, Interfaces & Domain Logic
│   ├── storage/            # SQLite / Postgres Adapter (sqlc generiert)
│   ├── ws/                 # WebSocket Hub & Raumverwaltung
│   └── webhook/            # Smarthome Ingestion Logic
├── migrations/             # Reine .sql Migrationsdateien
├── frontend/
│   ├── src/
│   │   ├── components/     # UI Primitives (Button, Pill, Input, Modal)
│   │   ├── features/
│   │   │   ├── capture/    # Instant-Input & Voice Recording
│   │   │   ├── triage/     # Framer Motion Swipe Deck
│   │   │   ├── workspace/  # Tiptap Block Editor
│   │   │   └── lists/      # Realtime Shopping / Todo Lists
│   │   ├── lib/            # WS Client, API Client, Sound/Haptics
│   │   └── index.css       # Tailwind v4 & Design-Tokens / CSS Variablen
├── .gitea/workflows/       # Gitea Actions CI/CD
├── Dockerfile              # Multi-Stage Build (< 35 MB)
├── docker-compose.yml
├── README.md               # Öffentliche Doku & Vision
└── BRAIN.md                # Dieses Dokument (Dev Cheat Sheet)

Namens- & ID-Konventionen

• Entity IDs: Präfix-basierte Strings für Lesbarkeit beim Debuggen:
  • usr_ = User (usr_9k2m1a)
  • th_ = Thought (th_4x8z19)
  • doc_ = Document (doc_81na72)
  • lst_ = List (lst_33fa09)
  • itm_ = List Item (itm_77bb41)
• Datenbank: snake_case (z. B. is_completed, due_date)
• JSON API: camelCase (z. B. isCompleted, dueDate)
• Timestamps: Immer UTC ISO-8601 (2026-10-24T14:20:00Z)

---

⌨️ 5. Power-User Tastatur-Shortcuts (Desktop)

Taste	Kontext	Aktion
C oder /	Überall	Fokus sofort auf das Capture-Eingabefeld
H oder ←	Triage	Karte nach links wischen (Verwerfen)
L oder →	Triage	Karte nach rechts wischen (Behalten)
T	Triage	Sofort in Aufgabe mit Fälligkeitsdatum verwandeln
D	Triage	In Workspace-Dokument umwandeln
Esc	Modal/Capture	Abbrechen / Eingabe leeren

---

⚡ 6. Cheat Sheet: Lokale Entwickler-Befehle

# 1. Frontend Dev Server (Hot Reload)
cd frontend && npm run dev

# 2. Go Backend starten (Hot Reload via air oder go run)
go run ./cmd/server

# 3. Datenbank-Migrationen lokal ausführen
go run ./cmd/migrate -direction=up

# 4. Lokalen Multi-Stage Docker-Build testen
docker build -t mindsift:dev .
docker run -p 8080:8080 -v $(pwd)/dev-data:/data -e JWT_SECRET="dev-secret-12345" mindsift:dev

# 5. SQLite DB direkt per CLI inspizieren
sqlite3 ./dev-data/mindsift.db ".tables" "SELECT * FROM thoughts LIMIT 5;"

---

🚀 7. Gitea CI/CD & Docker Tagging-Strategie

• Aktiver Arbeits-Branch: dev (hier entwickeln und pushen wir immer)
• Registry: git.dsit.me/sandrodach/mindsift
• Entwickler-Image: git.dsit.me/sandrodach/mindsift:dev (wird bei jedem Push auf dev überschrieben – kein Zumüllen der Registry!)
• Gitea Secret für Registry-Login: secrets.PUSH_TOKEN
• API-Endpunkt zum Auslesen der Pipeline: https://git.dsit.me/api/v1/repos/sandrodach/MindSift/actions/tasks
• Branch- & Release-Regeln (.gitea/workflows/build-and-publish.yaml):
  • Push auf dev: Führt Linter, TypeScript-Checks (tsc --noEmit), Unit-Tests aus und überschreibt das Image :dev.
  • Push auf main: Ignoriert (löst keinen Runner aus).
  • Git-Tag / Release (z. B. v1.0, 1.1, latest): Wird manuell bei echten Releases erstellt und baut das entsprechende Release-Image.
• Cross-Compile Speedup: Dockerfile nutzt FROM --platform=$BUILDPLATFORM für Node & Go und kompiliert amd64 + arm64 nativ über GOOS=${TARGETOS} GOARCH=${TARGETARCH} ohne langsames QEMU.