docs(code): document websocket flow

app/websocket/chat.py

@@ -9,10 +9,12 @@ router = APIRouter()
 
 
 def now_iso() -> str:
+    """Return an ISO timestamp so browsers can format message time locally."""
     return datetime.now(timezone.utc).isoformat()
 
 
 def event(event_type: str, room_id: str, client_id: str, content: str):
+    """Create the shared JSON shape sent from the server to the browser."""
     return {
         "type": event_type,
         "room_id": room_id,
@@ -23,17 +25,21 @@ def event(event_type: str, room_id: str, client_id: str, content: str):
 
 
 def clean_value(value: str, fallback: str) -> str:
+    """Use a default value when a route parameter is empty after trimming."""
     value = value.strip()
     return value if value else fallback
 
 
 @router.websocket("/ws/{room_id}/{client_id}")
 async def websocket_endpoint(websocket: WebSocket, room_id: str, client_id: str):
+    """Handle one browser's full WebSocket lifecycle."""
     room_id = clean_value(room_id, "عمومی")
     client_id = clean_value(client_id, "ناشناس")
 
+    # FastAPI accepts the HTTP Upgrade request here and switches to WebSocket.
     await manager.connect(websocket, room_id, client_id)
 
+    # Notify everyone in the room that the user joined, then refresh presence.
     await manager.broadcast_json(
         event("system", room_id, "سیستم", f"{client_id} وارد اتاق {room_id} شد."),
         room_id,
@@ -52,8 +58,10 @@ async def websocket_endpoint(websocket: WebSocket, room_id: str, client_id: str)
 
     try:
         while True:
+            # Keep the socket open and wait for the next message from this client.
             raw_data = await websocket.receive_text()
 
+            # The browser sends JSON, but plain text is accepted for manual tests.
             try:
                 data = json.loads(raw_data)
                 message = str(data.get("content", "")).strip()
@@ -69,6 +77,7 @@ async def websocket_endpoint(websocket: WebSocket, room_id: str, client_id: str)
             )
 
     except WebSocketDisconnect:
+        # When the browser tab closes or disconnects, remove it and update the room.
         manager.disconnect(websocket, room_id)
         await manager.broadcast_json(
             event("system", room_id, "سیستم", f"{client_id} از اتاق {room_id} خارج شد."),

app/websocket/manager.py

@@ -6,15 +6,22 @@ from fastapi import WebSocket
 
 @dataclass
 class ClientConnection:
+    """A connected browser inside one chat room."""
+
     websocket: WebSocket
     client_id: str
 
 
 class ConnectionManager:
+    """Keeps all active WebSocket connections grouped by room name."""
+
     def __init__(self):
+        # Example:
+        # {"عمومی": [ClientConnection(...), ClientConnection(...)]}
         self.active_connections: dict[str, list[ClientConnection]] = {}
 
     async def connect(self, websocket: WebSocket, room_id: str, client_id: str):
+        """Accept the WebSocket handshake and remember this user in the room."""
         await websocket.accept()
         self.active_connections.setdefault(room_id, [])
         self.active_connections[room_id].append(
@@ -22,6 +29,7 @@ class ConnectionManager:
         )
 
     def disconnect(self, websocket: WebSocket, room_id: str):
+        """Remove a socket from a room and delete the room when it becomes empty."""
         if room_id not in self.active_connections:
             return
 
@@ -38,11 +46,13 @@ class ConnectionManager:
         await websocket.send_json(payload)
 
     async def broadcast_json(self, payload: dict[str, Any], room_id: str):
+        """Send one JSON message to every connected client in the selected room."""
         if room_id not in self.active_connections:
             return
 
         dead_connections: list[WebSocket] = []
 
+        # Iterate over a copy so disconnected clients can be removed safely later.
         for connection in list(self.active_connections[room_id]):
             try:
                 await connection.websocket.send_json(payload)
@@ -53,12 +63,14 @@ class ConnectionManager:
             self.disconnect(websocket, room_id)
 
     def room_users(self, room_id: str) -> list[str]:
+        """Return display names of users currently connected to a room."""
         return [
             connection.client_id
             for connection in self.active_connections.get(room_id, [])
         ]
 
     def rooms_overview(self) -> dict[str, Any]:
+        """Build a small debug-friendly snapshot of all active rooms."""
         return {
             "rooms": [
                 {