vibetunnel/docs/ARCHITECTURE.md

VibeTunnel Architecture

This document describes the technical architecture and implementation details of VibeTunnel.

Architecture Overview

VibeTunnel employs a multi-layered architecture designed for flexibility, security, and ease of use:

┌─────────────────────────────────────────────────────────┐
│                   Web Browser (Client)                   │
│  ┌─────────────────────────────────────────────────┐   │
│  │  TypeScript/JavaScript Frontend                  │   │
│  │  - Asciinema Player for Terminal Rendering      │   │
│  │  - WebSocket for Real-time Updates              │   │
│  │  - Tailwind CSS for UI                          │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                            ↕ HTTPS/WebSocket
┌─────────────────────────────────────────────────────────┐
│                    HTTP Server Layer                     │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Dual Implementation:                            │   │
│  │  1. Hummingbird Server (Swift)                  │   │
│  │  2. Rust Server (tty-fwd binary)                │   │
│  │  - REST APIs for session management              │   │
│  │  - WebSocket streaming for terminal I/O         │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────┐
│                 macOS Application (Swift)                │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Core Components:                                │   │
│  │  - ServerManager: Orchestrates server lifecycle  │   │
│  │  - SessionMonitor: Tracks active sessions       │   │
│  │  - TTYForwardManager: Handles TTY forwarding    │   │
│  │  - TerminalManager: Terminal operations         │   │
│  │  - NgrokService: Optional tunnel exposure       │   │
│  └─────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────┐   │
│  │  UI Layer (SwiftUI):                            │   │
│  │  - MenuBarView: System menu bar integration     │   │
│  │  - SettingsView: Configuration interface        │   │
│  │  - ServerConsoleView: Diagnostics & logs        │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Core Components

1. Native macOS Application

The main application is built with Swift and SwiftUI, providing:

• Menu Bar Integration: Lives in the system menu bar with optional dock mode
• Server Lifecycle Management: Controls starting, stopping, and switching between server implementations
• System Integration: Launch at login, single instance enforcement, application mover
• Auto-Updates: Sparkle framework integration for seamless updates

Key files:

• VibeTunnel/VibeTunnelApp.swift: Main application entry point
• VibeTunnel/Core/Services/ServerManager.swift: Orchestrates server operations
• VibeTunnel/Core/Models/TunnelSession.swift: Core session model

2. HTTP Server Layer

VibeTunnel offers two server implementations that can be switched at runtime:

Hummingbird Server (Swift)

• Built-in Swift implementation using the Hummingbird framework
• Native integration with the macOS app
• RESTful APIs for session management
• File: VibeTunnel/Core/Services/HummingbirdServer.swift

Rust Server (tty-fwd)

• External binary written in Rust for high-performance TTY forwarding
• Spawns and manages terminal processes
• Records sessions in asciinema format
• WebSocket streaming for real-time terminal I/O
• Source: tty-fwd/ directory

Both servers expose similar APIs:

• POST /sessions: Create new terminal session
• GET /sessions: List active sessions
• GET /sessions/:id: Get session details
• POST /sessions/:id/send: Send input to terminal
• GET /sessions/:id/output: Stream terminal output
• DELETE /sessions/:id: Terminate session

3. Web Frontend

A modern web interface for terminal interaction:

• Terminal Rendering: Uses asciinema player for accurate terminal display
• Real-time Updates: WebSocket connections for live terminal output
• Responsive Design: Tailwind CSS for mobile-friendly interface
• Session Management: Create, list, and control multiple terminal sessions

Key files:

• web/: Frontend source code
• VibeTunnel/Resources/WebRoot/: Bundled static assets

Session Management Flow

1. Session Creation:

   Client → POST /sessions → Server spawns terminal process → Returns session ID
   

2. Command Execution:

   Client → POST /sessions/:id/send → Server writes to PTY → Process executes
   

3. Output Streaming:

   Process → PTY output → Server captures → WebSocket/HTTP stream → Client renders
   

4. Session Termination:

   Client → DELETE /sessions/:id → Server kills process → Cleanup resources
   

Key Features Implementation

Security & Tunneling

• Ngrok Integration: Optional secure tunnel exposure for remote access
• Keychain Storage: Secure storage of authentication tokens
• Code Signing: Full support for macOS code signing and notarization
• Basic Auth: Password protection for network access

Terminal Capabilities

• Full TTY Support: Proper handling of terminal control sequences
• Process Management: Spawn, monitor, and control terminal processes
• Session Recording: Asciinema format recording for playback
• Multiple Sessions: Concurrent terminal session support

Developer Experience

• Hot Reload: Development server with live updates
• Comprehensive Logging: Detailed logs for debugging
• Error Handling: Robust error handling throughout the stack
• Swift 6 Concurrency: Modern async/await patterns

Technology Stack

macOS Application

• Language: Swift 6.0
• UI Framework: SwiftUI
• Minimum OS: macOS 14.0 (Sonoma)
• Architecture: Universal Binary (Intel + Apple Silicon)

Dependencies

• Hummingbird: HTTP server framework
• Sparkle: Auto-update framework
• Swift Log: Structured logging
• Swift HTTP Types: Type-safe HTTP handling
• Swift NIO: Network framework

Build Tools

• Xcode: Main IDE and build system
• Swift Package Manager: Dependency management
• Cargo: Rust toolchain for tty-fwd
• npm: Frontend build tooling

Project Structure

vibetunnel/
├── VibeTunnel/              # macOS app source
│   ├── Core/                # Core business logic
│   │   ├── Services/        # Core services (servers, managers)
│   │   ├── Models/          # Data models
│   │   └── Utilities/       # Helper utilities
│   ├── Presentation/        # UI layer
│   │   ├── Views/          # SwiftUI views
│   │   └── Utilities/      # UI utilities
│   ├── Utilities/          # App-level utilities
│   └── Resources/          # Assets and bundled files
├── tty-fwd/                # Rust TTY forwarding server
├── web/                    # TypeScript/JavaScript frontend
├── scripts/                # Build and utility scripts
└── Tests/                  # Unit and integration tests

Key Design Patterns

1. Protocol-Oriented Design: ServerProtocol allows swapping server implementations
2. Actor Pattern: Swift actors for thread-safe state management
3. Dependency Injection: Services are injected for testability
4. MVVM Architecture: Clear separation of views and business logic
5. Singleton Pattern: Used for global services like ServerManager

Development Guidelines

Code Organization

• Services are organized by functionality in the Core/Services directory
• Views follow SwiftUI best practices with separate view models when needed
• Utilities are split between Core (business logic) and Presentation (UI)

Error Handling

• All network operations use Swift's async/await with proper error propagation
• User-facing errors are localized and actionable
• Detailed logging for debugging without exposing sensitive information

Testing Strategy

• Unit tests for core business logic
• Integration tests for server implementations
• UI tests for critical user flows

Performance Considerations

• Rust server for CPU-intensive terminal operations
• Efficient WebSocket streaming for real-time updates
• Lazy loading of terminal sessions in the UI

Security Model

1. Local-Only Mode: Default configuration restricts access to localhost
2. Password Protection: Optional password for network access stored in Keychain
3. Secure Tunneling: Integration with Tailscale/ngrok for remote access
4. Process Isolation: Each terminal session runs in its own process
5. No Persistent Storage: Sessions are ephemeral, recordings are opt-in

Future Architecture Considerations

• Plugin System: Allow third-party extensions
• Multi-Platform Support: Potential Linux/Windows ports
• Cloud Sync: Optional session history synchronization
• Terminal Multiplexing: tmux-like functionality
• API Extensions: Programmatic control of sessions

Acknowledgments

VibeTunnel's architecture is influenced by:

• Modern macOS app design patterns
• Unix philosophy of composable tools
• Web-based terminal emulators like ttyd and gotty
• The asciinema ecosystem for terminal recording