Michess/Brain.md

Brain.md — Michess Project Memory

Dieses Dokument ist mein aktives Gedächtnis während der Entwicklung von Michess. Ich denke hier, notiere Entscheidungen, Probleme und Fortschritt.

---

Projektziel

Michess = Lichess-inspirierte Schachplattform, self-hosted auf einer NAS, in Docker, mit Stockfish-Engine.

---

Tech Stack (Entschieden)

Schicht	Technologie	Grund
Frontend	Next.js 14 + React + Tailwind + daisyUI	Von chessu geerbt, modern, SSR-fähig
Backend	Node.js + Express + Socket.io	Von chessu geerbt, real-time-ready
Datenbank	PostgreSQL	Von chessu geerbt, solide
Auth	express-session + argon2	Bereits vorhanden, sicher
Schach-Logik	chess.js	Bereits vorhanden
Schachbrett UI	react-chessboard	Bereits vorhanden
Stockfish	stockfish npm-Paket	Einfache Integration im Backend
Container	Docker Compose	NAS-Deployment
Package Manager	pnpm Workspaces	Monorepo-Setup

---

Basis-Projekt

• Geclont von: dotnize/chessu (MIT-Lizenz)
• Warum: TypeScript, React/Next.js, Express, Socket.io, PostgreSQL, chess.js — perfekter Ausgangspunkt
• Was chessu schon hat:
  • User-Accounts (name, email, password, wins/losses/draws)
  • Session-Auth mit argon2-Passwort-Hashing
  • Real-time Multiplayer via Socket.io
  • Spiele mit PGN-Speicherung
  • Public Games Liste
  • Archiv (gespielte Partien)
  • User-Profilseite

---

Was ich bauen muss (Delta zu chessu)

1. Stockfish AI-Gegner — verschiedene Schwierigkeitsgrade (Level 1-8, ELO-basiert)
2. Admin-Panel — Nutzerverwaltung, Git-Pull-Button, Statistiken
3. Freundessystem — Freundschaftsanfragen, Freundesliste, Freunde herausfordern
4. Branding — Alles auf "Michess" umbenennen
5. Docker NAS-Deployment — docker-compose für NAS, Auto-Update-Script
6. DB-Schema Erweiterungen — admin-Flag, friends-Tabelle, friend_requests-Tabelle
7. E-Mail-basierte Registrierung — (email-Feld schon da, braucht UI-Flow: email → unique username wählen)

---

Architektur-Entscheidungen

Stockfish im Backend

• Stockfish läuft als Child-Process auf dem Server (NAS)
• Kommunikation über UCI-Protokoll
• Schwierigkeitsgrade via Skill Level (0-20) und Depth
• Pro aktiver AI-Partie: eigener Stockfish-Prozess (oder Pool)

Admin-Rolle

• role Spalte in user-Tabelle (default: 'user', admin: 'admin')
• Erster User mit email aus ADMIN_EMAIL env var wird automatisch Admin
• Admin-Middleware schützt /v1/admin/* Routen

Friends-System

• friends-Tabelle: user_id_1, user_id_2 (symmetrisch)
• friend_requests-Tabelle: from_id, to_id, status (pending/accepted/rejected)
• Nutzer suchen via Username

Git-Auto-Update (Admin-Feature)

• Admin-Route: POST /v1/admin/update
• Führt git pull im Container-Verzeichnis aus
• Triggert danach Neustart (via restart-policy des Containers)
• Update-Script wird ins Docker-Image eingebaut

Docker NAS-Setup

• docker-compose.yml mit Services: michess-app + postgres
• Watchtower oder einfaches update-script für automatische Updates
• Alle Credentials via .env-Datei

---

Aktueller Status

• Basis-Projekt geclont (chessu)
• Brain.md erstellt
• Plan.md erstellt
• Git remote auf git.mischlabs.de gesetzt
• Projekt auf "Michess" umbenannt
• DB-Schema erweitert (admin, friends, friend_requests)
• Stockfish integriert
• Admin-Panel gebaut
• Friends-System gebaut
• Docker NAS-Deployment finalisiert
• Alles committed & gepusht

---

Bekannte Probleme / Offene Fragen

• chessu's Dockerfile nutzt CMD ["start"] — muss für Michess angepasst werden (Server + Client separat oder zusammen)
• Stockfish binary muss im Docker-Image vorhanden sein (Alpine Linux: apk add stockfish oder npm-Paket)
• Admin-Git-Pull: funktioniert nur wenn Container read-write Zugriff auf sein eigenes Verzeichnis hat — besser: Host-Script via webhook triggern

---

Lessons Learned

(wird im Verlauf befüllt)

---

Nächste Schritte (immer aktuell)

1. Git remote setzen → push
2. Umbenennen chessu → Michess
3. DB-Schema erweitern
4. Stockfish backend einbauen
5. Admin-Panel UI + Backend
6. Friends-System
7. Docker finalisieren
8. Issues aus Git bearbeiten