# adhnan23/openemux architecture

> Architecture diagram of the GitHub repository adhnan23/openemux, 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/adhnan23/openemux
- Repository: https://github.com/adhnan23/openemux

## Overview

OpenEmux is a Linux-native GTK frontend for RetroArch. Users set up the app, import or scan their own ROMs, browse and organize the library with artwork, then launch a game through RetroArch; settings cover BIOS, input, and shaders. The graph also preserves startup provisioning and runtime support. Several subsystems are represented by their exact source directory because their individual implementation files were not sampled; those links rely on README statements where noted.

Main entry points: [`src/openemux/ui/window.py`](https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/window.py) (Library window), [`src/openemux/ui/preferences.py`](https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/preferences.py) (Preferences), [`src/openemux/core/runtime_manager.py`](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/runtime_manager.py) (Game runtime), [`src/openemux/app.py`](https://github.com/adhnan23/openemux/blob/develop/src/openemux/app.py) (GTK application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup &amp; setup"]
  node_entry["Application entry<br/>[main.py]"]
  node_application["GTK application<br/>[app.py]"]
  node_bootstrap["First-boot setup<br/>[first_boot.py]"]
  node_core_setup["Core provisioning"]
end

subgraph group_library["Game library"]
  node_window["Library window<br/>[window.py]"]
  node_import_flow["ROM import<br/>[import_flow.py]"]
  node_scanner["Library scanning<br/>[scanner.py]"]
  node_systems["Console catalog<br/>[systems.py]"]
  node_playlist["Collections &amp; playlists"]
  node_grid["ROM grid<br/>[grid.py]"]
end

subgraph group_artwork["Artwork"]
  node_art_manager["Artwork editor<br/>[artwork_manager.py]"]
  node_art_search["Artwork search<br/>[artwork_search.py]"]
  node_cover_sync["Cover sync<br/>[cover_sync.py]"]
  node_scraper["Local artwork lookup<br/>[scraper.py]"]
end

subgraph group_settings["Settings"]
  node_config["Configuration<br/>[config.py]"]
  node_preferences["Preferences<br/>[preferences.py]"]
  node_bios["BIOS status<br/>[bios_manager.py]"]
  node_input_settings["Input &amp; shaders"]
end

subgraph group_play["Gameplay"]
  node_runtime["Game runtime<br/>[runtime_manager.py]"]
  node_launcher["RetroArch launcher"]
  node_command["RetroArch commands"]
  node_states["Save states<br/>[save_states.py]"]
  node_game_window["Game window<br/>[game_window.py]"]
end

node_user(("Player"))
node_retroarch["RetroArch"]

node_user -->|"starts"| node_entry
node_entry -->|"builds"| node_application
node_application -->|"initializes"| node_config
node_application -->|"runs setup"| node_bootstrap
node_bootstrap -->|"provisions cores"| node_core_setup
node_application -->|"opens"| node_window
node_user -->|"adds ROMs"| node_import_flow
node_window -->|"scans library"| node_scanner
node_scanner -->|"resolves consoles"| node_systems
node_window -->|"manages lists"| node_playlist
node_window -->|"displays library"| node_grid
node_grid -->|"loads artwork"| node_scraper
node_user -->|"edits artwork"| node_art_manager
node_art_manager -->|"searches providers"| node_art_search
node_art_manager -->|"saves local art"| node_scraper
node_window -->|"syncs covers"| node_cover_sync
node_user -->|"configures"| node_preferences
node_preferences -->|"updates settings"| node_config
node_preferences -->|"checks BIOS"| node_bios
node_preferences -->|"sets controls"| node_input_settings
node_preferences -->|"sets shaders"| node_input_settings
node_user -->|"launches game"| node_runtime
node_window -->|"starts session"| node_runtime
node_runtime -->|"starts process"| node_launcher
node_launcher -->|"launches"| node_retroarch
node_runtime -->|"sends commands"| node_command
node_runtime -->|"manages states"| node_states
node_window -->|"presents gameplay"| node_game_window

click node_entry "https://github.com/adhnan23/openemux/blob/develop/src/openemux/main.py"
click node_application "https://github.com/adhnan23/openemux/blob/develop/src/openemux/app.py"
click node_bootstrap "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/first_boot.py"
click node_core_setup "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/retroarch_buildbot_updater.py"
click node_config "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/config.py"
click node_window "https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/window.py"
click node_import_flow "https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/import_flow.py"
click node_scanner "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/scanner.py"
click node_systems "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/systems.py"
click node_playlist "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/playlist_manager.py"
click node_grid "https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/grid.py"
click node_art_manager "https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/artwork_manager.py"
click node_art_search "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/artwork_search.py"
click node_cover_sync "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/cover_sync.py"
click node_scraper "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/scraper.py"
click node_preferences "https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/preferences.py"
click node_bios "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/bios_manager.py"
click node_input_settings "https://github.com/adhnan23/openemux/tree/develop/src/openemux/core"
click node_runtime "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/runtime_manager.py"
click node_launcher "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/retroarch_launcher.py"
click node_command "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/retroarch_command.py"
click node_states "https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/save_states.py"
click node_game_window "https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/game_window.py"

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_entry,node_application,node_bootstrap,node_core_setup toneBlue
class node_window,node_import_flow,node_scanner,node_systems,node_playlist,node_grid toneAmber
class node_art_manager,node_art_search,node_cover_sync,node_scraper toneMint
class node_config,node_preferences,node_bios,node_input_settings toneRose
class node_runtime,node_launcher,node_command,node_states,node_game_window,node_user,node_retroarch toneIndigo
```

## Components

### Startup & setup

- [Application entry](https://github.com/adhnan23/openemux/blob/develop/src/openemux/main.py): `src/openemux/main.py`
- [GTK application](https://github.com/adhnan23/openemux/blob/develop/src/openemux/app.py): `src/openemux/app.py`
- [First-boot setup](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/first_boot.py): `src/openemux/core/first_boot.py`
- [Core provisioning](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/retroarch_buildbot_updater.py): `src/openemux/core/retroarch_buildbot_updater.py`

### Game library

- [Library window](https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/window.py): `src/openemux/ui/window.py`
- [ROM import](https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/import_flow.py): `src/openemux/ui/import_flow.py`
- [Library scanning](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/scanner.py): `src/openemux/core/scanner.py`
- [Console catalog](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/systems.py): `src/openemux/core/systems.py`
- [Collections & playlists](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/playlist_manager.py): `src/openemux/core/playlist_manager.py`
- [ROM grid](https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/grid.py): `src/openemux/ui/grid.py`

### Artwork

- [Artwork editor](https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/artwork_manager.py): `src/openemux/ui/artwork_manager.py`
- [Artwork search](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/artwork_search.py): `src/openemux/core/artwork_search.py`
- [Cover sync](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/cover_sync.py): `src/openemux/core/cover_sync.py`
- [Local artwork lookup](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/scraper.py): `src/openemux/core/scraper.py`

### Settings

- [Configuration](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/config.py): `src/openemux/core/config.py`
- [Preferences](https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/preferences.py): `src/openemux/ui/preferences.py`
- [BIOS status](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/bios_manager.py): `src/openemux/core/bios_manager.py`
- [Input & shaders](https://github.com/adhnan23/openemux/tree/develop/src/openemux/core): `src/openemux/core`

### Gameplay

- [Game runtime](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/runtime_manager.py): `src/openemux/core/runtime_manager.py`
- [RetroArch launcher](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/retroarch_launcher.py): `src/openemux/core/retroarch_launcher.py`
- [RetroArch commands](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/retroarch_command.py): `src/openemux/core/retroarch_command.py`
- [Save states](https://github.com/adhnan23/openemux/blob/develop/src/openemux/core/save_states.py): `src/openemux/core/save_states.py`
- [Game window](https://github.com/adhnan23/openemux/blob/develop/src/openemux/ui/game_window.py): `src/openemux/ui/game_window.py`

### Other components

- **Player**
- **RetroArch**

## Connections

- Player → Application entry: starts (evidence: `README.md`)
- Application entry → GTK application: builds (evidence: `src/openemux/main.py`)
- GTK application → Configuration: initializes (evidence: `src/openemux/app.py`)
- GTK application → First-boot setup: runs setup (evidence: `src/openemux/app.py`)
- First-boot setup → Core provisioning: provisions cores (evidence: `README.md`)
- GTK application → Library window: opens (evidence: `src/openemux/app.py`)
- Player → ROM import: adds ROMs (evidence: `README.md`)
- Library window → Library scanning: scans library (evidence: `src/openemux/ui/window.py`)
- Library scanning → Console catalog: resolves consoles
- Library window → Collections & playlists: manages lists (evidence: `src/openemux/ui/window.py`)
- Library window → ROM grid: displays library (evidence: `src/openemux/ui/window.py`)
- ROM grid → Local artwork lookup: loads artwork (evidence: `src/openemux/ui/grid.py`)
- Player → Artwork editor: edits artwork (evidence: `README.md`)
- Artwork editor → Artwork search: searches providers (evidence: `src/openemux/ui/artwork_manager.py`)
- Artwork editor → Local artwork lookup: saves local art (evidence: `src/openemux/core/scraper.py`)
- Library window → Cover sync: syncs covers (evidence: `src/openemux/ui/window.py`)
- Player → Preferences: configures (evidence: `README.md`)
- Preferences → Configuration: updates settings (evidence: `src/openemux/ui/window.py`)
- Preferences → BIOS status: checks BIOS (evidence: `src/openemux/ui/window.py`)
- Preferences → Input & shaders: sets controls (evidence: `README.md`)
- Preferences → Input & shaders: sets shaders (evidence: `README.md`)
- Player → Game runtime: launches game (evidence: `README.md`)
- Library window → Game runtime: starts session (evidence: `src/openemux/ui/window.py`)
- Game runtime → RetroArch launcher: starts process (evidence: `src/openemux/core/runtime_manager.py`)
- RetroArch launcher → RetroArch: launches (evidence: `README.md`)
- Game runtime → RetroArch commands: sends commands (evidence: `src/openemux/core/runtime_manager.py`)
- Game runtime → Save states: manages states (evidence: `src/openemux/core/runtime_manager.py`)
- Library window → Game window: presents gameplay (evidence: `src/openemux/ui/window.py`)
