Architecture Refactor — Implementation Plan¶

Created: 2026-03-04 Companion to: refactor.md (Nova's brief)

Actionable extraction plan for splitting hub.py (1,819 lines) and hub.html (5,607 lines) into focused modules. Each phase is independently deployable.

Safety & Testing Strategy¶

1. One module at a time. Extract, test, commit. Never refactor two modules in parallel.
2. Python: FastAPI routers. Move routes into a router, import the router in hub.py. Import errors surface immediately on startup — no silent breakage.
3. JS: Use the working git tag as safety net. Diff against it if anything breaks.
4. Incremental extraction only. No logic changes — just moving functions between files. Logic improvements come after the refactor.
5. Test checklist after each extraction:
6. Hub starts without errors (python -m server.hub)
7. Browser loads without console errors
8. Voice send/receive works (record → transcribe → TTS playback)
9. Sidebar updates (state dots, status text, project labels)
10. Messages appear in chat (user, agent, system, threaded replies)
11. Thin shells. After refactor, hub.py and hub.html become entry points that import everything. Easy to inline back if needed.
12. No logic changes during refactor. Just file reorganization. Logic improvements are a separate effort.

Phase 1: Extract ws.js — WebSocket Connection¶

Goal: Move the WebSocket connection, reconnection, and message dispatch out of hub.html.

What moves to static/js/ws.js¶

Exports from ws.js¶

export { connect, ws, sendWS, onMessage };

Imports into ws.js¶

Needs access to: sessions, activeSessionId, setConnected, setStatus, addMessage, renderSidebar, showThinking, hideThinking, updateTransportBar, switchTab, addSession, removeSession.

These come from other modules (sidebar.js, chat.js, audio.js) via imports, or from a shared state.js module (see Phase 2).

Shared state module: static/js/state.js¶

Extract global state that multiple modules read/write:

state.js exports mutable references. All modules import from it.

Phase 2: Extract audio.js — Recording, Playback, VAD¶

Goal: Move all audio I/O (mic, TTS playback, VAD, transport controls) into one module.

What moves to static/js/audio.js¶

Exports from audio.js¶

export {
  startRecording, stopRecording, cancelRecording, sendAudio,
  playMessageTTS, stopActiveAudio, interruptPlayback,
  updateTransportBar, transportPause, transportNext, transportPrev,
  startWaveform, stopWaveform, updateMicUI, getMicStream,
  showThinking, hideThinking, updateThinkingLabel,
  startPlaybackVAD, stopPlaybackVAD, startThinkingVAD, stopThinkingVAD,
  cueListening, cueProcessing, cueSessionReady,
  pttStart, pttEnd,
};

Phase 3: Extract sidebar.js — Agent Cards & State Machine¶

Goal: Move sidebar rendering and introduce the state machine for agent status.

What moves to static/js/sidebar.js¶

State machine (new logic — Phase 3 only exception to "no logic changes")¶

Replace sidebarState string + scattered boolean checks with a formal state machine:

// static/js/sidebar.js
const AgentState = {
  IDLE: 'idle',
  LISTENING: 'listening',
  PROCESSING: 'processing',
  SPEAKING: 'speaking',
  WAITING: 'waiting',    // in clawmux wait
  COMPACTING: 'compacting',
  SPAWNING: 'spawning',
  OFFLINE: 'offline',
};

const TRANSITIONS = {
  idle:       ['listening', 'processing', 'waiting', 'compacting', 'offline'],
  listening:  ['processing', 'idle', 'offline'],
  processing: ['speaking', 'idle', 'waiting', 'compacting', 'offline'],
  speaking:   ['idle', 'listening', 'processing', 'offline'],
  waiting:    ['processing', 'idle', 'offline'],
  compacting: ['idle', 'processing', 'offline'],
  spawning:   ['idle', 'offline'],
  offline:    ['idle', 'spawning'],
};

Note: The state machine is the one exception to "no logic changes" — it replaces the existing sidebar state derivation with an equivalent but explicit model. The transition table must match all existing setSessionSidebarState() call sites exactly.

Phase 4: Extract chat.js — Message Rendering¶

Goal: Move chat message creation, markdown rendering, and message list management.

What moves to static/js/chat.js¶

Exports from chat.js¶

export {
  addMessage, renderChat, createMsgEl, chatScrollToBottom,
  sendTextMessage, cycleInputMode, applyInputMode,
};

Phase 5: Split hub.py into Python Modules¶

Goal: Break the 1,819-line server into focused modules using FastAPI routers.

Module: server/routes.py — REST API Endpoints¶

Total: ~500 lines → routes.py

Module: server/voice.py — TTS/STT Pipeline¶

Total: ~250 lines → voice.py

Module: server/websocket.py — WebSocket Handlers¶

Total: ~300 lines → websocket.py

Note on circular dependencies: send_to_browser(), _flush_browser_queue(), browser_ws, and browser_queue stay in hub.py as shared infrastructure. Both websocket.py and messaging.py import them from hub — this avoids a circular dependency where messaging needs to push browser notifications and websocket handlers need to call messaging functions.

Module: server/messaging.py — Send, Inbox, Hooks¶

Total: ~450 lines → messaging.py

What stays in hub.py (~310 lines)¶

Plus: FastAPI app creation, middleware, router imports, and module wiring.

Integration pattern¶

# server/hub.py (after refactor)
from fastapi import FastAPI
from server.routes import router as routes_router
from server.messaging import router as messaging_router
from server.voice import router as voice_router
from server.websocket import register_ws_handlers

app = FastAPI(lifespan=lifespan)
app.include_router(routes_router)
app.include_router(messaging_router)
app.include_router(voice_router)
register_ws_handlers(app)  # WS endpoints need app directly

Shared state (sessions, browser_ws, browser_queue, message_broker) lives in hub.py and is imported by submodules.

Phase 6: Cleanup¶

After all extractions are verified:

1. Remove legacy code — Delete deprecated CLI handlers, unused converse references, dead imports
2. Update imports — Ensure no circular dependencies between Python modules
3. Cache busting — Add version query params to JS module imports in hub.html: <script type="module" src="js/ws.js?v=0.7.0">
4. hub.html becomes a shell — HTML structure, CSS (lines 8–1184), <script type="module"> imports, and DOM init (~100 lines of JS)

Execution Order¶

Total: ~3,150 lines moved out of the two monoliths.

After refactor: - hub.html: ~1,300 lines (HTML + CSS shell, ~100 lines init JS) - hub.py: ~270 lines (app wiring, lifecycle, background tasks) - 4 JS modules: ~1,600 lines total - 4 Python modules: ~1,550 lines total