Update

README.md

@@ -1,17 +1,77 @@
-# Klangkiste 🎶📦
+# Klangkiste
 
-Klangkiste ist eine selbstgebaute, offlinefähige Kinder-Audiobox
-(Phoniebox-Prinzip, aber vollständig eigenständig).
+Klangkiste ist eine DIY-Kinder-Audiobox mit serverseitiger Verwaltung und
+vollstaendiger Offline-Faehigkeit. Ziel ist eine robuste, kindgerechte Box:
+Tags auflegen, Inhalte starten, und Eltern verwalten alles bequem ueber eine
+einfache Web-Oberflaeche.
 
-## Ziel
-- Mehrere Boxen
-- Zentrale Verwaltung über Web-GUI (später)
-- Jede Box arbeitet offlinefähig mit lokalem Medien-Cache
+## Was die Box aktuell kann
+- NFC-Workflow (simuliert): Tags auflegen, Tags erkennen, Tag-IDs in der
+  Datenbank speichern, Tags Medienordnern zuordnen.
+- Playback-Steuerung (simuliert): Play/Pause, Next, Prev, Stop, Volume.
+- Medienverwaltung: Ordnerstruktur anzeigen, Uploads, Umbenennen, Verschieben,
+  Loeschen.
+- Box-Verwaltung: Pairing/Unpairing, Box-Status, Commands an einzelne Boxen.
+- Tag-Verwaltung: Alias, Zuordnung, Sperren pro Box, Import von lokalen Tags.
+- Offline-Logik (simuliert): Box arbeitet mit lokalem Cache, Server kann wieder
+  synchronisieren.
+- Mehrere Boxen gleichzeitig (box + box2) fuer Multi-Box-Tests.
+
+## Was geplant ist
+- Echte NFC-Hardware-Integration (Lesen/Schreiben von Tag-IDs).
+- Reale Audio-Ausgabe auf der Box, nicht nur Simulation.
+- Robuste Setup-Flows fuer WLAN, Updates und Fehlerdiagnose.
+- Feinschliff der GUI (Mobile-Flows, Accessibility, klare Nutzerfuehrung).
+- Vereinfachte Installation fuer Familien (Image/Installer).
 
 ## Status
-Phase 1a – lokale Entwicklung ohne Hardware (Mocks)
+Phase 1.x – lokale Entwicklung ohne Hardware (Mocks + API + GUI)
 
-## Tech
-- Python 3
-- Raspberry Pi Zero W / Zero 2 W (später)
-- NFC, Buttons, Audio abstrahiert über Interfaces
+## Repo-Struktur
+- `box/` – Box-Software (Python, NFC/Playback/Resume, API)
+- `box2/` – zweite Box-Instanz fuer Multi-Box-Tests
+- `gui/backend/` – Backend (Node.js + SQLite, Box-Verwaltung, Media-API)
+- `gui/frontend/` – Control-Panel (React + Vite)
+- `docs/` – Dev-Playbook, API-Vertrag, Tests
+
+## Quickstart (lokal)
+1) Alles starten:
+```
+./dev.sh
+```
+2) Setup-WebGUI (Box):
+```
+http://127.0.0.1:9000/setup
+```
+3) Backend pruefen:
+```
+curl http://127.0.0.1:5001/api/boxes
+```
+4) Frontend oeffnen:
+```
+http://127.0.0.1:5174
+```
+
+## Ports (Default)
+- Backend API: `5001`
+- Frontend GUI: `5174`
+- Box API: `8000`
+- Setup UI: `9000`
+- Box2 API (optional): `8001`
+- Box2 Setup (optional): `9001`
+
+## Entwicklungsprinzipien (Kurz)
+- Box und GUI/Backend teilen keinen Code.
+- Kommunikation nur ueber JSON-APIs.
+- Box ist Quelle der Wahrheit fuer Playback/State.
+- Server verwaltet Tags, Medien und Boxen.
+
+## Technisch (kurz)
+- Start via `./dev.sh` (startet Frontend, Backend, Box-Simulation).
+- Frontend spricht mit Backend (`/api`), Backend spricht mit Boxen (HTTP).
+- NFC/Playback sind aktuell simuliert; reale Hardware folgt.
+
+## Doku
+- `docs/README.md` – Startpunkt fuer den Dev-Playbook
+- `docs/dev-workflow.md` – Start/Stop, Ports, Logs
+- `docs/api.md` – API-Vertrag