SSE Refactoring - File Structure
================================

/home/uroma/obsidian-web-interface/
│
├── 📘 Documentation
│   ├── SSE_REFACTOR_PLAN.md              (48KB) - Complete refactoring plan
│   ├── SSE_IMPLEMENTATION_GUIDE.md        (9.5KB) - Step-by-step implementation
│   ├── SSE_QUICK_REFERENCE.md             (8.8KB) - Developer quick reference
│   ├── SSE_ARCHITECTURE_DIAGRAMS.md       (30KB) - Visual architecture diagrams
│   ├── SSE_DELIVERABLES.md                (7KB) - This summary
│   └── SSE_FILE_TREE.txt                  (this file) - File structure
│
├── 🔧 Services (NEW)
│   ├── event-bus.js                       (5.8KB) - Event pub/sub system
│   │   ├── subscribe(eventType, sessionId, handler)
│   │   ├── emit(eventType, data)
│   │   ├── subscribeToSession(sessionId, handler)
│   │   └── getMetrics()
│   │
│   └── sse-manager.js                     (11KB) - SSE connection manager
│       ├── addConnection(sessionId, res, req)
│       ├── sendEvent(sessionId, res, data)
│       ├── broadcastToSession(sessionId, data)
│       ├── getConnectionCount(sessionId)
│       ├── getStats()
│       └── cleanup()
│
├── 🛣️ Routes (NEW)
│   ├── session-routes.js                 (13KB) - Session API endpoints
│   │   ├── POST   /api/session/:id/prompt
│   │   ├── GET    /api/session/:id/status
│   │   ├── GET    /api/session/:id/context
│   │   ├── POST   /api/session/:id/operations/preview
│   │   ├── POST   /api/session/:id/operations/execute
│   │   ├── DELETE /api/session/:id
│   │   ├── POST   /api/session/:id/duplicate
│   │   ├── POST   /api/session/:id/fork
│   │   └── POST   /api/session/:id/move
│   │
│   └── sse-routes.js                     (3.8KB) - SSE streaming endpoints
│       ├── GET /api/session/:id/events     - SSE event stream
│       ├── GET /api/session/:id/events/status - Connection status
│       ├── GET /api/sse/stats              - Global stats
│       └── GET /api/sse/test               - Test endpoint (dev)
│
├── ✅ Middleware (NEW)
│   └── validation.js                     (6.2KB) - Request validation
│       ├── validateSessionId
│       ├── validateTerminalId
│       ├── validateCommand
│       ├── validateOperations
│       ├── validateResponse
│       └── errorHandler
│
├── 💻 Client-Side (NEW)
│   └── public/js/sse-client.js           (11KB) - SSE connection manager
│       ├── new SessionEventStream(sessionId, options)
│       ├── on(event, handler)
│       ├── off(event, handler)
│       ├── disconnect()
│       └── getStatus()
│
└── 📝 Existing Files (TO MODIFY)
    ├── server.js                          - Add route registration
    └── services/claude-service.js         - Emit events instead of callbacks


Event Flow Diagram
==================

User sends command "ls -la"
        │
        ▼
┌─────────────────────────────────────────────────────────────┐
│ Client                                                       │
│  POST /api/session/session-123/prompt                        │
│  { "command": "ls -la" }                                     │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ Server: REST API                                             │
│  • validateSessionId middleware                              │
│  • validateCommand middleware                                │
│  • claudeService.sendCommand()                               │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ ClaudeService                                                │
│  • Write to Claude Code process                              │
│  • Return 202 Accepted                                       │
└────────────────────────┬────────────────────────────────────┘
                         │
                         │ (output comes later)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ Claude Code Process                                          │
│  • Execute command                                           │
│  • Generate output                                           │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ ClaudeService (callback)                                     │
│  • eventBus.emit('session-output', {                         │
│      sessionId: 'session-123',                               │
│      content: 'file1.txt\nfile2.txt'                         │
│    })                                                         │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ EventBus                                                     │
│  • Find all subscribers to 'session-output' for session-123 │
│  • Call each subscriber's handler                            │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ SSEManager (subscribed to EventBus)                         │
│  • For each SSE connection for session-123:                 │
│    res.write('event: session-output\n')                     │
│    res.write('data: {"content":"..."}\n')                   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│ Client (EventSource)                                         │
│  • Receives event                                            │
│  • Calls registered handler:                                 │
│    eventStream.on('output', (data) => {                      │
│      console.log(data.content)  // "file1.txt\nfile2.txt"    │
│    })                                                         │
└─────────────────────────────────────────────────────────────┘


Key Improvements
================

Before (WebSocket):
  ❌ Session ID in message body (ambiguous)
  ❌ Client must manage subscription state
  ❌ Multiple tabs can conflict
  ❌ Complex reconnection logic

After (SSE):
  ✅ Session ID in URL path (clear)
  ✅ Automatic subscription
  ✅ Multiple tabs work correctly
  ✅ Built-in reconnection with backoff
  ✅ Works through nginx
  ✅ Simpler client code


Migration Timeline
==================

Week 1-2:  Phase 1 - Infrastructure
  ✓ Implement EventBus, SSEManager, Routes
  ✓ Deploy to staging
  ✓ Test thoroughly
  
Week 3-5:  Phase 2 - Client Migration
  ✓ Update UI for new sessions
  ✓ Feature flag for gradual rollout
  ✓ Monitor metrics
  
Week 6-7:  Phase 3 - Deprecation
  ✓ Add deprecation warnings
  ✓ Update documentation
  
Week 8:    Phase 4 - Cleanup
  ✓ Remove WebSocket code
  ✓ Final regression test


Integration Effort
==================

server.js:              +10 lines  (register routes)
claude-service.js:      +20 lines  (emit events)
UI components:          ~30 lines each (replace WebSocket with SSE)

Total NEW code:         ~2,500 lines
Total MODIFY code:      ~100 lines
Documentation:          ~100KB


Next Actions
============

1. Read SSE_REFACTOR_PLAN.md for complete design
2. Read SSE_IMPLEMENTATION_GUIDE.md for integration steps
3. Implement Phase 1 (Infrastructure)
4. Test in staging environment
5. Monitor metrics and gather feedback
6. Proceed to Phase 2 (Client Migration)


Questions?
==========

• Full Design:           SSE_REFACTOR_PLAN.md
• How to Integrate:      SSE_IMPLEMENTATION_GUIDE.md
• Quick Reference:       SSE_QUICK_REFERENCE.md
• Visual Understanding:  SSE_ARCHITECTURE_DIAGRAMS.md
• This Summary:          SSE_DELIVERABLES.md