Monolex Architecture
Monolex is a next-generation AI-native terminal built on Tauri 2.0 with a unique rendering system called MonoTerm. ████
█████████████ ██████ ████████ ██████ ░░███ ██████ █████ █████
░░███░░███░░███ ███░░███░░███░░███ ███░░███ ░███ ███░░███░░███░███
░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███████ ░░░███░
░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███░░░ ███░███
█████░███ █████░░██████ ████ █████░░██████ █████░░██████ █████ █████
░░░░░ ░░░ ░░░░░ ░░░░░░ ░░░░ ░░░░░ ░░░░░░ ░░░░░ ░░░░░░ ░░░░░ ░░░░░
"Atomic UX for Human + AI"
The Problem We Solved
Traditional terminals have a fundamental issue: They render whatever comes in, whenever it comes.╔═══════════════════════════════════════════════════════════════════════════════╗
║ THE PROBLEM: UNCOORDINATED RENDERING ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ ║
║ Program writes: "Hello" ║
║ Screen shows: "Hel" ← (partial, program still writing) ║
║ ║
║ Program writes: "lo World" ║
║ Screen shows: "Hello Wor" ← (still incomplete!) ║
║ ║
║ Program writes: "ld!" ║
║ Screen shows: "Hello World!" ← (finally complete) ║
║ ║
║ ❌ User sees THREE screen updates for ONE logical update ║
║ ❌ Flicker, tearing, visual artifacts ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
MonoTerm Solution
MonoTerm waits for complete frames before rendering.╔═══════════════════════════════════════════════════════════════════════════════╗
║ THE SOLUTION: FRAME-COORDINATED RENDERING ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ ║
║ Program writes: [cursor hide] + "Hello World!" + [cursor show] ║
║ │ │ ║
║ │ MonoTerm detects: │ ║
║ │ "Frame boundary!" │ ║
║ ▼ ▼ ║
║ Screen shows: ──────(nothing)──────────→ "Hello World!" ║
║ ║
║ ✅ User sees ONE screen update for ONE logical update ║
║ ✅ No flicker, no tearing, atomic frames ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
Architecture Overview
╔═════════════════════════════════════════════════════════════════════════════════╗
║ MONOTERM ARCHITECTURE ║
╠═════════════════════════════════════════════════════════════════════════════════╣
║ ║
║ ┌──────────────────┐ ║
║ │ PTY Daemon │ ← Runs shell (bash, zsh, etc.) ║
║ │ (Rust) │ ║
║ └────────┬─────────┘ ║
║ │ ║
║ │ Unix Socket (raw bytes) ║
║ ▼ ║
║ ┌──────────────────┐ ║
║ │ Tauri Backend │ ← Parses and coordinates rendering ║
║ │ (Rust) │ ║
║ │ │ ║
║ │ ┌────────────┐ │ ║
║ │ │ Alacritty │ │ ← VTE Parser (from Alacritty project) ║
║ │ │ VTE Parser │ │ ║
║ │ └────────────┘ │ ║
║ │ │ ║
║ │ ┌────────────┐ │ ║
║ │ │ Frame │ │ ← Detects complete frame boundaries ║
║ │ │ Detection │ │ (BSU/ESU, cursor hide/show) ║
║ │ └────────────┘ │ ║
║ │ │ ║
║ │ ┌────────────┐ │ ║
║ │ │ Smart │ │ ← Compares with previous frame ║
║ │ │ Diff │ │ (hash-based, only send changes) ║
║ │ └────────────┘ │ ║
║ │ │ ║
║ │ ┌────────────┐ │ ║
║ │ │ Flow │ │ ← Prevents overwhelming the frontend ║
║ │ │ Control │ │ (ACK handshake) ║
║ │ └────────────┘ │ ║
║ └────────┬─────────┘ ║
║ │ ║
║ │ Tauri Event (only changed data) ║
║ ▼ ║
║ ┌──────────────────┐ ║
║ │ Frontend │ ← Direct buffer injection ║
║ │ (TypeScript) │ ║
║ │ │ ║
║ │ ┌────────────┐ │ ║
║ │ │ atomic-term│ │ ← xterm.js fork with direct buffer access ║
║ │ │ (xterm.js) │ │ ║
║ │ └────────────┘ │ ║
║ └────────┬─────────┘ ║
║ │ ║
║ │ WebGL ║
║ ▼ ║
║ ┌──────────────────┐ ║
║ │ Your Screen │ ← Final render ║
║ └──────────────────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
Key Components
1. PTY Daemon (Rust)
Runs your shell. Completely separate process.╔═════════════════════════════════════════════════════════════════╗
║ PTY DAEMON ║
╠═════════════════════════════════════════════════════════════════╣
║ ║
║ You type: ls -la ║
║ │ ║
║ ▼ ║
║ ┌─────────────┐ ║
║ │ Your Shell │ (bash, zsh, fish, etc.) ║
║ └─────────────┘ ║
║ │ ║
║ ▼ ║
║ Output: file listing with colors, formatting ║
║ ║
║ Benefit: Survives main app crash ║
║ ║
╚═════════════════════════════════════════════════════════════════╝
2. Alacritty VTE Parser
Interprets escape sequences. Same code used by Alacritty terminal.╔═════════════════════════════════════════════════════════════════╗
║ VTE PARSER ║
╠═════════════════════════════════════════════════════════════════╣
║ ║
║ Input: ESC[31mHelloESC[0m ║
║ │ ║
║ ▼ ║
║ Meaning: [red color] Hello [reset color] ║
║ │ ║
║ ▼ ║
║ Grid: Cell(H, red), Cell(e, red), Cell(l, red), ... ║
║ ║
║ Benefit: Battle-tested parsing (Alacritty = production) ║
║ ║
╚═════════════════════════════════════════════════════════════════╝
3. Frame Detection
Detects when a complete frame is ready.╔═════════════════════════════════════════════════════════════════╗
║ FRAME DETECTION ║
╠═════════════════════════════════════════════════════════════════╣
║ ║
║ Detection Methods: ║
║ ║
║ 1. Cursor Hide/Show (Ink Pattern) ║
║ ┌────────────────────────────────────────────┐ ║
║ │ Cursor HIDE ── content ── Cursor SHOW │ ║
║ │ │ │ │ ║
║ │ "Drawing" "Done drawing" │ ║
║ └────────────────────────────────────────────┘ ║
║ ║
║ 2. BSU/ESU (Explicit Protocol) ║
║ ┌────────────────────────────────────────────┐ ║
║ │ BSU ─────── content ─────── ESU ║ ║
║ │ │ │ │ ║
║ │ "Begin" "End" │ ║
║ └────────────────────────────────────────────┘ ║
║ ║
║ 3. Implicit Sync (Timeout) ║
║ ┌────────────────────────────────────────────┐ ║
║ │ Clear screen ── wait 8ms ── assume done │ ║
║ └────────────────────────────────────────────┘ ║
║ ║
║ Benefit: Works with existing programs (no changes needed) ║
║ ║
╚═════════════════════════════════════════════════════════════════╝
4. Smart Diff
Compares frames to minimize data transfer.╔═════════════════════════════════════════════════════════════════╗
║ SMART DIFF ║
╠═════════════════════════════════════════════════════════════════╣
║ ║
║ Previous Frame Current Frame ║
║ ┌────────────┐ ┌────────────┐ ║
║ │ Line 1 ████│ │ Line 1 ████│ same (hash match) ║
║ │ Line 2 ████│ │ Line 2 ████│ same (hash match) ║
║ │ Line 3 ████│ vs │ Line 3 ░░░░│ CHANGED! ║
║ │ Line 4 ████│ │ Line 4 ████│ same (hash match) ║
║ └────────────┘ └────────────┘ ║
║ ║
║ Result: Only send Line 3 ║
║ 99.95% less data! ║
║ ║
║ Benefit: Fast even with slow connections ║
║ ║
╚═════════════════════════════════════════════════════════════════╝
5. Flow Control (ACK)
Prevents overwhelming the frontend.╔═════════════════════════════════════════════════════════════════╗
║ FLOW CONTROL ║
╠═════════════════════════════════════════════════════════════════╣
║ ║
║ Without Flow Control (Traditional): ║
║ ┌────────────────────────────────────────────────────┐ ║
║ │ Backend: SEND SEND SEND SEND SEND SEND SEND... │ ║
║ │ Frontend: ──processing── ← can't keep up! → │ ║
║ │ Result: Lag, frozen UI, dropped frames │ ║
║ └────────────────────────────────────────────────────┘ ║
║ ║
║ With Flow Control (MonoTerm): ║
║ ┌────────────────────────────────────────────────────┐ ║
║ │ Backend: SEND ── wait ── SEND ── wait ── ... │ ║
║ │ Frontend: process → ACK → process → ACK → ... │ ║
║ │ Result: Smooth, no lag, no drops │ ║
║ └────────────────────────────────────────────────────┘ ║
║ ║
║ Benefit: Frontend always in control ║
║ ║
╚═════════════════════════════════════════════════════════════════╝
Why “Atomic”?
╔═════════════════════════════════════════════════════════════════╗
║ ATOMIC = INDIVISIBLE ║
╠═════════════════════════════════════════════════════════════════╣
║ ║
║ In physics: An atom is the smallest unit of matter ║
║ ║
║ In MonoTerm: A frame is the smallest unit of display ║
║ ║
║ ┌─────────────────────────────────────┐ ║
║ │ │ ║
║ │ You see complete frames │ ║
║ │ or nothing at all. │ ║
║ │ │ ║
║ │ Never partial garbage. │ ║
║ │ │ ║
║ └─────────────────────────────────────┘ ║
║ ║
║ This is the "Atomic UX" promise. ║
║ ║
╚═════════════════════════════════════════════════════════════════╝
Performance
╔═════════════════════════════════════════════════════════════════╗
║ REAL-WORLD PERFORMANCE ║
╠═════════════════════════════════════════════════════════════════╣
║ ║
║ Scenario: Normal typing in terminal ║
║ ║
║ Traditional: ████████████████████████████████████ 100% ║
║ MonoTerm: █ 0.05% ║
║ ║
║ 99.95% less data transferred! ║
║ ║
║ ─────────────────────────────────────────────────────────── ║
║ ║
║ Scenario: AI streaming output ║
║ ║
║ Traditional: May freeze or lag ║
║ MonoTerm: Smooth streaming always ║
║ ║
╚═════════════════════════════════════════════════════════════════╝
Core Principles
SMPC
Simplicity is Managed Part ChaosComplex things happen behind the scenes so you experience simplicity.
OFAC
Order is a Feature of Accepted ChaosOrder comes from well-designed constraints, not forced patterns.
Summary
╔═════════════════════════════════════════════════════════════════════════════════╗
║ MONOTERM DATA FLOW ║
╠═════════════════════════════════════════════════════════════════════════════════╣
║ ║
║ Shell Output (raw bytes) ║
║ │ ║
║ ▼ ║
║ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ║
║ │ PTY Daemon │───▶│ Session │───▶│ AtomicState │───▶│ Cell │ ║
║ │ (Tier 1) │ │ Actor │ │ (Tier 3) │ │ Converter │ ║
║ │ │ │ (Tier 2) │ │ │ │ (Tier 4) │ ║
║ └─────────────┘ └─────────────┘ └──────┬──────┘ └─────────────┘ ║
║ │ ║
║ ┌──────────────────────┘ ║
║ │ ║
║ │ Data Processing (Rust backend): ║
║ │ ║
║ │ ┌─────────────────────────────────────────────────┐ ║
║ │ │ 1. Accumulate (collect bytes) │ ║
║ │ │ 2. Frame boundary (detect complete frame) │ ║
║ │ │ 3. Parse (Alacritty VTE) │ ║
║ │ │ 4. Compare (find what changed) │ ║
║ │ │ 5. Control flow (wait for frontend ACK) │ ║
║ │ └─────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ┌─────────────┐ ║
║ │ GridUpdate │ (only changed data) ║
║ └──────┬──────┘ ║
║ │ Tauri emit() ║
║ ▼ ║
║ ┌─────────────┐ ║
║ │ GridBuffer │ (Tier 5: direct xterm.js injection) ║
║ │ Injector │ ║
║ └──────┬──────┘ ║
║ │ WebGL ║
║ ▼ ║
║ Your Eyes ║
║ ║
║ Result: Smooth, atomic frames with minimal data transfer ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝
Technology Stack
| Layer | Technology | Purpose |
|---|---|---|
| App Framework | Tauri 2.0 | Native app with web frontend |
| Backend | Rust | Performance-critical operations |
| Frontend | TypeScript | UI and user interaction |
| PTY Management | Rust Daemon | Session lifecycle, Unix sockets |
| VTE Parsing | Alacritty VTE | ANSI sequence processing |
| Frame Detection | Atomic Loop | Detects complete frame boundaries |
| Optimization | Smart Diff | 99.95% data reduction |
| Rendering | xterm.js WebGL | GPU-accelerated display |
| Flow Control | ACK Handshake | Consumer-driven rate control |
Next Steps
5-Tier Architecture
Deep dive into the 5-tier processing pipeline.
SessionActor Pattern
Learn how we achieve lock-free concurrency.
Why Monolex is Fast
Understand the performance optimizations.
Alacritty Integration
How we integrate Alacritty with xterm.js.