docs: consolidate documentation into organized structure

- Move 12 markdown files from root to docs/ subdirectories
- Organize documentation by category:
  • docs/troubleshooting/ (1 file)  - Technical troubleshooting guides
  • docs/deployment/      (4 files) - Deployment and security documentation
  • docs/guides/          (3 files) - Feature-specific guides
  • docs/planning/        (4 files) - Planning and improvement proposals

Root directory cleanup:
- Reduced from 16 to 4 markdown files in root
- Only essential project files remain:
  • CLAUDE.md (AI instructions)
  • README.md (Main project readme)
  • CLEANUP_PLAN.md (Current cleanup plan)
  • SRC_STRUCTURE_IMPROVEMENTS.md (Structure improvements)

This improves:
✅ Documentation discoverability
✅ Logical organization by purpose
✅ Clean root directory
✅ Better maintainability

docs/guides/README-websocket.md

@@ -0,0 +1,118 @@
+# WebSocket Server
+
+Dieses Dokument beschreibt die Implementierung und Verwendung des WebSocket-Servers.
+
+## Übersicht
+
+Der WebSocket-Server ist als eigenständiger Prozess implementiert, der unabhängig vom HTTP-Server läuft. Dies ermöglicht langlebige Verbindungen, die mit dem PHP-FPM/Apache-Modell nicht möglich wären.
+
+## Starten des WebSocket-Servers
+
+Der WebSocket-Server kann mit folgendem Befehl gestartet werden:
+
+```bash
+php websocket.php
+```
+
+Oder, wenn die Ausführungsrechte gesetzt sind:
+
+```bash
+./websocket.php
+```
+
+Der Server läuft standardmäßig auf `0.0.0.0:8080` und kann über WebSocket-Clients erreicht werden.
+
+## Konfiguration
+
+Die Konfiguration des WebSocket-Servers erfolgt direkt in der `websocket.php`-Datei. Hier können Host und Port angepasst werden:
+
+```php
+$server->start('0.0.0.0', 8080);
+```
+
+## Implementierung von WebSocket-Controllern
+
+WebSocket-Controller werden wie normale HTTP-Controller implementiert, geben jedoch ein `WebSocketResult`-Objekt zurück. Hier ist ein Beispiel:
+
+```php
+#[Route(path: '/chat/websocket', method: Method::GET)]
+public function chatWebSocket(): WebSocketResult
+{
+    return new WebSocketResult()
+        ->onConnect(function (WebSocketConnection $connection) {
+            // Handler für neue Verbindungen
+        })
+        ->onMessage(function (WebSocketConnection $connection, string $message) {
+            // Handler für eingehende Nachrichten
+        })
+        ->onClose(function (WebSocketConnection $connection, int $code, string $reason) {
+            // Handler für geschlossene Verbindungen
+        })
+        ->onError(function (WebSocketConnection $connection, \Throwable $error) {
+            // Handler für Fehler
+        });
+}
+```
+
+## Testen mit dem ChatController
+
+Der bestehende `ChatController` kann als Beispiel für die Verwendung von WebSockets dienen. Um ihn zu testen:
+
+1. Starten Sie den WebSocket-Server:
+   ```bash
+   php websocket.php
+   ```
+
+2. Öffnen Sie eine WebSocket-Verbindung zum Server (z.B. mit JavaScript):
+   ```javascript
+   const socket = new WebSocket('ws://localhost:8080/chat/websocket');
+   
+   socket.onopen = function(e) {
+     console.log("Verbindung hergestellt");
+   };
+   
+   socket.onmessage = function(event) {
+     console.log(`Daten empfangen: ${event.data}`);
+   };
+   
+   socket.onclose = function(event) {
+     if (event.wasClean) {
+       console.log(`Verbindung geschlossen, Code=${event.code} Grund=${event.reason}`);
+     } else {
+       console.log('Verbindung unterbrochen');
+     }
+   };
+   
+   socket.onerror = function(error) {
+     console.log(`Fehler: ${error.message}`);
+   };
+   
+   // Nachricht senden
+   socket.send(JSON.stringify({
+     type: 'chat_message',
+     message: 'Hallo Welt!'
+   }));
+   ```
+
+## Architektur
+
+Der WebSocket-Server verwendet folgende Komponenten:
+
+1. **websocket.php**: Einstiegspunkt und Hauptskript
+2. **WebSocketServer**: Verarbeitet WebSocket-Verbindungen und -Nachrichten
+3. **WebSocketConnection**: Repräsentiert eine aktive WebSocket-Verbindung
+4. **WebSocketResult**: Definiert Handler für WebSocket-Ereignisse
+
+Der Server nutzt das bestehende Routing-System, um WebSocket-Anfragen an die entsprechenden Controller weiterzuleiten.
+
+## Vorteile gegenüber der HTTP-basierten Implementierung
+
+1. **Langlebige Verbindungen**: Der Server kann Verbindungen über längere Zeit offen halten
+2. **Echtzeit-Kommunikation**: Bidirektionale Kommunikation in Echtzeit
+3. **Ressourceneffizienz**: Geringerer Overhead im Vergleich zu HTTP-Polling
+4. **Skalierbarkeit**: Der WebSocket-Server kann unabhängig vom HTTP-Server skaliert werden
+
+## Bekannte Einschränkungen
+
+1. Der WebSocket-Server unterstützt derzeit keine SSL/TLS-Verschlüsselung direkt. Für sichere Verbindungen sollte ein Reverse-Proxy wie Nginx verwendet werden.
+2. Die Implementierung ist auf einfache Anwendungsfälle ausgelegt und könnte für komplexere Szenarien erweitert werden.