# benjcal/zltt architecture

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

- Interactive diagram: https://gitdiagram.com/benjcal/zltt
- Repository: https://github.com/benjcal/zltt

## Overview

ZLTT is a Lua-scriptable text UI: a user launches a Lua program, which uses the host’s text-output API while the application renders the interface and forwards key events to the script. The README documents multiline main text, a bottom-line subtitle, and keydown callbacks. Source excerpts cover only the Cairo/SDL bridge, so internal Zig call wiring is necessarily conservative.

Main entry points: [`src/app.zig`](https://github.com/benjcal/zltt/blob/master/src/app.zig) (Application), [`src/lua.zig`](https://github.com/benjcal/zltt/blob/master/src/lua.zig) (Lua bridge), [`src/cairo.zig`](https://github.com/benjcal/zltt/blob/master/src/cairo.zig) (Cairo layer), [`libs/cairosdl/cairosdl.c`](https://github.com/benjcal/zltt/blob/master/libs/cairosdl/cairosdl.c) (Cairo-SDL bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Zig host"]
  node_main["Program entry<br/>[main.zig]"]
  node_app["Application<br/>[app.zig]"]
  node_lua_bridge["Lua bridge<br/>[lua.zig]"]
  node_c_bindings["C bindings<br/>[c.zig]"]
end

subgraph group_script["Lua programs"]
  node_lua_api["Lua API<br/>[init.lua]"]
  node_todo["Todo example<br/>[init.lua]"]
  node_rpn["RPN example<br/>[init.lua]"]
end

subgraph group_render["Rendering"]
  node_sdl_layer["SDL layer<br/>[sdl.zig]"]
  node_cairo_layer["Cairo layer<br/>[cairo.zig]"]
  node_cairosdl["Cairo-SDL bridge<br/>[cairosdl.c]"]
end

node_user(("User"))
node_lua_runtime["LuaJIT"]
node_sdl["SDL2"]
node_cairo["Cairo"]
node_fontconfig["fontconfig"]

node_user -->|"launches"| node_main
node_main -->|"starts"| node_app
node_app -->|"uses"| node_lua_bridge
node_lua_bridge -->|"embeds"| node_lua_runtime
node_lua_bridge -->|"exposes"| node_lua_api
node_user -->|"runs example"| node_todo
node_user -->|"runs example"| node_rpn
node_todo -->|"uses API"| node_lua_api
node_rpn -->|"uses API"| node_lua_api
node_app -->|"renders with"| node_sdl_layer
node_app -->|"forwards keydown"| node_lua_bridge
node_sdl_layer -->|"uses"| node_sdl
node_cairo_layer -->|"uses"| node_cairo
node_cairo_layer -->|"uses"| node_cairosdl
node_cairosdl -->|"binds surfaces"| node_sdl
node_cairosdl -->|"creates surfaces"| node_cairo
node_cairo_layer -->|"loads fonts"| node_fontconfig

click node_main "https://github.com/benjcal/zltt/blob/master/src/main.zig"
click node_app "https://github.com/benjcal/zltt/blob/master/src/app.zig"
click node_lua_bridge "https://github.com/benjcal/zltt/blob/master/src/lua.zig"
click node_c_bindings "https://github.com/benjcal/zltt/blob/master/src/c.zig"
click node_lua_api "https://github.com/benjcal/zltt/blob/master/lua/init.lua"
click node_todo "https://github.com/benjcal/zltt/blob/master/lua/examples/todo/init.lua"
click node_rpn "https://github.com/benjcal/zltt/blob/master/lua/examples/rpn/init.lua"
click node_sdl_layer "https://github.com/benjcal/zltt/blob/master/src/sdl.zig"
click node_cairo_layer "https://github.com/benjcal/zltt/blob/master/src/cairo.zig"
click node_cairosdl "https://github.com/benjcal/zltt/blob/master/libs/cairosdl/cairosdl.c"

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_main,node_app,node_lua_bridge,node_c_bindings,node_user toneBlue
class node_lua_api,node_todo,node_rpn toneAmber
class node_sdl_layer,node_cairo_layer,node_cairosdl toneMint
class node_lua_runtime,node_sdl,node_cairo,node_fontconfig toneIndigo
```

## Components

### Zig host

- [Program entry](https://github.com/benjcal/zltt/blob/master/src/main.zig): `src/main.zig`
- [Application](https://github.com/benjcal/zltt/blob/master/src/app.zig): `src/app.zig`
- [Lua bridge](https://github.com/benjcal/zltt/blob/master/src/lua.zig): `src/lua.zig`
- [C bindings](https://github.com/benjcal/zltt/blob/master/src/c.zig): `src/c.zig`

### Lua programs

- [Lua API](https://github.com/benjcal/zltt/blob/master/lua/init.lua): `lua/init.lua`
- [Todo example](https://github.com/benjcal/zltt/blob/master/lua/examples/todo/init.lua): `lua/examples/todo/init.lua`
- [RPN example](https://github.com/benjcal/zltt/blob/master/lua/examples/rpn/init.lua): `lua/examples/rpn/init.lua`

### Rendering

- [SDL layer](https://github.com/benjcal/zltt/blob/master/src/sdl.zig): `src/sdl.zig`
- [Cairo layer](https://github.com/benjcal/zltt/blob/master/src/cairo.zig): `src/cairo.zig`
- [Cairo-SDL bridge](https://github.com/benjcal/zltt/blob/master/libs/cairosdl/cairosdl.c): `libs/cairosdl/cairosdl.c`

### Other components

- **User**
- **LuaJIT**
- **SDL2**
- **Cairo**
- **fontconfig**

## Connections

- User → Program entry: launches
- Program entry → Application: starts
- Application → Lua bridge: uses
- Lua bridge → LuaJIT: embeds
- Lua bridge → Lua API: exposes
- User → Todo example: runs example
- User → RPN example: runs example
- Todo example → Lua API: uses API
- RPN example → Lua API: uses API
- Application → SDL layer: renders with
- Application → Lua bridge: forwards keydown
- SDL layer → SDL2: uses
- Cairo layer → Cairo: uses
- Cairo layer → Cairo-SDL bridge: uses
- Cairo-SDL bridge → SDL2: binds surfaces
- Cairo-SDL bridge → Cairo: creates surfaces
- Cairo layer → fontconfig: loads fonts