Initial scaffold: FastAPI backend + Vue 3 frontend + Docker setup

Backend: config/db/security/logging core, SQLAlchemy models (Server,
Credential, UpdateJob, UpdateLog, AuditLog, User), services (winrm, ssh,
cau, audit, job_runner), REST API (auth, servers, updates, audit),
Socket.io WebSocket layer.
Frontend: Vue 3 + TS + Pinia + Tailwind, Views (Dashboard, Servers,
Updates, Audit, Login), axios + socket.io-client, nginx prod config.

backend/app/websocket/__init__.py

@@ -0,0 +1,6 @@
+"""WebSocket layer: Socket.io server, connection manager, event handlers."""
+
+from app.websocket.handlers import sio
+from app.websocket.manager import WSManager, ws_manager
+
+__all__ = ["WSManager", "sio", "ws_manager"]

backend/app/websocket/handlers.py

@@ -0,0 +1,103 @@
+"""Socket.io server instance and event handlers.
+
+Events (see AGENTS.md):
+  Server -> Client: job:start, job:log, job:progress, job:complete
+  Client -> Server: job:subscribe, job:unsubscribe, job:cancel
+"""
+
+from typing import Any
+
+import socketio
+
+from app.core.config import get_settings
+from app.core.logging import get_logger
+from app.websocket.manager import ws_manager
+
+settings = get_settings()
+logger = get_logger(__name__)
+
+sio = socketio.AsyncServer(
+    async_mode="asgi",
+    cors_allowed_origins=settings.cors_origin_list or "*",
+    # Redis manager for multi-worker pub/sub; set in main.py when Redis is up
+)
+
+
+@sio.event
+async def connect(sid: str, environ: dict, auth: dict | None) -> None:  # noqa: ARG001
+    # TODO: validate JWT from auth payload before accepting
+    ws_manager.register(sid)
+
+
+@sio.event
+async def disconnect(sid: str) -> None:
+    ws_manager.unregister(sid)
+
+
+@sio.event
+async def subscribe_job(sid: str, data: dict[str, Any]) -> dict[str, Any]:
+    """Client subscribes to a job's live log room."""
+    job_id = int(data.get("job_id", 0))
+    room = ws_manager.subscribe(sid, job_id)
+    await sio.enter_room(sid, room)
+    logger.info("ws.subscribed", sid=sid, room=room)
+    return {"ok": True, "room": room}
+
+
+@sio.event
+async def unsubscribe_job(sid: str, data: dict[str, Any]) -> dict[str, Any]:
+    job_id = int(data.get("job_id", 0))
+    room = ws_manager.unsubscribe(sid, job_id)
+    await sio.leave_room(sid, room)
+    return {"ok": True}
+
+
+@sio.event
+async def cancel_job(sid: str, data: dict[str, Any]) -> dict[str, Any]:
+    """Client requests job cancellation."""
+    from app.services.job_runner import job_runner
+
+    job_id = int(data.get("job_id", 0))
+    cancelled = await job_runner.cancel(job_id)
+    return {"ok": cancelled}
+
+
+# ---------------------------------------------------------------------------
+# Emit helpers used by services / job runner
+# ---------------------------------------------------------------------------
+
+
+async def emit_job_start(job_id: int, server_id: int, job_type: str) -> None:
+    await sio.emit(
+        "job:start",
+        {"job_id": job_id, "server_id": server_id, "type": job_type},
+        room=ws_manager.room_for(job_id),
+    )
+
+
+async def emit_job_log(job_id: int, line: str, level: str = "info") -> None:
+    from datetime import UTC, datetime
+
+    await sio.emit(
+        "job:log",
+        {"job_id": job_id, "line": line, "level": level, "timestamp": datetime.now(UTC).isoformat()},
+        room=ws_manager.room_for(job_id),
+    )
+
+
+async def emit_job_progress(
+    job_id: int, percent: int, phase: str, node: str | None = None
+) -> None:
+    await sio.emit(
+        "job:progress",
+        {"job_id": job_id, "percent": percent, "phase": phase, "node": node},
+        room=ws_manager.room_for(job_id),
+    )
+
+
+async def emit_job_complete(job_id: int, status: str, duration: float | None) -> None:
+    await sio.emit(
+        "job:complete",
+        {"job_id": job_id, "status": status, "duration": duration},
+        room=ws_manager.room_for(job_id),
+    )

backend/app/websocket/manager.py

@@ -0,0 +1,43 @@
+"""Connection manager for Socket.io rooms (one room per update job)."""
+
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class WSManager:
+    """Tracks active Socket.io sessions and job-room subscriptions."""
+
+    def __init__(self) -> None:
+        # sid -> set of job rooms the client subscribed to
+        self._subscriptions: dict[str, set[str]] = {}
+
+    def register(self, sid: str) -> None:
+        self._subscriptions.setdefault(sid, set())
+        logger.info("ws.client_connected", sid=sid)
+
+    def unregister(self, sid: str) -> None:
+        self._subscriptions.pop(sid, None)
+        logger.info("ws.client_disconnected", sid=sid)
+
+    def subscribe(self, sid: str, job_id: int) -> str:
+        room = self.room_for(job_id)
+        self._subscriptions.setdefault(sid, set()).add(room)
+        return room
+
+    def unsubscribe(self, sid: str, job_id: int) -> str:
+        room = self.room_for(job_id)
+        if sid in self._subscriptions:
+            self._subscriptions[sid].discard(room)
+        return room
+
+    @staticmethod
+    def room_for(job_id: int) -> str:
+        return f"job:{job_id}"
+
+    @property
+    def client_count(self) -> int:
+        return len(self._subscriptions)
+
+
+ws_manager = WSManager()