Architecture review: 8 improvements for production-readiness

[dimakis]

Context

Full architectural review of Mitzo identified 8 areas for improvement. None are urgent for personal use — they matter at scale or if others start using it.

Improvements

1. Break up chat.ts (815 lines)

The orchestration hub handles too many concerns: session start, follow-ups, interrupts, listing/restoring, prompt assembly, image staging, worktree resolution, and legacy JSONL reconstruction.

Extract:

• session-lifecycle.ts — start/send/interrupt/stop
• image-staging.ts — base64 decode + file write
• message-replay.ts — reconstructMessages + replayEventsToMessages

2. Tool tier agent/auto collapse

shouldAutoAllow returns true for elevated tools (Bash, Shell) in agent mode because the SDK's canUseTool stream breaks on permission requests. This means agent mode gives the same tool access as auto — the three-mode distinction collapses to two. If/when the SDK fixes this upstream, revisit.

3. EventStore singleton initialization

initEventStore() runs at module evaluation time in chat.ts, creating the SQLite DB and running migrations on import. Makes testing harder and import order fragile. Consider lazy initialization or dependency injection via Express app context.

4. No WebSocket rate limiting

REST API has express-rate-limit on login, but /ws/chat has no throttling. A reconnect loop bug could flood the server with start messages, each spawning an SDK query. The sendOrBuffer path is also unbounded — fast SDK stream + slow client = memory growth.

5. Image staging pollutes repo tree

stageImages writes decoded images to .mitzo-images/ inside the working directory, creating untracked files in the user's repo. No cleanup mechanism. Use a /tmp-based staging directory with TTL cleanup instead.

6. Global CSS at 43KB, no scoping

global.css contains all styles for all components. Every style change touches one file, no component scoping. Consider CSS modules or Tailwind for component-scoped styles with zero runtime cost.

7. WS pool never shrinks (frontend)

ws-pool.ts accumulates entries for every session visited. wsRemoveIfIdle exists but is only called explicitly. Add a proactive GC mechanism (e.g., idle timeout sweep).

8. Symlink bypass on file write endpoint

PUT /api/files/write checks isAllowedPath but doesn't resolve symlinks. A symlink inside the repo pointing outside would pass the path check. Low risk in single-user Tailscale context, but worth hardening.

Priority suggestion

If tackling incrementally: #1 → #4 → #2 → #5 — structural clarity, then safety, then correctness, then cleanup.

---

Source: external architectural review, April 2025