docs(code): document websocket flow

app/main.py

@@ -12,10 +12,11 @@ STATIC_DIR = BASE_DIR / "static"
 
 app = FastAPI(title="Simple WebSocket Chatroom")
 
-# WebSocket route: ws://localhost:8000/ws/{room_id}/{client_id}
+# Registers the WebSocket endpoint:
+# ws://localhost:8000/ws/{room_id}/{client_id}
 app.include_router(chat_router)
 
-# Frontend files
+# Serves CSS, JavaScript, font files, and the main HTML page from app/static.
 app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
 
 
@@ -27,7 +28,7 @@ async def home():
 
 @app.get("/api/rooms")
 async def rooms():
-    """Small helper endpoint for the GUI/debugging."""
+    """Return active rooms and users for simple debugging during the demo."""
     return manager.rooms_overview()
 
 

app/static/app.js

@@ -16,6 +16,7 @@ let socket = null;
 let currentUser = '';
 let currentRoom = '';
 
+// Persist the last used identity locally so refreshing the page is convenient.
 usernameInput.value = localStorage.getItem('chat_username') || '';
 roomInput.value = localStorage.getItem('chat_room') || 'عمومی';
 
@@ -48,6 +49,8 @@ function formatTime(timestamp) {
   if (!timestamp) return '';
   const date = new Date(timestamp);
   if (Number.isNaN(date.getTime())) return '';
+
+  // The server stores UTC timestamps; the browser formats them for the user.
   return date.toLocaleTimeString('fa-IR', { hour: '2-digit', minute: '2-digit' });
 }
 
@@ -108,6 +111,7 @@ function connect() {
   const wsProtocol = window.location.protocol === 'https:' ? 'wss' : 'ws';
   const wsUrl = `${wsProtocol}://${window.location.host}/ws/${encodeURIComponent(currentRoom)}/${encodeURIComponent(currentUser)}`;
 
+  // Opening this object starts the HTTP Upgrade handshake automatically.
   socket = new WebSocket(wsUrl);
 
   socket.addEventListener('open', () => {
@@ -120,6 +124,7 @@ function connect() {
   socket.addEventListener('message', (event) => {
     const payload = JSON.parse(event.data);
 
+    // Presence messages update the sidebar; chat/system messages go to the feed.
     if (payload.type === 'presence') {
       updateUsers(payload.users || []);
       return;
@@ -159,6 +164,7 @@ messageForm.addEventListener('submit', (event) => {
   const content = messageInput.value.trim();
   if (!content || !socket || socket.readyState !== WebSocket.OPEN) return;
 
+  // The server accepts JSON messages and broadcasts the content to the room.
   socket.send(JSON.stringify({ content }));
   messageInput.value = '';
   messageInput.focus();

app/static/style.css

@@ -29,6 +29,7 @@ body {
   color: var(--text);
   background: var(--bg);
   direction: rtl;
+  /* The app shell owns scrolling so the page does not exceed the viewport. */
   overflow: hidden;
 }
 
@@ -98,6 +99,7 @@ h1 {
 }
 
 .layout {
+  /* Allows the chat and users panels to shrink and scroll inside the viewport. */
   min-height: 0;
   flex: 1;
   display: grid;
@@ -216,6 +218,7 @@ ul {
 
 #usersList {
   min-height: 0;
+  /* Long user lists scroll here instead of making the page taller. */
   overflow-y: auto;
 }
 
@@ -252,6 +255,7 @@ li {
   min-height: 0;
   flex: 1;
   padding: 18px;
+  /* Chat history scrolls inside the chat panel. */
   overflow-y: auto;
   display: flex;
   flex-direction: column;

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": [
                 {