# abduazim424/rex architecture

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

- Interactive diagram: https://gitdiagram.com/abduazim424/rex
- Repository: https://github.com/abduazim424/rex

## Overview

##### What this project is (type + purpose)
**Rex** is a **native Linux desktop utility**: a **lightweight application launcher** written in **C++17**. It runs as a single local process that:
- Creates and manages a small UI window via **X11/XCB**
- Captures keyboard input (XCB + keysyms)
- Renders text/UI using **Cairo (XCB backend)** + **Pango**
- Produces “suggestions” (likely app/command matches)
- Executes the selected command/application (via an “execution engine”)

##### File-structure-driven component breakdown (what to map)
From the tree, the core components are strongly implied by the headers and cpp files:

##### Entry / orchestration
- `src/launcher.cpp`
Likely the `main()` entry point. Owns startup, instantiates the app controller, enters the event loop.

- `include/rex.hpp`, `src/rex.cpp`
Likely the central “application/controller” object: wires UI, input, suggestions, execution together.

##### UI + rendering
- `include/ui.hpp`, `src/ui.cpp`
XCB window creation, Cairo surface/context setup, Pango layout creation, drawing loop, re-render triggers.

##### Input/event handling
- `include/inputhandler.hpp`, `src/inputhandler.cpp`
Handles XCB event polling/dispatch (KeyPress, KeyRelease, Expose, Focus), converts keycodes to text using `xcb-keysyms`, updates the current query string, handles navigation/selection keys.

##### Execution/spawning
- `include/executionengine.hpp`, `src/executionengine.cpp`

##### Domain model / suggestion logic
- `include/suggestion.hpp`

- `include/types.hpp`
Shared types / aliases / enums used across components (e.g., key enums, config structs, UI state).

- **X Server (X11)** (external runtime service)
- **XCB** + **xcb-keysyms** (client-side protocol + key translation)
- **Cairo (XCB backend)** (2D rendering to an X drawable)
- **Pango** (font/text layout shaping)
- OS process APIs (Linux): `fork/exec`/`posix_spawn`, environment PATH, filesystem

Build system boundary:

##### UI Renderer (`ui.cpp/.hpp`)
- Uses Cairo + Pango
- Owns XCB window/surface
##### Input Handler (`inputhandler.cpp/.hpp`)
- Uses xcb-keysyms
##### Execution Engine (`executionengine.cpp/.hpp`)

- Launcher → Rex App Controller: “init + run()”
- Rex App Controller ↔ UI Renderer: “update view state / request redraw”
- Rex App Controller ↔ Input Handler: “dispatch events / receive query updates”
- Rex App Controller → Suggestion logic: “compute/filter suggestions from query”
- Rex App Controller → UI Renderer: “render(query, suggestions, selection)”
- Rex App Controller → Execution Engine: “execute(selectedSuggestion)”
- Input Handler ← X Server (via XCB): “KeyPress/KeyRelease events”

Goal: show *data flow* through the event loop and render cycle.

##### Rex App Controller triggers
- Recompute/filter suggestions (list of `Suggestion`)
- UI invalidate/redraw
##### UI Renderer
- Layout text via Pango
- Present to X window

On “Enter” key:

##### Architectural patterns to highlight (specific to this repo)

- **Single-process, event-driven architecture**
- **Controller-mediated design** (Rex object coordinating UI, input, execution)
- A lightweight “MVC-ish” separation:
- View: `UI`
- Controller: `Rex` / `InputHandler` collaboration
- Model: `Suggestion` + state types in `types.hpp`

Also call out library boundaries:
- XCB handles **events + window plumbing**
- Cairo handles **drawing**
- Pango handles **text shaping/layout**

These three together will be the “best and most accurate” representation given the repo’s current structure and early-stage scope.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 0: System Context
  %% =========================
  subgraph "System Context (Level 0)"
    direction TB

    XSrv{{"X Server (X11)"}}
    WM{{"Window Manager / Desktop Environment"}}
    OS{{"Linux OS"}}
    FS[("Filesystem<br/>(PATH,.desktop,icons)")]:::db

    subgraph "Rex (Single Local Desktop Process)"
      direction TB
      RexProc("Rex"):::app
      Note0["Event-driven GUI loop<br/>Single-process<br/>No network services"]:::note
    end

    WM -.->|"manages_windows"| XSrv
    RexProc -->|"create_window&draw"| XSrv
    XSrv -->|"key&expose&focus_events"| RexProc
    RexProc -->|"spawn_selected_app/command"| OS
    RexProc -.->|"read_scan_entries/icons (likely)"| FS
  end

  %% =========================
  %% Level 1: Runtime / Containers
  %% =========================
  subgraph "Runtime / Containers (Level 1 - Main Architecture)"
    direction TB

    subgraph "Rex Process (C++17)"
      direction TB

      Launcher("Launcher (main/bootstrap)"):::module
      RexCtl("Rex App Controller (Orchestrator)"):::module

      subgraph "UI + Rendering"
        direction TB
        UIR("UI Renderer<br/>(XCB window + draw loop)"):::module
        RenderState[("UI State<br/>(query,selection,suggestions view)")]:::db
      end

      subgraph "Input + Events"
        direction TB
        Input("Input Handler<br/>(event poll/dispatch)"):::module
        QueryState[("Query State<br/>(string,cursor)")]:::db
        SelectionState[("Selection State<br/>(index)")]:::db
      end

      subgraph "Domain / Suggestions"
        direction TB
        Types("Shared Types / Enums"):::module
        Suggestion("Suggestion (domain model)"):::module
        SuggestList[("Suggestion List<br/>Suggestion[]")]:::db
      end

      subgraph "Execution"
        direction TB
        Exec("Execution Engine<br/>(Process Spawner)"):::module
      end
    end

    %% External runtime libraries (shown as stacked components)
    subgraph "External Libraries (Runtime)"
      direction TB
      XCB["XCB (X11 client protocol)"]:::lib
      Keysyms["xcb-keysyms<br/>(keycode->keysym/text)"]:::lib
      Cairo["Cairo (XCB backend)<br/>(2D rendering)"]:::lib
      Pango["Pango<br/>(font/text shaping)"]:::lib
    end

    %% Wiring within Rex process
    Launcher -->|"init&run()"| RexCtl

    XSrv -->|"XCB_events"| Input
    Input -->|"update_query&selection"| QueryState
    Input -->|"update_selection"| SelectionState
    Input -.->|"intent:execute/confirm"| RexCtl
    Input -.->|"query_changed/navigation"| RexCtl

    RexCtl -->|"compute/filter"| Suggestion
    RexCtl -->|"store_results"| SuggestList
    RexCtl -->|"update_view_state"| RenderState
    RexCtl -.->|"invalidate/request_redraw"| UIR

    UIR -->|"read_state"| RenderState
    UIR -->|"draw_frame"| Cairo
    UIR -->|"layout_text"| Pango
    UIR -->|"present_to_window"| XCB
    XCB -->|"to_XServer"| XSrv

    Input -->|"poll/dispatch"| XCB
    Input -->|"translate_keys"| Keysyms
    Keysyms -->|"uses"| XCB

    RexCtl -->|"execute(selectedSuggestion)"| Exec
    Exec -->|"fork/exec or posix_spawn"| OS

    %% Shared types usage
    RexCtl -->|"uses"| Types
    Input -->|"uses"| Types
    UIR -->|"uses"| Types
    Suggestion -->|"uses"| Types
  end

  %% =========================
  %% Level 2: Key Flow (Dataflow / Sequence-like)
  %% =========================
  subgraph "Key Flows (Level 2 - Dataflow)"
    direction TB

    KF1["1) KeyPress/KeyRelease arrives"]:::step
    KF2["2) InputHandler decodes key<br/>(xcb-keysyms)"]:::step
    KF3["3) Update Query/Selection state"]:::step
    KF4["4) Controller recomputes suggestions<br/>(Suggestion[])"]:::step
    KF5["5) UI redraw: Pango layout + Cairo render<br/>-> X window"]:::step
    KF6["On Enter: Controller -> ExecutionEngine -> OS spawn"]:::step

    KF1 --> KF2 --> KF3 --> KF4 --> KF5 --> KF6

    KF1 -.->|"source"| XSrv
    KF2 -.->|"module"| Input
    KF3 -.->|"stores"| QueryState
    KF3 -.->|"stores"| SelectionState
    KF4 -.->|"produces"| SuggestList
    KF5 -.->|"renders_via"| UIR
    KF6 -.->|"spawns_via"| Exec
  end

  %% =========================
  %% Build / Packaging (separate view)
  %% =========================
  subgraph "Build / Packaging (Non-runtime)"
    direction TB
    CMake["CMake Build System"]:::build
    Compiler["C++17 Toolchain<br/>(compiler/linker)"]:::build
    Docs["Project Docs / Dependencies"]:::doc
    Assets["Assets (images/icons)"]:::asset

    CMake -->|"configure_generate"| Compiler
    Docs -.->|"documents_deps"| CMake
    Assets -.->|"referenced_by_UI/docs"| UIR
  end

  %% =========================
  %% Click targets (preserve all repository-path mappings)
  %% =========================
  subgraph "Repository Paths (Click Targets)"
    direction TB
    Launcher_cpp["src/launcher.cpp"]:::doc
    RexCtl_hpp["include/rex.hpp"]:::doc
    RexCtl_cpp["src/rex.cpp"]:::doc
    UIR_hpp["include/ui.hpp"]:::doc
    UIR_cpp["src/ui.cpp"]:::doc
    Input_hpp["include/inputhandler.hpp"]:::doc
    Input_cpp["src/inputhandler.cpp"]:::doc
    Exec_hpp["include/executionengine.hpp"]:::doc
    Exec_cpp["src/executionengine.cpp"]:::doc
    Suggestion_hpp["include/suggestion.hpp"]:::doc
    Types_hpp["include/types.hpp"]:::doc
    CMake_root["CMakeLists.txt"]:::doc
    CMake_src["src/CMakeLists.txt"]:::doc
    Docs_readme["README.md"]:::doc
    Assets_dir["misc/images/"]:::doc
  end

  Launcher -.->|"file"| Launcher_cpp
  RexCtl -.->|"files"| RexCtl_hpp
  RexCtl -.->|"files"| RexCtl_cpp
  UIR -.->|"files"| UIR_hpp
  UIR -.->|"files"| UIR_cpp
  Input -.->|"files"| Input_hpp
  Input -.->|"files"| Input_cpp
  Exec -.->|"files"| Exec_hpp
  Exec -.->|"files"| Exec_cpp
  Suggestion -.->|"file"| Suggestion_hpp
  Types -.->|"file"| Types_hpp
  CMake -.->|"files"| CMake_root
  CMake -.->|"files"| CMake_src
  Docs -.->|"file"| Docs_readme
  Assets -.->|"path"| Assets_dir

  click Launcher_cpp "https://github.com/abduazim424/rex/blob/develop/src/launcher.cpp"
  click RexCtl_hpp "https://github.com/abduazim424/rex/blob/develop/include/rex.hpp"
  click RexCtl_cpp "https://github.com/abduazim424/rex/blob/develop/src/rex.cpp"
  click UIR_hpp "https://github.com/abduazim424/rex/blob/develop/include/ui.hpp"
  click UIR_cpp "https://github.com/abduazim424/rex/blob/develop/src/ui.cpp"
  click Input_hpp "https://github.com/abduazim424/rex/blob/develop/include/inputhandler.hpp"
  click Input_cpp "https://github.com/abduazim424/rex/blob/develop/src/inputhandler.cpp"
  click Exec_hpp "https://github.com/abduazim424/rex/blob/develop/include/executionengine.hpp"
  click Exec_cpp "https://github.com/abduazim424/rex/blob/develop/src/executionengine.cpp"
  click Suggestion_hpp "https://github.com/abduazim424/rex/blob/develop/include/suggestion.hpp"
  click Types_hpp "https://github.com/abduazim424/rex/blob/develop/include/types.hpp"
  click CMake_root "https://github.com/abduazim424/rex/blob/develop/CMakeLists.txt"
  click CMake_src "https://github.com/abduazim424/rex/blob/develop/src/CMakeLists.txt"
  click Docs_readme "https://github.com/abduazim424/rex/blob/develop/README.md"
  click Assets_dir "https://github.com/abduazim424/rex/tree/develop/misc/images/"

  %% =========================
  %% Styles (color is critical)
  %% =========================
  classDef app fill:#1f2937,stroke:#0b1220,color:#ffffff,stroke-width:2px;
  classDef module fill:#2563eb,stroke:#1e40af,color:#ffffff,stroke-width:2px;
  classDef lib fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1.5px;
  classDef db fill:#10b981,stroke:#065f46,color:#ffffff,stroke-width:1.5px;
  classDef build fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1.5px;
  classDef doc fill:#a78bfa,stroke:#5b21b6,color:#ffffff,stroke-width:1.5px;
  classDef asset fill:#f472b6,stroke:#9d174d,color:#111827,stroke-width:1.5px;
  classDef note fill:#111827,stroke:#6b7280,color:#e5e7eb,stroke-dasharray:4 3,stroke-width:1.5px;
  classDef step fill:#334155,stroke:#0f172a,color:#e2e8f0,stroke-width:1.5px;

  class XSrv,WM,OS app
  class RexProc app
```
