# aptumfr/lv architecture

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

- Interactive diagram: https://gitdiagram.com/aptumfr/lv
- Repository: https://github.com/aptumfr/lv

## Overview

lv:: is a header-only C++20 wrapper for LVGL. The principal workflow is application code initializing LVGL, creating a display and composing a UI from widgets and layouts, then running LVGL’s timer handler to process the interface. Core wrappers provide object, event, style, and state APIs; additional modules cover animation, input, drawing, assets, internationalization, and fragments. The graph reflects README capabilities and sampled/index evidence; connections to unsampled subsystems are omitted unless documented.

Main entry points: [`include/lv/core/object.hpp`](https://github.com/aptumfr/lv/blob/master/include/lv/core/object.hpp) (Object API), [`include/lv/widgets`](https://github.com/aptumfr/lv/tree/master/include/lv/widgets) (Widgets), [`include/lv/core/objectref.hpp`](https://github.com/aptumfr/lv/blob/master/include/lv/core/objectref.hpp) (Object references), [`include/lv/core/style.hpp`](https://github.com/aptumfr/lv/blob/master/include/lv/core/style.hpp) (Style API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_ui["Application UI"]
  node_app_lifecycle["Lifecycle loop<br/>[app.hpp]"]
  node_display["Display setup<br/>[display.hpp]"]
  node_component["Components<br/>[component.hpp]"]
  node_widgets["Widgets"]
  node_layout["Layouts"]
  node_state["Reactive state<br/>[state.hpp]"]
  node_label["Label widget<br/>[label.hpp]"]
end

subgraph group_core["Core wrappers"]
  node_object["Object API<br/>[object.hpp]"]
  node_object_ref["Object references<br/>[objectref.hpp]"]
  node_events["Typed events<br/>[event.hpp]"]
  node_styles["Style API<br/>[style.hpp]"]
  node_color["Color utilities<br/>[color.hpp]"]
  node_version["Version support<br/>[version.hpp]"]
  node_wrapping["C API interop<br/>[wrap.hpp]"]
  node_strings["String utilities<br/>[string_utils.hpp]"]
end

subgraph group_presentation["Presentation"]
  node_drawing["Drawing APIs"]
  node_animation["Animation<br/>[anim.hpp]"]
  node_input["Input devices<br/>[indev.hpp]"]
  node_font_loader["Font loading<br/>[font_loader.hpp]"]
  node_image["Image support<br/>[image.hpp]"]
  node_filesystem["Filesystem<br/>[fs.hpp]"]
  node_timer["Timers<br/>[timer.hpp]"]
end

subgraph group_extensions["Runtime extensions"]
  node_i18n["Internationalization<br/>[translation.hpp]"]
  node_fragments["Fragment navigation<br/>[fragment.hpp]"]
end

node_developer(("Application code"))
node_lvgl["LVGL runtime"]

node_developer -->|"initializes and runs"| node_app_lifecycle
node_developer -->|"creates display"| node_display
node_developer -->|"composes UI"| node_widgets
node_developer -->|"builds component"| node_component
node_developer -->|"updates state"| node_state
node_app_lifecycle -->|"handles timers"| node_lvgl
node_display -.->|"configures display"| node_lvgl
node_component -->|"uses references"| node_object_ref
node_widgets -->|"wraps objects"| node_object
node_widgets -->|"uses callbacks"| node_events
node_widgets -->|"uses styling"| node_styles
node_layout -->|"creates containers"| node_object
node_layout -->|"sets layout styles"| node_styles
node_state -->|"updates UI"| node_widgets
node_object_ref -->|"extends object view"| node_object
node_object_ref -->|"provides event API"| node_events
node_object_ref -->|"provides style API"| node_styles
node_object -->|"uses wrapper types"| node_wrapping
node_label -->|"uses text helpers"| node_strings
node_label -->|"creates LVGL object"| node_object
node_animation -->|"animates objects"| node_object
node_drawing -.->|"calls drawing APIs"| node_lvgl
node_input -.->|"dispatches input events"| node_events
node_font_loader -.->|"loads fonts"| node_lvgl
node_image -.->|"handles images"| node_lvgl
node_filesystem -.->|"wraps filesystem APIs"| node_lvgl
node_timer -.->|"wraps timer APIs"| node_lvgl
node_i18n -.->|"translates text"| node_label
node_fragments -->|"manages fragments"| node_lvgl
node_version -->|"detects version"| node_lvgl
node_color -.->|"sets style colors"| node_styles

click node_app_lifecycle "https://github.com/aptumfr/lv/blob/master/include/lv/core/app.hpp"
click node_display "https://github.com/aptumfr/lv/blob/master/include/lv/core/display.hpp"
click node_component "https://github.com/aptumfr/lv/blob/master/include/lv/core/component.hpp"
click node_widgets "https://github.com/aptumfr/lv/tree/master/include/lv/widgets"
click node_layout "https://github.com/aptumfr/lv/tree/master/include/lv/layout"
click node_state "https://github.com/aptumfr/lv/blob/master/include/lv/core/state.hpp"
click node_object "https://github.com/aptumfr/lv/blob/master/include/lv/core/object.hpp"
click node_object_ref "https://github.com/aptumfr/lv/blob/master/include/lv/core/objectref.hpp"
click node_events "https://github.com/aptumfr/lv/blob/master/include/lv/core/event.hpp"
click node_styles "https://github.com/aptumfr/lv/blob/master/include/lv/core/style.hpp"
click node_color "https://github.com/aptumfr/lv/blob/master/include/lv/core/color.hpp"
click node_version "https://github.com/aptumfr/lv/blob/master/include/lv/core/version.hpp"
click node_wrapping "https://github.com/aptumfr/lv/blob/master/include/lv/core/wrap.hpp"
click node_label "https://github.com/aptumfr/lv/blob/master/include/lv/widgets/label.hpp"
click node_drawing "https://github.com/aptumfr/lv/tree/master/include/lv/draw"
click node_animation "https://github.com/aptumfr/lv/blob/master/include/lv/core/anim.hpp"
click node_input "https://github.com/aptumfr/lv/blob/master/include/lv/core/indev.hpp"
click node_font_loader "https://github.com/aptumfr/lv/blob/master/include/lv/core/font_loader.hpp"
click node_image "https://github.com/aptumfr/lv/blob/master/include/lv/core/image.hpp"
click node_filesystem "https://github.com/aptumfr/lv/blob/master/include/lv/core/fs.hpp"
click node_strings "https://github.com/aptumfr/lv/blob/master/include/lv/core/string_utils.hpp"
click node_timer "https://github.com/aptumfr/lv/blob/master/include/lv/core/timer.hpp"
click node_i18n "https://github.com/aptumfr/lv/blob/master/include/lv/core/translation.hpp"
click node_fragments "https://github.com/aptumfr/lv/blob/master/include/lv/others/fragment.hpp"

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_app_lifecycle,node_display,node_component,node_widgets,node_layout,node_state,node_label toneBlue
class node_object,node_object_ref,node_events,node_styles,node_color,node_version,node_wrapping,node_strings toneAmber
class node_drawing,node_animation,node_input,node_font_loader,node_image,node_filesystem,node_timer toneMint
class node_i18n,node_fragments toneRose
class node_developer,node_lvgl toneIndigo
```

## Components

### Application UI

- [Lifecycle loop](https://github.com/aptumfr/lv/blob/master/include/lv/core/app.hpp): `include/lv/core/app.hpp`
- [Display setup](https://github.com/aptumfr/lv/blob/master/include/lv/core/display.hpp): `include/lv/core/display.hpp`
- [Components](https://github.com/aptumfr/lv/blob/master/include/lv/core/component.hpp): `include/lv/core/component.hpp`
- [Widgets](https://github.com/aptumfr/lv/tree/master/include/lv/widgets): `include/lv/widgets`
- [Layouts](https://github.com/aptumfr/lv/tree/master/include/lv/layout): `include/lv/layout`
- [Reactive state](https://github.com/aptumfr/lv/blob/master/include/lv/core/state.hpp): `include/lv/core/state.hpp`
- [Label widget](https://github.com/aptumfr/lv/blob/master/include/lv/widgets/label.hpp): `include/lv/widgets/label.hpp`

### Core wrappers

- [Object API](https://github.com/aptumfr/lv/blob/master/include/lv/core/object.hpp): `include/lv/core/object.hpp`
- [Object references](https://github.com/aptumfr/lv/blob/master/include/lv/core/objectref.hpp): `include/lv/core/objectref.hpp`
- [Typed events](https://github.com/aptumfr/lv/blob/master/include/lv/core/event.hpp): `include/lv/core/event.hpp`
- [Style API](https://github.com/aptumfr/lv/blob/master/include/lv/core/style.hpp): `include/lv/core/style.hpp`
- [Color utilities](https://github.com/aptumfr/lv/blob/master/include/lv/core/color.hpp): `include/lv/core/color.hpp`
- [Version support](https://github.com/aptumfr/lv/blob/master/include/lv/core/version.hpp): `include/lv/core/version.hpp`
- [C API interop](https://github.com/aptumfr/lv/blob/master/include/lv/core/wrap.hpp): `include/lv/core/wrap.hpp`
- [String utilities](https://github.com/aptumfr/lv/blob/master/include/lv/core/string_utils.hpp): `include/lv/core/string_utils.hpp`

### Presentation

- [Drawing APIs](https://github.com/aptumfr/lv/tree/master/include/lv/draw): `include/lv/draw`
- [Animation](https://github.com/aptumfr/lv/blob/master/include/lv/core/anim.hpp): `include/lv/core/anim.hpp`
- [Input devices](https://github.com/aptumfr/lv/blob/master/include/lv/core/indev.hpp): `include/lv/core/indev.hpp`
- [Font loading](https://github.com/aptumfr/lv/blob/master/include/lv/core/font_loader.hpp): `include/lv/core/font_loader.hpp`
- [Image support](https://github.com/aptumfr/lv/blob/master/include/lv/core/image.hpp): `include/lv/core/image.hpp`
- [Filesystem](https://github.com/aptumfr/lv/blob/master/include/lv/core/fs.hpp): `include/lv/core/fs.hpp`
- [Timers](https://github.com/aptumfr/lv/blob/master/include/lv/core/timer.hpp): `include/lv/core/timer.hpp`

### Runtime extensions

- [Internationalization](https://github.com/aptumfr/lv/blob/master/include/lv/core/translation.hpp): `include/lv/core/translation.hpp`
- [Fragment navigation](https://github.com/aptumfr/lv/blob/master/include/lv/others/fragment.hpp): `include/lv/others/fragment.hpp`

### Other components

- **Application code**
- **LVGL runtime**

## Connections

- Application code → Lifecycle loop: initializes and runs
- Application code → Display setup: creates display
- Application code → Widgets: composes UI
- Application code → Components: builds component
- Application code → Reactive state: updates state
- Lifecycle loop → LVGL runtime: handles timers (evidence: `include/lv/core/app.hpp`)
- Display setup → LVGL runtime: configures display
- Components → Object references: uses references (evidence: `include/lv/core/component.hpp`)
- Widgets → Object API: wraps objects (evidence: `include/lv/widgets/button.hpp`)
- Widgets → Typed events: uses callbacks (evidence: `include/lv/widgets/button.hpp`)
- Widgets → Style API: uses styling (evidence: `include/lv/widgets/button.hpp`)
- Layouts → Object API: creates containers (evidence: `include/lv/layout/flex.hpp`)
- Layouts → Style API: sets layout styles (evidence: `include/lv/layout/grid.hpp`)
- Reactive state → Widgets: updates UI
- Object references → Object API: extends object view (evidence: `include/lv/core/objectref.hpp`)
- Object references → Typed events: provides event API (evidence: `include/lv/core/objectref.hpp`)
- Object references → Style API: provides style API (evidence: `include/lv/core/objectref.hpp`)
- Object API → C API interop: uses wrapper types (evidence: `include/lv/core/object.hpp`)
- Label widget → String utilities: uses text helpers (evidence: `include/lv/widgets/label.hpp`)
- Label widget → Object API: creates LVGL object (evidence: `include/lv/widgets/label.hpp`)
- Animation → Object API: animates objects (evidence: `include/lv/core/anim.hpp`)
- Drawing APIs → LVGL runtime: calls drawing APIs
- Input devices → Typed events: dispatches input events
- Font loading → LVGL runtime: loads fonts
- Image support → LVGL runtime: handles images
- Filesystem → LVGL runtime: wraps filesystem APIs
- Timers → LVGL runtime: wraps timer APIs
- Internationalization → Label widget: translates text
- Fragment navigation → LVGL runtime: manages fragments (evidence: `include/lv/others/fragment.hpp`)
- Version support → LVGL runtime: detects version (evidence: `include/lv/core/version.hpp`)
- Color utilities → Style API: sets style colors
