191 lines
8.1 KiB
Markdown
191 lines
8.1 KiB
Markdown
# 🧠 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)
|
||
```css
|
||
/* 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)
|
||
```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 & 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
|
||
|
||
```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.
|
||
|