# kmukuch/ctuix architecture

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

- Interactive diagram: https://gitdiagram.com/kmukuch/ctuix
- Repository: https://github.com/kmukuch/ctuix

## Overview

CTUIX is a C library for building ncurses text interfaces from DTD-validated XML. Its documented user workflow initializes the terminal, parses one or more screen files into a manager, runs the UI loop, then frees manager and library resources. The graph preserves the XML widget types, tree/model layer, navigation, and error handling. Some runtime source was not excerpted; those gaps limit the call relationships shown.

Main entry points: [`src/ctuix_parse.c`](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_parse.c) (XML parser), [`src/ctuix_tree.c`](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_tree.c) (Node tree), [`src/ctuix_entry.c`](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_entry.c) (Text entry), [`src/ctuix_selection_box.c`](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_selection_box.c) (Selection box)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["UI lifecycle"]
  node_api["Public API<br/>[ctuix.h]"]
  node_init["Terminal setup<br/>[ctuix_core.c]"]
  node_loop["Event loop<br/>[ctuix_core.c]"]
end

subgraph group_model["XML and tree"]
  node_parser["XML parser<br/>[ctuix_parse.c]"]
  node_schema["XML DTD<br/>[ctuix.dtd]"]
  node_tree["Node tree<br/>[ctuix_tree.c]"]
end

subgraph group_widgets["UI widgets"]
  node_root["Root widget<br/>[ctuix_root.c]"]
  node_panel["Panel<br/>[ctuix_panel.c]"]
  node_label["Label<br/>[ctuix_label.c]"]
  node_button["Button<br/>[ctuix_button.c]"]
  node_entry["Text entry<br/>[ctuix_entry.c]"]
  node_selection["Selection box"]
  node_item["List item"]
  node_scroll["Scroll panel"]
end

subgraph group_interaction["Input and navigation"]
  node_nav["Focus navigation<br/>[ctuix_nav.c]"]
end

subgraph group_support["Errors and resources"]
  node_errors["Error display<br/>[ctuix_error.c]"]
  node_cleanup["Resource cleanup<br/>[ctuix_parse.c]"]
end

node_user(("Application"))
node_ncurses["ncurses"]
node_libxml["libxml2"]

node_user -->|"initializes"| node_init
node_user -->|"parses screens"| node_parser
node_parser -->|"validates against"| node_schema
node_parser -->|"reads XML"| node_libxml
node_parser -->|"builds manager"| node_tree
node_parser -->|"creates"| node_root
node_parser -->|"creates"| node_panel
node_parser -->|"creates"| node_label
node_parser -->|"creates"| node_button
node_parser -->|"creates"| node_entry
node_parser -->|"creates"| node_selection
node_parser -->|"creates"| node_item
node_parser -->|"creates"| node_scroll
node_parser -->|"reports failures"| node_errors
node_user -->|"runs manager"| node_loop
node_loop -->|"draws tree"| node_tree
node_user -->|"frees resources"| node_cleanup
node_entry -->|"selects next"| node_nav
node_selection -->|"selects next"| node_nav
node_scroll -->|"selects next"| node_nav
node_entry -->|"redraws"| node_tree
node_selection -->|"redraws"| node_tree
node_scroll -->|"redraws"| node_tree
node_init -.->|"initializes"| node_ncurses

click node_api "https://github.com/kmukuch/ctuix/blob/main/include/ctuix.h"
click node_init "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_core.c"
click node_loop "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_core.c"
click node_parser "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_parse.c"
click node_schema "https://github.com/kmukuch/ctuix/blob/main/data/ctuix.dtd"
click node_tree "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_tree.c"
click node_root "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_root.c"
click node_panel "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_panel.c"
click node_label "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_label.c"
click node_button "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_button.c"
click node_entry "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_entry.c"
click node_selection "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_selection_box.c"
click node_item "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_selection_box.c"
click node_scroll "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_scroll_panel.c"
click node_nav "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_nav.c"
click node_errors "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_error.c"
click node_cleanup "https://github.com/kmukuch/ctuix/blob/main/src/ctuix_parse.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_api,node_init,node_loop toneBlue
class node_parser,node_schema,node_tree toneAmber
class node_root,node_panel,node_label,node_button,node_entry,node_selection,node_item,node_scroll toneMint
class node_nav toneRose
class node_errors,node_cleanup,node_user,node_ncurses,node_libxml toneIndigo
```

## Components

### UI lifecycle

- [Public API](https://github.com/kmukuch/ctuix/blob/main/include/ctuix.h): `include/ctuix.h`
- [Terminal setup](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_core.c): `src/ctuix_core.c`
- [Event loop](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_core.c): `src/ctuix_core.c`

### XML and tree

- [XML parser](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_parse.c): `src/ctuix_parse.c`
- [XML DTD](https://github.com/kmukuch/ctuix/blob/main/data/ctuix.dtd): `data/ctuix.dtd`
- [Node tree](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_tree.c): `src/ctuix_tree.c`

### UI widgets

- [Root widget](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_root.c): `src/ctuix_root.c`
- [Panel](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_panel.c): `src/ctuix_panel.c`
- [Label](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_label.c): `src/ctuix_label.c`
- [Button](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_button.c): `src/ctuix_button.c`
- [Text entry](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_entry.c): `src/ctuix_entry.c`
- [Selection box](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_selection_box.c): `src/ctuix_selection_box.c`
- [List item](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_selection_box.c): `src/ctuix_selection_box.c`
- [Scroll panel](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_scroll_panel.c): `src/ctuix_scroll_panel.c`

### Input and navigation

- [Focus navigation](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_nav.c): `src/ctuix_nav.c`

### Errors and resources

- [Error display](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_error.c): `src/ctuix_error.c`
- [Resource cleanup](https://github.com/kmukuch/ctuix/blob/main/src/ctuix_parse.c): `src/ctuix_parse.c`

### Other components

- **Application**
- **ncurses**
- **libxml2**

## Connections

- Application → Terminal setup: initializes (evidence: `README.md`)
- Application → XML parser: parses screens (evidence: `README.md`)
- XML parser → XML DTD: validates against (evidence: `README.md`)
- XML parser → libxml2: reads XML (evidence: `src/ctuix_parse.c`)
- XML parser → Node tree: builds manager (evidence: `src/ctuix_parse.c`)
- XML parser → Root widget: creates (evidence: `src/ctuix_parse.c`)
- XML parser → Panel: creates (evidence: `src/ctuix_parse.c`)
- XML parser → Label: creates (evidence: `src/ctuix_parse.c`)
- XML parser → Button: creates (evidence: `src/ctuix_parse.c`)
- XML parser → Text entry: creates (evidence: `src/ctuix_parse.c`)
- XML parser → Selection box: creates (evidence: `src/ctuix_parse.c`)
- XML parser → List item: creates (evidence: `src/ctuix_parse.c`)
- XML parser → Scroll panel: creates (evidence: `src/ctuix_parse.c`)
- XML parser → Error display: reports failures (evidence: `src/ctuix_parse.c`)
- Application → Event loop: runs manager (evidence: `README.md`)
- Event loop → Node tree: draws tree (evidence: `README.md`)
- Application → Resource cleanup: frees resources (evidence: `README.md`)
- Text entry → Focus navigation: selects next (evidence: `src/ctuix_entry.c`)
- Selection box → Focus navigation: selects next (evidence: `src/ctuix_selection_box.c`)
- Scroll panel → Focus navigation: selects next (evidence: `src/ctuix_scroll_panel.c`)
- Text entry → Node tree: redraws (evidence: `src/ctuix_entry.c`)
- Selection box → Node tree: redraws (evidence: `src/ctuix_selection_box.c`)
- Scroll panel → Node tree: redraws (evidence: `src/ctuix_scroll_panel.c`)
- Terminal setup → ncurses: initializes
