# phenom64/openxmb architecture

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

- Interactive diagram: https://gitdiagram.com/phenom64/openxmb
- Repository: https://github.com/phenom64/openxmb

## Overview

1. **What this repository is**
   OpenXMB is a C++23 desktop UI shell that reimagines the PlayStation-style XMB. The runtime is not a general-purpose app framework; it is a single interactive front-end that coordinates menus, overlays, media viewers, and optional modules inside one Vulkan-rendered interface.

2. **Top-level execution path**
   `src/main.cpp` is the entry point. Startup flows into the application/shell layer (`src/app/shell.cpp`, `src/app/module.cppm`), which initializes configuration, localization, rendering, and input, then hands control to the main navigation loop.

3. **Core platform boundary**
   SDL2 is the platform-facing layer for window creation, input, and likely audio/event plumbing. Vulkan is the graphics API. The actual renderer is delegated to **AuroreEngine** (built on dreamrender), so OpenXMB sits above the engine rather than managing raw Vulkan frame logic everywhere.

4. **Rendering architecture**
   Rendering is split into a dedicated `src/render` subtree. It contains shader management plus render components for the XMB look and effects: wave background, original-style renderer, and particle variants. Shader sources live in `shaders/`, including compute passes for blur/downsample/upsample and YUV decoding, which indicates a GPU-heavy pipeline with postprocessing and media decode support.

5. **UI composition model**
   The visible interface is built from reusable components in `src/app/components` and layered effects in `src/app/layers`. Examples include startup, progress, message, and choice overlays, plus a blur layer. This suggests a composited UI model where the shell is always present and transient overlays are stacked above the main navigation state.

6. **Navigation and menu subsystem**
   The menu tree lives under `src/menu/` and is divided into domain-specific menus: applications, files, settings, and users. This is the main user-navigation boundary. The menus likely feed content into the shell rather than owning rendering themselves, keeping content selection separate from presentation.

7. **Programs / content viewers**
   `src/programs/` contains built-in viewers for images, text, and video. These are treated as sub-apps opened from the shell rather than independent executables. The video path is notable because the README says it uses FFmpeg plus GPU-accelerated YUV decoding, so media decoding is a distinct pipeline from normal menu rendering.

8. **Optional feature modules**
   `src/modules/` holds optional alpha integrations: browser, disc media, and libretro. These are feature boundaries that can be compiled out. Architecturally, they extend the shell with specialized content sources without changing the core navigation or renderer.

9. **Config, constants, and utilities**
   Runtime behavior is driven by `config.json` through `src/config.*`, with shared constants and helpers in `src/constants.cppm` and `src/utils.*`. Config affects visual theme, font choices, date/time display, controller behavior, and render quality. The runtime resolves config from environment and app-local/user locations, so deployment layout matters.

10. **Assets and localization**
   The repository includes packaged asset trees under `interfaceFX/` for graphics, audio, and typefaces, plus gettext catalogs in `po/`. The launcher/build scripts set asset and locale directories at runtime, so the app expects a structured install layout rather than baking everything into code only.

11. **Build and packaging topology**
   This repo is organized as a CMake/Ninja project with C++ modules and resource embedding (`resources.qrc`, embedded shader/resource paths). The build is designed to run across Linux/SynOS, macOS with MoltenVK, and Windows via vcpkg/LLVM. CI and smoke scripts validate not just compilation but staged install layout, launcher startup, and presence of key assets.

12. **External dependency boundaries**
   The important external boundaries are: SDL2 for platform I/O, Vulkan/MoltenVK for graphics, AuroreEngine/dreamrender for rendering infrastructure, FFmpeg for video, gettext for localization, and optionally CEF/libretro/disc tooling for alpha features. OpenXMB is essentially the orchestration layer that ties these services into a single XMB-style shell.

Main entry points: [`src/app/shell.cpp`](https://github.com/phenom64/openxmb/blob/master/src/app/shell.cpp) (Shell), [`src/app/components/main_menu.cpp`](https://github.com/phenom64/openxmb/blob/master/src/app/components/main_menu.cpp) (Main Menu), [`src/render/module.cppm`](https://github.com/phenom64/openxmb/blob/master/src/render/module.cppm) (Render Module), [`src/menu/base.cppm`](https://github.com/phenom64/openxmb/blob/master/src/menu/base.cppm) (Menus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.cpp]"]
  node_shell["Shell<br/>orchestrator<br/>[shell.cpp]"]
  node_app_module["App Module<br/>module interface<br/>[module.cppm]"]
  node_config["Config<br/>[config.cpp]"]
  node_constants["Constants<br/>shared definitions<br/>[constants.cppm]"]
end

subgraph group_ui["UI Shell"]
  node_app_components["Overlays<br/>ui components<br/>[main_menu.cpp]"]
  node_startup_overlay["Startup<br/>overlay"]
  node_progress_overlay["Progress<br/>overlay"]
  node_message_overlay["Message<br/>overlay"]
  node_choice_overlay["Choice<br/>overlay<br/>[choice_overlay.cpp]"]
  node_blur_layer["Blur Layer<br/>visual layer<br/>[blur_layer.cpp]"]
  node_main_menu["Main Menu<br/>navigation UI<br/>[main_menu.cpp]"]
  node_menu_system["Menus<br/>navigation<br/>[base.cppm]"]
  node_applications_menu["Apps Menu"]
  node_files_menu["Files Menu<br/>[files_menu.cpp]"]
  node_settings_menu["Settings<br/>menu<br/>[settings_menu.cpp]"]
  node_users_menu["Users<br/>menu<br/>[users_menu.cpp]"]
end

subgraph group_content["Content"]
  node_programs["Programs<br/>content hub<br/>[programs.cpp]"]
  node_image_viewer["Image Viewer<br/>[image_viewer.cppm]"]
  node_text_viewer["Text Viewer<br/>[text_viewer.cppm]"]
  node_video_player["Video Player<br/>viewer<br/>[video_player.cppm]"]
  node_modules["Optional Modules<br/>feature extensions<br/>[browser.cppm]"]
  node_browser_module["Browser<br/>optional module<br/>[browser.cppm]"]
  node_disc_module["Disc Media<br/>optional module<br/>[disc.cppm]"]
  node_libretro_module["Libretro<br/>optional module<br/>[libretro.cppm]"]
end

subgraph group_rendering["Rendering"]
  node_render_module["Render Module<br/>render orchestrator<br/>[module.cppm]"]
  node_shaders["Shaders<br/>gpu pipeline<br/>[shaders.cpp]"]
  node_wave_renderer["Wave Renderer<br/>[wave_renderer.cppm]"]
  node_original_renderer["Original Renderer"]
  node_particles["Particles<br/>effect renderer"]
end

subgraph group_support["Support"]
  node_assets[("Assets<br/>packaged resources")]
  node_localization["Localization<br/>gettext catalogs<br/>[en.po]"]
  node_qml_ui["QML UI<br/>ui frontend<br/>[main.qml]"]
  node_build_system["Build<br/>cmake packaging<br/>[CMakeLists.txt]"]
end

node_main -->|"starts"| node_shell
node_shell -->|"loads"| node_config
node_shell -->|"initializes"| node_app_module
node_shell -->|"binds"| node_render_module
node_shell -->|"drives"| node_menu_system
node_shell -->|"opens"| node_programs
node_shell -.->|"extends"| node_modules
node_app_module -->|"composes"| node_main_menu
node_main_menu -->|"layers"| node_startup_overlay
node_main_menu -->|"layers"| node_progress_overlay
node_main_menu -->|"layers"| node_message_overlay
node_main_menu -->|"layers"| node_choice_overlay
node_main_menu -->|"effects"| node_blur_layer
node_menu_system -->|"includes"| node_applications_menu
node_menu_system -->|"includes"| node_files_menu
node_menu_system -->|"includes"| node_settings_menu
node_menu_system -->|"includes"| node_users_menu
node_programs -->|"contains"| node_image_viewer
node_programs -->|"contains"| node_text_viewer
node_programs -->|"contains"| node_video_player
node_modules -->|"contains"| node_browser_module
node_modules -->|"contains"| node_disc_module
node_modules -->|"contains"| node_libretro_module
node_render_module -->|"manages"| node_shaders
node_render_module -->|"routes"| node_wave_renderer
node_render_module -->|"routes"| node_original_renderer
node_render_module -->|"routes"| node_particles
node_video_player -->|"uses"| node_shaders
node_shell -->|"uses"| node_assets
node_shell -->|"uses"| node_localization
node_build_system -->|"builds"| node_render_module
node_build_system -->|"packages"| node_qml_ui

click node_main "https://github.com/phenom64/openxmb/blob/master/src/main.cpp"
click node_shell "https://github.com/phenom64/openxmb/blob/master/src/app/shell.cpp"
click node_app_module "https://github.com/phenom64/openxmb/blob/master/src/app/module.cppm"
click node_config "https://github.com/phenom64/openxmb/blob/master/src/config.cpp"
click node_constants "https://github.com/phenom64/openxmb/blob/master/src/constants.cppm"
click node_app_components "https://github.com/phenom64/openxmb/blob/master/src/app/components/main_menu.cpp"
click node_startup_overlay "https://github.com/phenom64/openxmb/blob/master/src/app/components/startup_overlay.cpp"
click node_progress_overlay "https://github.com/phenom64/openxmb/blob/master/src/app/components/progress_overlay.cpp"
click node_message_overlay "https://github.com/phenom64/openxmb/blob/master/src/app/components/message_overlay.cpp"
click node_choice_overlay "https://github.com/phenom64/openxmb/blob/master/src/app/components/choice_overlay.cpp"
click node_blur_layer "https://github.com/phenom64/openxmb/blob/master/src/app/layers/blur_layer.cpp"
click node_main_menu "https://github.com/phenom64/openxmb/blob/master/src/app/components/main_menu.cpp"
click node_menu_system "https://github.com/phenom64/openxmb/blob/master/src/menu/base.cppm"
click node_applications_menu "https://github.com/phenom64/openxmb/blob/master/src/menu/applications_menu.cpp"
click node_files_menu "https://github.com/phenom64/openxmb/blob/master/src/menu/files_menu.cpp"
click node_settings_menu "https://github.com/phenom64/openxmb/blob/master/src/menu/settings_menu.cpp"
click node_users_menu "https://github.com/phenom64/openxmb/blob/master/src/menu/users_menu.cpp"
click node_programs "https://github.com/phenom64/openxmb/blob/master/src/programs.cpp"
click node_image_viewer "https://github.com/phenom64/openxmb/blob/master/src/programs/image_viewer.cppm"
click node_text_viewer "https://github.com/phenom64/openxmb/blob/master/src/programs/text_viewer.cppm"
click node_video_player "https://github.com/phenom64/openxmb/blob/master/src/programs/video_player.cppm"
click node_modules "https://github.com/phenom64/openxmb/blob/master/src/modules/browser.cppm"
click node_browser_module "https://github.com/phenom64/openxmb/blob/master/src/modules/browser.cppm"
click node_disc_module "https://github.com/phenom64/openxmb/blob/master/src/modules/disc.cppm"
click node_libretro_module "https://github.com/phenom64/openxmb/blob/master/src/modules/libretro.cppm"
click node_render_module "https://github.com/phenom64/openxmb/blob/master/src/render/module.cppm"
click node_shaders "https://github.com/phenom64/openxmb/blob/master/src/render/shaders.cpp"
click node_wave_renderer "https://github.com/phenom64/openxmb/blob/master/src/render/components/wave_renderer.cppm"
click node_original_renderer "https://github.com/phenom64/openxmb/blob/master/src/render/components/original_renderer.cppm"
click node_particles "https://github.com/phenom64/openxmb/blob/master/src/render/components/original_particles.cppm"
click node_assets "https://github.com/phenom64/openxmb/tree/master/interfaceFX/GraphicsServer/HomeMenu"
click node_localization "https://github.com/phenom64/openxmb/blob/master/po/en.po"
click node_qml_ui "https://github.com/phenom64/openxmb/blob/master/qml/main.qml"
click node_build_system "https://github.com/phenom64/openxmb/blob/master/CMakeLists.txt"

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_shell,node_app_module,node_config,node_constants toneBlue
class node_app_components,node_startup_overlay,node_progress_overlay,node_message_overlay,node_choice_overlay,node_blur_layer,node_main_menu,node_menu_system,node_applications_menu,node_files_menu,node_settings_menu,node_users_menu toneAmber
class node_programs,node_image_viewer,node_text_viewer,node_video_player,node_modules,node_browser_module,node_disc_module,node_libretro_module toneMint
class node_render_module,node_shaders,node_wave_renderer,node_original_renderer,node_particles toneRose
class node_assets,node_localization,node_qml_ui,node_build_system toneIndigo
```

## Components

### Runtime

Entry, shell, config, and app coordination

- [Main](https://github.com/phenom64/openxmb/blob/master/src/main.cpp): entrypoint · Program entry and startup handoff · `src/main.cpp`
- [Shell](https://github.com/phenom64/openxmb/blob/master/src/app/shell.cpp): orchestrator · Initializes and runs the interactive XMB shell · `src/app/shell.cpp`
- [App Module](https://github.com/phenom64/openxmb/blob/master/src/app/module.cppm): module interface · Top-level app module boundary · `src/app/module.cppm`
- [Config](https://github.com/phenom64/openxmb/blob/master/src/config.cpp): runtime config · Loads user and environment-driven settings · `src/config.cpp`
- [Constants](https://github.com/phenom64/openxmb/blob/master/src/constants.cppm): shared definitions · Common compile-time/runtime constants · `src/constants.cppm`

### UI Shell

Composable overlays and menu navigation

- [Overlays](https://github.com/phenom64/openxmb/blob/master/src/app/components/main_menu.cpp): ui components · Reusable transient UI components · `src/app/components/main_menu.cpp`
- [Startup](https://github.com/phenom64/openxmb/blob/master/src/app/components/startup_overlay.cpp): overlay · Boot and startup status layer · `src/app/components/startup_overlay.cpp`
- [Progress](https://github.com/phenom64/openxmb/blob/master/src/app/components/progress_overlay.cpp): overlay · Progress feedback layer · `src/app/components/progress_overlay.cpp`
- [Message](https://github.com/phenom64/openxmb/blob/master/src/app/components/message_overlay.cpp): overlay · Status and error message layer · `src/app/components/message_overlay.cpp`
- [Choice](https://github.com/phenom64/openxmb/blob/master/src/app/components/choice_overlay.cpp): overlay · User choice and confirmation layer · `src/app/components/choice_overlay.cpp`
- [Blur Layer](https://github.com/phenom64/openxmb/blob/master/src/app/layers/blur_layer.cpp): visual layer · Backdrop blur compositing layer · `src/app/layers/blur_layer.cpp`
- [Main Menu](https://github.com/phenom64/openxmb/blob/master/src/app/components/main_menu.cpp): navigation UI · Primary shell menu composition · `src/app/components/main_menu.cpp`
- [Menus](https://github.com/phenom64/openxmb/blob/master/src/menu/base.cppm): navigation · Domain menus for shell navigation · `src/menu/base.cppm`
- [Apps Menu](https://github.com/phenom64/openxmb/blob/master/src/menu/applications_menu.cpp): menu · Application launcher navigation · `src/menu/applications_menu.cpp`
- [Files Menu](https://github.com/phenom64/openxmb/blob/master/src/menu/files_menu.cpp): menu · File browsing navigation · `src/menu/files_menu.cpp`
- [Settings](https://github.com/phenom64/openxmb/blob/master/src/menu/settings_menu.cpp): menu · Settings navigation and options · `src/menu/settings_menu.cpp`
- [Users](https://github.com/phenom64/openxmb/blob/master/src/menu/users_menu.cpp): menu · User/profile navigation · `src/menu/users_menu.cpp`

### Content

Built-in viewers and optional feature modules

- [Programs](https://github.com/phenom64/openxmb/blob/master/src/programs.cpp): content hub · Built-in viewers opened from the shell · `src/programs.cpp`
- [Image Viewer](https://github.com/phenom64/openxmb/blob/master/src/programs/image_viewer.cppm): viewer · Image viewing sub-app · `src/programs/image_viewer.cppm`
- [Text Viewer](https://github.com/phenom64/openxmb/blob/master/src/programs/text_viewer.cppm): viewer · Text viewing sub-app · `src/programs/text_viewer.cppm`
- [Video Player](https://github.com/phenom64/openxmb/blob/master/src/programs/video_player.cppm): viewer · Video playback pipeline and sub-app · `src/programs/video_player.cppm`
- [Optional Modules](https://github.com/phenom64/openxmb/blob/master/src/modules/browser.cppm): feature extensions · Compile-time optional integrations · `src/modules/browser.cppm`
- [Browser](https://github.com/phenom64/openxmb/blob/master/src/modules/browser.cppm): optional module · Browser integration boundary · `src/modules/browser.cppm`
- [Disc Media](https://github.com/phenom64/openxmb/blob/master/src/modules/disc.cppm): optional module · Disc/media integration boundary · `src/modules/disc.cppm`
- [Libretro](https://github.com/phenom64/openxmb/blob/master/src/modules/libretro.cppm): optional module · Retro content integration boundary · `src/modules/libretro.cppm`

### Rendering

GPU rendering, shader management, and visual effects

- [Render Module](https://github.com/phenom64/openxmb/blob/master/src/render/module.cppm): render orchestrator · Connects shell UI to the rendering subsystem · `src/render/module.cppm`
- [Shaders](https://github.com/phenom64/openxmb/blob/master/src/render/shaders.cpp): gpu pipeline · Shader loading and shader pipeline management · `src/render/shaders.cpp`
- [Wave Renderer](https://github.com/phenom64/openxmb/blob/master/src/render/components/wave_renderer.cppm): renderer · XMB wave background renderer · `src/render/components/wave_renderer.cppm`
- [Original Renderer](https://github.com/phenom64/openxmb/blob/master/src/render/components/original_renderer.cppm): renderer · Original-style XMB renderer · `src/render/components/original_renderer.cppm`
- [Particles](https://github.com/phenom64/openxmb/blob/master/src/render/components/original_particles.cppm): effect renderer · Particle effect variant renderer · `src/render/components/original_particles.cppm`

### Support

Assets, localization, build, and external integration boundaries

- [Assets](https://github.com/phenom64/openxmb/tree/master/interfaceFX/GraphicsServer/HomeMenu): packaged resources · Packaged graphics, audio, and typefaces · `interfaceFX/GraphicsServer/HomeMenu`
- [Localization](https://github.com/phenom64/openxmb/blob/master/po/en.po): gettext catalogs · Translated message catalogs · `po/en.po`
- [QML UI](https://github.com/phenom64/openxmb/blob/master/qml/main.qml): ui frontend · Supplementary QML frontend entrypoint · `qml/main.qml`
- [Build](https://github.com/phenom64/openxmb/blob/master/CMakeLists.txt): cmake packaging · CMake build, presets, and install layout · `CMakeLists.txt`

## Connections

- Main → Shell: starts · Program entry hands off to shell startup
- Shell → Config: loads · Shell initializes runtime configuration
- Shell → App Module: initializes · Shell enters the application module boundary
- Shell → Render Module: binds · Shell connects UI state to renderer
- Shell → Menus: drives · Shell owns the main navigation loop
- Shell → Programs: opens · Shell launches built-in viewers
- Shell → Optional Modules: extends · Optional integrations are attached through modules
- App Module → Main Menu: composes · Application module composes the visible shell UI
- Main Menu → Startup: layers · Startup overlay appears above the main shell
- Main Menu → Progress: layers · Progress overlay appears during loading
- Main Menu → Message: layers · Message overlay provides status and errors
- Main Menu → Choice: layers · Choice overlay handles confirmations
- Main Menu → Blur Layer: effects · Blur layer provides background compositing
- Menus → Apps Menu: includes · Menu tree includes application navigation
- Menus → Files Menu: includes · Menu tree includes file browsing
- Menus → Settings: includes · Menu tree includes settings navigation
- Menus → Users: includes · Menu tree includes user navigation
- Programs → Image Viewer: contains · Built-in image viewer sub-app
- Programs → Text Viewer: contains · Built-in text viewer sub-app
- Programs → Video Player: contains · Built-in video player sub-app
- Optional Modules → Browser: contains · Optional browser integration
- Optional Modules → Disc Media: contains · Optional disc-media integration
- Optional Modules → Libretro: contains · Optional libretro integration
- Render Module → Shaders: manages · Renderer module manages shader pipeline assets
- Render Module → Wave Renderer: routes · Wave background renderer is selected through render module
- Render Module → Original Renderer: routes · Original XMB renderer is selected through render module
- Render Module → Particles: routes · Particle variant is part of the visual effect set
- Video Player → Shaders: uses · Video playback depends on GPU decode shaders
- Shell → Assets: uses · Shell consumes packaged interface assets
- Shell → Localization: uses · Shell loads translated text resources
- Build → Render Module: builds · Build system assembles the render subsystem
- Build → QML UI: packages · Build includes auxiliary QML UI resources
