# Performance Architecture

## Session Management Models

VibeTunnel supports two distinct session management approaches, each with different performance characteristics:

### 1. Server-Managed Sessions (API-initiated)

Sessions created via `POST /api/sessions` are spawned directly within the server's Node.js process. These sessions benefit from:

- **Direct PTY communication**: Input and resize commands bypass the command pipe system
- **Reduced latency**: No inter-process communication overhead for terminal interactions
- **Immediate responsiveness**: Direct memory access to PTY stdout/stdin

### 2. External Sessions (vt-initiated)

Sessions started via the `vt` command run in a separate Node.js process with:

- **File-based communication**: PTY stdout is written to disk files
- **Command pipe interface**: Resize and input commands are passed through IPC
- **Additional latency**: File I/O and IPC overhead for all terminal operations

## Server Architecture

### Session Discovery and Management

The server performs two primary management tasks:

1. **External Session Monitoring**
   - Watches control directory for new external sessions
   - Automatically registers discovered sessions with the terminal manager
   - Maintains in-memory buffer cache (cols × rows) for text/buffer API endpoints

2. **Client Connection Handling**
   - WebSocket connections trigger file watchers on session stdout files
   - File watchers stream new output to connected clients in real-time
   - Multiple clients can connect to the same session simultaneously

### Memory Management

- **Buffer caching**: Last visible scrollbuffer (terminal dimensions) kept in memory
- **Efficient retrieval**: Text and buffer API endpoints serve from memory cache
- **File streaming**: WebSocket clients receive updates via file watchers

## Known Performance Issues

### Session Creation Blocking

**Symptom**: All sessions freeze temporarily when creating a new session

**Cause**: Synchronous operations during session creation
- Session creation endpoint waits for process spawn completion
- PTY initialization must complete before returning
- Any synchronous operation blocks the entire Node.js event loop

**Impact**: All active sessions become unresponsive during new session initialization

### Potential Solutions

1. **Async session creation**: Move blocking operations to worker threads
2. **Pre-spawn PTY pool**: Maintain ready PTYs to reduce creation time
3. **Event loop monitoring**: Identify and eliminate synchronous operations
4. **Progressive initialization**: Return session ID immediately, initialize asynchronously

## Performance Optimization Strategies

### For Server-Managed Sessions
- Minimize synchronous operations in session creation
- Use Node.js worker threads for CPU-intensive tasks
- Implement connection pooling for database operations

### For External Sessions
- Consider memory-mapped files for stdout communication
- Implement file change batching to reduce watcher overhead
- Use efficient file formats (binary vs text) where appropriate

### General Optimizations
- Profile event loop blocking with tools like `clinic.js`
- Implement request queuing for session creation
- Add performance metrics and monitoring
- Consider horizontal scaling with session affinity