# rockorager/libvaxis architecture

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

- Interactive diagram: https://gitdiagram.com/rockorager/libvaxis
- Repository: https://github.com/rockorager/libvaxis

## Overview

libvaxis is a Zig terminal UI library with a low-level terminal API and a higher-level widget framework. A typical framework application supplies a root widget; the framework runtime manages events, focus, mouse handling, and drawing. The low-level API also supports applications that manage their own event loop and screen cells. The README documents terminal capability detection and protocol features. Source excerpts were limited to the C API header, so uncertain internal call relationships are omitted.

Main entry points: [`src/Vaxis.zig`](https://github.com/rockorager/libvaxis/blob/main/src/Vaxis.zig) (Low-level API), [`src/Loop.zig`](https://github.com/rockorager/libvaxis/blob/main/src/Loop.zig) (Event loop), [`src/Window.zig`](https://github.com/rockorager/libvaxis/blob/main/src/Window.zig) (Window drawing), [`src/Parser.zig`](https://github.com/rockorager/libvaxis/blob/main/src/Parser.zig) (Input parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Terminal Runtime"]
  node_low_api["Low-level API<br/>[Vaxis.zig]"]
  node_event_loop["Event loop<br/>[Loop.zig]"]
  node_tty["TTY access<br/>[tty.zig]"]
  node_parser["Input parser<br/>[Parser.zig]"]
  node_events["Events and keys<br/>[event.zig]"]
end

subgraph group_screen["Screen and Graphics"]
  node_screen["Screen state<br/>[Screen.zig]"]
  node_window["Window drawing<br/>[Window.zig]"]
  node_cells["Cells and graphemes<br/>[Cell.zig]"]
  node_images["Terminal images<br/>[Image.zig]"]
  node_unicode["Unicode width<br/>[unicode.zig]"]
end

subgraph group_framework["Widget Framework"]
  node_framework_app["Framework runtime<br/>[App.zig]"]
  node_framework_widgets["Framework widgets"]
  node_widget_library["Widgets"]
  node_terminal_widgets["Terminal widgets"]
end

subgraph group_extras["Additional APIs"]
  node_c_api["C API<br/>[c_api.zig]"]
end

node_app(("TUI application"))
node_terminal(("Terminal"))
node_c_app(("C application"))

node_app -->|"starts"| node_framework_app
node_framework_app -->|"dispatches"| node_framework_widgets
node_app -->|"uses"| node_low_api
node_low_api -->|"uses"| node_event_loop
node_event_loop -->|"reads input"| node_tty
node_event_loop -->|"parses input"| node_parser
node_parser -->|"produces"| node_events
node_terminal -->|"input and output"| node_tty
node_low_api -->|"manages"| node_screen
node_screen -->|"creates"| node_window
node_window -->|"draws"| node_cells
node_cells -->|"uses widths"| node_unicode
node_window -->|"draws images"| node_images
node_app -.->|"may use"| node_widget_library
node_app -.->|"may use"| node_terminal_widgets
node_c_app -->|"calls"| node_c_api
node_c_api -->|"exposes"| node_low_api

click node_framework_app "https://github.com/rockorager/libvaxis/blob/main/src/vxfw/App.zig"
click node_framework_widgets "https://github.com/rockorager/libvaxis/tree/main/src/vxfw"
click node_widget_library "https://github.com/rockorager/libvaxis/tree/main/src/widgets"
click node_terminal_widgets "https://github.com/rockorager/libvaxis/tree/main/src/widgets/terminal"
click node_low_api "https://github.com/rockorager/libvaxis/blob/main/src/Vaxis.zig"
click node_event_loop "https://github.com/rockorager/libvaxis/blob/main/src/Loop.zig"
click node_tty "https://github.com/rockorager/libvaxis/blob/main/src/tty.zig"
click node_parser "https://github.com/rockorager/libvaxis/blob/main/src/Parser.zig"
click node_events "https://github.com/rockorager/libvaxis/blob/main/src/event.zig"
click node_screen "https://github.com/rockorager/libvaxis/blob/main/src/Screen.zig"
click node_window "https://github.com/rockorager/libvaxis/blob/main/src/Window.zig"
click node_cells "https://github.com/rockorager/libvaxis/blob/main/src/Cell.zig"
click node_images "https://github.com/rockorager/libvaxis/blob/main/src/Image.zig"
click node_unicode "https://github.com/rockorager/libvaxis/blob/main/src/unicode.zig"
click node_c_api "https://github.com/rockorager/libvaxis/blob/main/src/c_api.zig"

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_low_api,node_event_loop,node_tty,node_parser,node_events,node_app toneBlue
class node_screen,node_window,node_cells,node_images,node_unicode toneAmber
class node_framework_app,node_framework_widgets,node_widget_library,node_terminal_widgets toneMint
class node_c_api toneRose
class node_terminal,node_c_app toneIndigo
```

## Components

### Terminal Runtime

- [Low-level API](https://github.com/rockorager/libvaxis/blob/main/src/Vaxis.zig): `src/Vaxis.zig`
- [Event loop](https://github.com/rockorager/libvaxis/blob/main/src/Loop.zig): `src/Loop.zig`
- [TTY access](https://github.com/rockorager/libvaxis/blob/main/src/tty.zig): `src/tty.zig`
- [Input parser](https://github.com/rockorager/libvaxis/blob/main/src/Parser.zig): `src/Parser.zig`
- [Events and keys](https://github.com/rockorager/libvaxis/blob/main/src/event.zig): `src/event.zig`

### Screen and Graphics

- [Screen state](https://github.com/rockorager/libvaxis/blob/main/src/Screen.zig): `src/Screen.zig`
- [Window drawing](https://github.com/rockorager/libvaxis/blob/main/src/Window.zig): `src/Window.zig`
- [Cells and graphemes](https://github.com/rockorager/libvaxis/blob/main/src/Cell.zig): `src/Cell.zig`
- [Terminal images](https://github.com/rockorager/libvaxis/blob/main/src/Image.zig): `src/Image.zig`
- [Unicode width](https://github.com/rockorager/libvaxis/blob/main/src/unicode.zig): `src/unicode.zig`

### Widget Framework

- [Framework runtime](https://github.com/rockorager/libvaxis/blob/main/src/vxfw/App.zig): `src/vxfw/App.zig`
- [Framework widgets](https://github.com/rockorager/libvaxis/tree/main/src/vxfw): `src/vxfw`
- [Widgets](https://github.com/rockorager/libvaxis/tree/main/src/widgets): `src/widgets`
- [Terminal widgets](https://github.com/rockorager/libvaxis/tree/main/src/widgets/terminal): `src/widgets/terminal`

### Additional APIs

- [C API](https://github.com/rockorager/libvaxis/blob/main/src/c_api.zig): `src/c_api.zig`

### Other components

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

## Connections

- TUI application → Framework runtime: starts
- Framework runtime → Framework widgets: dispatches
- TUI application → Low-level API: uses
- Low-level API → Event loop: uses
- Event loop → TTY access: reads input
- Event loop → Input parser: parses input
- Input parser → Events and keys: produces
- Terminal → TTY access: input and output
- Low-level API → Screen state: manages
- Screen state → Window drawing: creates
- Window drawing → Cells and graphemes: draws
- Cells and graphemes → Unicode width: uses widths
- Window drawing → Terminal images: draws images
- TUI application → Widgets: may use
- TUI application → Terminal widgets: may use
- C application → C API: calls
- C API → Low-level API: exposes