Architecture

The Elm Architecture (TEA) #

All state lives in a single App model. Events become messages, update() applies them, view() renders the result.

Event → Message → update(model, msg) → view(model) → Frame

TEA makes state transitions explicit and testable. Every input has a traceable path from event to screen change. There's no hidden state scattered across components.

Event loop

tokio::main → init backends (BackendRegistry)
  → open SQLite DB
  → init terminal
  → spawn/restore sessions
  → loop {
    draw frame → poll crossterm events (10ms)
    → convert to AppMessage
    → app.update()
    → app.tick()
  }
  → app.shutdown() (detach sessions)
  → restore terminal

Module Structure #

Dependencies flow strictly one-directionally. Enforced by tests/architecture_rules.rs .

session  ← pure data types, no project-local imports
project  ← imports session only
agent    ← imports session only (NEVER ui, git, or project)
ui       ← imports session and project only (NEVER agent or git)
mcp      ← imports storage, session, project, sync, paths only
app      ← coordinator, imports all modules

Module responsibilities

Session Pipeline #

A SessionBackend trait abstracts session lifecycle. The default is LocalTmuxBackend ( tmux -L thurbox ). vt100::Parser interprets escape sequences, tui_term::PseudoTerminal renders into ratatui.

Backend trait methods

• check_available — verify backend prerequisites
• ensure_ready — initialize backend resources
• spawn() — returns (backend_id, output_reader, input_writer)
• adopt() — reconnect to existing session, returns initial screen content
• discover() — list existing sessions for restore-on-startup
• resize() — update terminal dimensions
• detach() — stop streaming without killing session
• kill() — permanently destroy session

tmux details

Control mode ( -C ) supports multiple concurrent client connections. Output arrives as %output notifications (octal-encoded), input is sent via send-keys -H (hex-encoded). Configuration on init includes remain-on-exit on , extended-keys on , and flow control via pause-after .

Multi-Backend Architecture #

Sessions select their backend at creation time via a BackendRegistry . Each session stores its backend_type in the database.

Async Runtime #

The app runs on tokio's multi-threaded runtime. PTY read loops run inside spawn_blocking (blocking I/O in a threadpool), while PTY write and event handling run in tokio::spawn (async).

Persistence #

All state is stored in SQLite at ~/.local/share/thurbox/thurbox.db . Multiple instances synchronize via PRAGMA data_version polling (250ms). SQLite WAL mode handles concurrent access.

Multi-instance sync

• Database : Atomic transactions, no race conditions
• Session I/O : Each instance independently connects to tmux control mode. Tmux broadcasts output to all clients.
• Input : Commands serialized by tmux (same as tmux attach with multiple clients)

Core Principles #

Non-negotiable rules that define what Thurbox must always be. Each has an automated enforcement mechanism.

Key technical details

• MSRV: 1.75, Edition 2021
• Async runtime: tokio (multi-threaded)
• Terminal state: vt100::Parser + tui_term::PseudoTerminal
• Logging: file-based at ~/.local/share/thurbox/thurbox.log
• Panic hook restores terminal before printing
• Requires tmux >= 3.2