Developer Guides

View Source

Technical documentation for TermUI internals and architecture.

Guides

GuideDescription
01-architecture-overview.mdSystem layers, process hierarchy, data flow
02-runtime-internals.mdGenServer event loop, state management, lifecycle
03-rendering-pipeline.mdView → Buffer → Diff → Output stages
04-event-system.mdInput parsing, escape sequences, dispatch
05-buffer-management.mdETS double buffering, cell storage
06-terminal-layer.mdRaw mode, ANSI sequences, platform handling
07-elm-implementation.mdThe Elm Architecture adapted for OTP
08-creating-widgets.mdHow to create and contribute new widgets
09-testing-framework.mdComponent and widget testing framework

Reading Order

For new contributors:

  1. Architecture Overview - Understand the layers
  2. Elm Implementation - Learn the component model
  3. Runtime Internals - See how components are orchestrated
  4. Event System - Follow input from terminal to component
  5. Rendering Pipeline - Follow output from component to terminal
  6. Buffer Management - Understand the ETS buffer system
  7. Terminal Layer - Low-level terminal details

Key Concepts

Three-Layer Architecture

┌─────────────────────────────────────┐
│          Widget Layer               │  ← Components (Elm Architecture)
├─────────────────────────────────────┤
│         Renderer Layer              │  ← Buffers, Diff, Output
├─────────────────────────────────────┤
│          Port Layer                 │  ← Terminal I/O
└─────────────────────────────────────┘

Data Flow

Event → event_to_msg → Message → update → State → view → Render Tree → Buffer → Diff → Terminal

Key Files

FilePurpose
lib/term_ui/runtime.exCentral GenServer orchestrating everything
lib/term_ui/renderer/buffer.exETS-backed screen buffer
lib/term_ui/renderer/diff.exDifferential rendering algorithm
lib/term_ui/renderer/sequence_buffer.exANSI sequence batching
lib/term_ui/terminal.exRaw mode and terminal control
lib/term_ui/terminal/input_reader.exStdin reading and event parsing
lib/term_ui/terminal/escape_parser.exEscape sequence parsing

Diagrams

All guides include Mermaid diagrams. To view them:

  • GitHub renders Mermaid automatically
  • VS Code with Markdown Preview Mermaid extension
  • Mermaid Live Editor