# 🧠 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 & Gemini-Dark-Theme (Copy & Paste)

### Farbpalette (Strict Hex Values - Google Gemini Material 3 Dark)
```css
/* Backgrounds (Material 3 Dark Theme) */
--bg-canvas:     #131314;  /* Google Gemini Canvas */
--bg-surface:    #1e1f20;  /* Surface Container (Karten, Dialoge, Panels) */
--bg-elevated:   #282a2c;  /* Elevated Container / Tonal Chips / Hover */
--bg-field:      #131314;  /* Input Field Fill */

/* Borders & Dividers */
--border-subtle: rgba(255, 255, 255, 0.08); /* 1px Hairline Kante */
--border-focus:  rgba(168, 199, 250, 0.40); /* Gemini Primary Blue Hairline */

/* Akzente & Status (Material 3 Soft Pastels - KEINE grellen AI-Farbverläufe) */
--color-primary: #a8c7fa;  /* Google Gemini Primary Blue */
--color-on-pri:  #041e49;  /* Text on Primary Container */
--color-success: #a8dab5;  /* Soft Green (Check / Kept) */
--color-danger:  #f28b82;  /* Soft Coral Red (Discard / Delete) */
--color-warning: #fdd663;  /* Warm Amber */

/* Typografie */
--text-primary:   #e3e3e3;  /* High Emphasis */
--text-secondary: #c4c7c5;  /* Medium Emphasis */
--text-muted:     #8e918f;  /* 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 sanften Pastell-Akzenten.
* **Keine grellen Glow-Schatten:** Keine starken farbigen Drop-Shadows oder Neon-Glows. Feine `border: 1px solid rgba(255,255,255,0.08)` Hairlines nutzen.
* **Buttons / Pills:** `rounded-full` (`border-radius: 9999px`) für Filter, Actions und Navigation.
* **Karten:** `rounded-2xl` (`16px`) oder `rounded-3xl` (`24px`), Padding `p-5` bis `p-6`, Border `1px solid rgba(255, 255, 255, 0.08)`.
* **Input-Feld (Instant Capture):** Prompt-Box-Stil wie Google Gemini, Höhe `h-14` (56px) für mobile Daumenbedienung, Autofokus bei Mount.
* **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)
```typescript
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 & Gemini 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

```bash
# 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`](file:///home/sandro/Dokumente/git/MindSift/.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.