# termbox/termbox2 architecture

> Architecture diagram of the GitHub repository termbox/termbox2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/termbox/termbox2
- Repository: https://github.com/termbox/termbox2

## Overview

termbox2 is a single-header C terminal I/O library for applications that draw TUIs and handle terminal input. The main workflow is to initialize terminal state, render cells or formatted text into a screen buffer, present updates as terminal escape sequences, and poll parsed keyboard, mouse, or resize events. The header also contains terminal capability and terminfo handling, Unicode cell-width/grapheme support, and optional color modes. The excerpt is partial, so links among internal stages are limited to behavior explicitly documented in the README or shown in the excerpt.

Main entry points: [`termbox2.h`](https://github.com/termbox/termbox2/blob/master/termbox2.h) (termbox API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_api["termbox API<br/>[termbox2.h]"]
end

subgraph group_render["Rendering"]
  node_screen["Cell screen buffer<br/>[termbox2.h]"]
  node_text["Text formatting<br/>[termbox2.h]"]
  node_present["Screen presentation<br/>[termbox2.h]"]
end

subgraph group_terminal["Terminal support"]
  node_output["Terminal output<br/>[termbox2.h]"]
  node_caps["Terminal capabilities<br/>[termbox2.h]"]
  node_terminfo["Terminfo loading<br/>[termbox2.h]"]
end

subgraph group_input["Input and Unicode"]
  node_input["Event polling<br/>[termbox2.h]"]
  node_parser["Escape parser<br/>[termbox2.h]"]
  node_unicode["Unicode cells<br/>[termbox2.h]"]
end

node_app(("TUI application"))
node_terminal_actor["Terminal"]

node_app -->|"calls"| node_api
node_api -.->|"sets cells"| node_screen
node_api -.->|"prints text"| node_text
node_api -.->|"presents screen"| node_present
node_api -.->|"polls events"| node_input
node_screen -.->|"renders updates"| node_present
node_text -.->|"formats text"| node_unicode
node_present -.->|"emits sequences"| node_output
node_output -.->|"writes output"| node_terminal_actor
node_caps -.->|"loads capabilities"| node_terminfo
node_caps -->|"provides sequences"| node_output
node_terminal_actor -.->|"provides input"| node_input
node_input -.->|"parses input"| node_parser
node_parser -.->|"returns events"| node_api
node_unicode -.->|"supports graphemes"| node_screen

click node_api "https://github.com/termbox/termbox2/blob/master/termbox2.h"
click node_screen "https://github.com/termbox/termbox2/blob/master/termbox2.h"
click node_text "https://github.com/termbox/termbox2/blob/master/termbox2.h"
click node_present "https://github.com/termbox/termbox2/blob/master/termbox2.h"
click node_output "https://github.com/termbox/termbox2/blob/master/termbox2.h"
click node_caps "https://github.com/termbox/termbox2/blob/master/termbox2.h"
click node_terminfo "https://github.com/termbox/termbox2/blob/master/termbox2.h"
click node_input "https://github.com/termbox/termbox2/blob/master/termbox2.h"
click node_parser "https://github.com/termbox/termbox2/blob/master/termbox2.h"
click node_unicode "https://github.com/termbox/termbox2/blob/master/termbox2.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_app toneBlue
class node_screen,node_text,node_present toneAmber
class node_output,node_caps,node_terminfo toneMint
class node_input,node_parser,node_unicode toneRose
class node_terminal_actor toneIndigo
```

## Components

### Application API

- [termbox API](https://github.com/termbox/termbox2/blob/master/termbox2.h): `termbox2.h`

### Rendering

- [Cell screen buffer](https://github.com/termbox/termbox2/blob/master/termbox2.h): `termbox2.h`
- [Text formatting](https://github.com/termbox/termbox2/blob/master/termbox2.h): `termbox2.h`
- [Screen presentation](https://github.com/termbox/termbox2/blob/master/termbox2.h): `termbox2.h`

### Terminal support

- [Terminal output](https://github.com/termbox/termbox2/blob/master/termbox2.h): `termbox2.h`
- [Terminal capabilities](https://github.com/termbox/termbox2/blob/master/termbox2.h): `termbox2.h`
- [Terminfo loading](https://github.com/termbox/termbox2/blob/master/termbox2.h): `termbox2.h`

### Input and Unicode

- [Event polling](https://github.com/termbox/termbox2/blob/master/termbox2.h): `termbox2.h`
- [Escape parser](https://github.com/termbox/termbox2/blob/master/termbox2.h): `termbox2.h`
- [Unicode cells](https://github.com/termbox/termbox2/blob/master/termbox2.h): `termbox2.h`

### Other components

- **TUI application**
- **Terminal**

## Connections

- TUI application → termbox API: calls (evidence: `README.md`)
- termbox API → Cell screen buffer: sets cells (evidence: `termbox2.h`)
- termbox API → Text formatting: prints text (evidence: `termbox2.h`)
- termbox API → Screen presentation: presents screen (evidence: `termbox2.h`)
- termbox API → Event polling: polls events (evidence: `termbox2.h`)
- Cell screen buffer → Screen presentation: renders updates (evidence: `termbox2.h`)
- Text formatting → Unicode cells: formats text (evidence: `termbox2.h`)
- Screen presentation → Terminal output: emits sequences (evidence: `termbox2.h`)
- Terminal output → Terminal: writes output
- Terminal capabilities → Terminfo loading: loads capabilities (evidence: `termbox2.h`)
- Terminal capabilities → Terminal output: provides sequences (evidence: `termbox2.h`)
- Terminal → Event polling: provides input
- Event polling → Escape parser: parses input (evidence: `termbox2.h`)
- Escape parser → termbox API: returns events (evidence: `termbox2.h`)
- Unicode cells → Cell screen buffer: supports graphemes (evidence: `termbox2.h`)
