# werwolv/imhex architecture

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

- Interactive diagram: https://gitdiagram.com/werwolv/imhex
- Repository: https://github.com/werwolv/imhex

## Overview

1. **What this repo builds**
   - ImHex is a cross-platform hex editor with a plugin-based architecture.
   - The primary deliverable is the desktop GUI app; there is also a WebAssembly/browser build under `dist/web`, plus packaging targets for Windows, Linux, macOS, Flatpak, Snap, AppImage, etc.

2. **Top-level runtime split**
   - `main/gui` is the user-facing application process.
   - `main/updater` is a separate updater executable.
   - `main/forwarder` is a small helper/entry process used to launch or forward into the main app in some environments.
   - Most shared behavior lives in `lib/libimhex`, which is the core SDK/runtime used by the app and plugins.

3. **Core application foundation: `lib/libimhex`**
   - This is the central architecture layer: managers, registries, event bus, plugin manager, task manager, workspace/layout/theme/localization managers, shortcut handling, and project file management.
   - It also defines the stable plugin-facing API under `hex/api`, so plugins do not talk directly to the GUI internals.
   - The library includes provider abstractions, undo/redo, data processor graph primitives, helpers, and MCP client/server support.

4. **Plugin system as the main extension boundary**
   - Plugins are first-class modules in `plugins/*`, each with its own CMake target and often its own bundled resources in `romfs`.
   - Plugins register content through the core content registry: views, tools, providers, formatters, disassemblers, data processors, settings, and commands.
   - This is the key architecture boundary: core app + `libimhex` provide services, plugins contribute features.

5. **Built-in plugin is the feature backbone**
   - `plugins/builtin` contains most default user functionality: hex editor behavior, file handlers, recent files, settings, tutorials, reports, popups, command palette actions, and core views.
   - It also registers the default data processors, pattern-language integration, import/export formats, themes, workspaces, and out-of-box experience.
   - In practice, many visible app features are not in the GUI executable itself but are registered by this plugin at startup.

6. **Data model and data-source pipeline**
   - The app centers on a `Provider` abstraction: files, raw disks, process memory, GDB, UDP, Base64, Intel HEX/SREC, SSH/SFTP, and other sources are all exposed through provider implementations.
   - Views like the hex editor, data inspector, bookmarks, search, patches, and pattern parser read through the active provider rather than directly from files.
   - Undo/redo and patching operate on provider-backed data, so modifications flow through the provider layer instead of being hardwired to a single storage type.

7. **Pattern Language and data processor graph**
   - Pattern Language is the custom C-like parser/descriptor system used to interpret file structure and generate highlights, types, and visualizations.
   - The node-based data processor is a preprocessing pipeline that can transform, decrypt, or decode data before it reaches the editor/visualizers.
   - These two subsystems are central to analysis: one describes structure, the other can transform input data.

8. **Feature plugins are mostly self-contained modules**
   - `plugins/diffing`, `disassembler`, `hashes`, `remote`, `script_loader`, `ui`, `visualizers`, `windows`, `yara_rules`, `decompress`, and `fonts` each add a coherent feature set.
   - Examples of external integrations that materially shape architecture:
     - Capstone for disassembly
     - YARA for signature scanning
     - SSH/SFTP for remote file access
     - .NET scripting loader for plugin scripting
     - ImGui/ImPlot/ImNodes for UI, plotting, and node graphs
   - These plugins generally register their own views and helpers, but still rely on the same provider/content-registry core.

9. **UI and rendering stack**
   - The GUI is built on Dear ImGui with OpenGL rendering and GLFW-style platform integration.
   - `plugins/ui` provides shared UI widgets and editors used by many plugins, while `plugins/fonts` manages bundled font assets and font selection.
   - Platform-specific window/messaging code lives under `main/gui/source/window/platform/*` and `main/gui/source/messaging/*` for Windows, macOS, Linux, and Web.

10. **Startup and platform glue**
   - `main/gui` handles application startup, splash screen, crash handling, window creation, and per-platform messaging.
   - It branches into CLI/desktop/web startup paths under `main/gui/source/init/run/*`, which is where environment-specific launch logic is separated.
   - This layer is the bridge between the OS and the plugin-driven core runtime.

11. **Resources and bundled content**
   - `romfs` directories throughout the repo contain embedded runtime assets: themes, layouts, icons, localization JSON, shaders, splash assets, templates, and default workspaces.
   - `resources/` contains packaging assets such as Windows installer resources, macOS app metadata, and logo artwork.
   - The app depends heavily on these embedded resources for first-run experience, theming, and plugin-provided UI/content.

12. **Build, packaging, and dependency structure**
   - The repository is organized around CMake with many helper modules and third-party libraries vendored under `lib/third_party`.
   - This layout is important architecturally because the project is meant to be built into multiple binaries and packaging formats from the same source tree.
   - `dist/` contains release engineering, distro packaging, dependency bootstrap scripts, and web build assets.

13. **Tests and verification**
   - `tests/` covers common helpers, algorithms, plugin behavior, and language-related checks.
   - Tests are split by concern rather than by app layer, which matches the repo’s modular design: core helpers, algorithms, and plugin integration are validated separately.

14. **Diagram-friendly mental model**
   - The cleanest architecture diagram is: OS/web entrypoints → GUI bootstrap → core `libimhex` services → content registry/plugin manager → plugins → providers/views/data processors.
   - Data flows from providers into the hex editor, pattern language, inspector, diffing, disassembler, hashing, and visualizer features; user actions flow back through events, undo/redo, and task managers.

Main entry points: [`lib/libimhex`](https://github.com/werwolv/imhex/tree/master/lib/libimhex) (libimhex), [`plugins/builtin`](https://github.com/werwolv/imhex/tree/master/plugins/builtin) (Builtin plugin), [`lib/libimhex/include/hex/api/content_registry`](https://github.com/werwolv/imhex/tree/master/lib/libimhex/include/hex/api/content_registry) (Registry), [`plugins`](https://github.com/werwolv/imhex/tree/master/plugins) (Feature plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entrypoints"]
  node_main_gui["GUI app<br/>desktop runtime"]
  node_main_updater["Updater<br/>helper exe"]
  node_main_forwarder["Forwarder<br/>launcher helper"]
end

subgraph group_core["Core runtime"]
  node_libimhex["libimhex<br/>core SDK"]
  node_content_registry["Registry<br/>extension API"]
  node_event_manager(("Events<br/>event bus<br/>[event_manager.hpp]"))
  node_plugin_manager["Plugins core<br/>plugin host<br/>[plugin_manager.hpp]"]
  node_managers["Managers<br/>runtime services"]
  node_provider_layer[("Providers<br/>data source layer")]
  node_undo_patch["Undo/patch<br/>mutation flow"]
  node_data_processor{{"Processors<br/>node pipeline"}}
  node_pattern_language{{"Pattern language<br/>parser/runtime"}}
end

subgraph group_plugins["Plugins"]
  node_builtin_plugin["Builtin plugin<br/>default feature set"]
  node_ui_plugin["UI plugin<br/>shared widgets"]
  node_fonts_plugin["Fonts plugin<br/>asset plugin"]
  node_feature_plugins["Feature plugins<br/>extension pack"]
end

subgraph group_assets["Assets & packaging"]
  node_web_bundle["Web build<br/>wasm target"]
  node_romfs_resources["ROMFS assets<br/>embedded content"]
  node_packaging["Packaging<br/>release targets"]
end

node_main_forwarder -->|"launches"| node_main_gui
node_main_gui -->|"uses"| node_libimhex
node_main_updater -.->|"shares core"| node_libimhex
node_libimhex -->|"exposes"| node_content_registry
node_libimhex -->|"routes"| node_event_manager
node_libimhex -->|"hosts"| node_plugin_manager
node_libimhex -->|"bundles"| node_managers
node_libimhex -->|"defines"| node_provider_layer
node_libimhex -->|"tracks"| node_undo_patch
node_libimhex -->|"defines"| node_data_processor
node_libimhex -->|"integrates"| node_pattern_language
node_builtin_plugin -->|"registers"| node_content_registry
node_builtin_plugin -->|"implements"| node_provider_layer
node_builtin_plugin -->|"adds"| node_data_processor
node_builtin_plugin -->|"extends"| node_pattern_language
node_builtin_plugin -->|"ships"| node_romfs_resources
node_ui_plugin -->|"registers"| node_content_registry
node_fonts_plugin -->|"registers"| node_content_registry
node_feature_plugins -->|"registers"| node_content_registry
node_feature_plugins -->|"uses"| node_provider_layer
node_feature_plugins -.->|"builds on"| node_ui_plugin
node_web_bundle -.->|"targets"| node_main_gui
node_packaging -.->|"packages"| node_main_gui
node_packaging -.->|"packages"| node_main_updater
node_romfs_resources -.->|"feeds"| node_builtin_plugin
node_feature_plugins -.->|"localizes"| node_romfs_resources

click node_main_gui "https://github.com/werwolv/imhex/tree/master/main/gui"
click node_main_updater "https://github.com/werwolv/imhex/tree/master/main/updater"
click node_main_forwarder "https://github.com/werwolv/imhex/tree/master/main/forwarder"
click node_libimhex "https://github.com/werwolv/imhex/tree/master/lib/libimhex"
click node_content_registry "https://github.com/werwolv/imhex/tree/master/lib/libimhex/include/hex/api/content_registry"
click node_event_manager "https://github.com/werwolv/imhex/blob/master/lib/libimhex/include/hex/api/event_manager.hpp"
click node_plugin_manager "https://github.com/werwolv/imhex/blob/master/lib/libimhex/include/hex/api/plugin_manager.hpp"
click node_managers "https://github.com/werwolv/imhex/tree/master/lib/libimhex/include/hex/api"
click node_provider_layer "https://github.com/werwolv/imhex/tree/master/lib/libimhex/include/hex/providers"
click node_undo_patch "https://github.com/werwolv/imhex/tree/master/lib/libimhex/include/hex/providers/undo_redo"
click node_data_processor "https://github.com/werwolv/imhex/tree/master/lib/libimhex/include/hex/data_processor"
click node_pattern_language "https://github.com/werwolv/imhex/tree/master/lib/external/pattern_language"
click node_builtin_plugin "https://github.com/werwolv/imhex/tree/master/plugins/builtin"
click node_ui_plugin "https://github.com/werwolv/imhex/tree/master/plugins/ui"
click node_fonts_plugin "https://github.com/werwolv/imhex/tree/master/plugins/fonts"
click node_feature_plugins "https://github.com/werwolv/imhex/tree/master/plugins"
click node_web_bundle "https://github.com/werwolv/imhex/tree/master/dist/web"
click node_romfs_resources "https://github.com/werwolv/imhex/tree/master/plugins/builtin/romfs"
click node_packaging "https://github.com/werwolv/imhex/tree/master/dist"

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_gui,node_main_updater,node_main_forwarder toneBlue
class node_libimhex,node_content_registry,node_event_manager,node_plugin_manager,node_managers,node_provider_layer,node_undo_patch,node_data_processor,node_pattern_language toneAmber
class node_builtin_plugin,node_ui_plugin,node_fonts_plugin,node_feature_plugins toneMint
class node_web_bundle,node_romfs_resources,node_packaging toneRose
```

## Components

### Entrypoints

Desktop, updater, and web startup paths.

- [GUI app](https://github.com/werwolv/imhex/tree/master/main/gui): desktop runtime · Primary user-facing application process with startup, windowing, messaging, and crash handling. · `main/gui`
- [Updater](https://github.com/werwolv/imhex/tree/master/main/updater): helper exe · Separate executable used for update workflows. · `main/updater`
- [Forwarder](https://github.com/werwolv/imhex/tree/master/main/forwarder): launcher helper · Small entry process that forwards launch into the main app in some environments. · `main/forwarder`

### Core runtime

Shared SDK, managers, providers, events, and analysis primitives.

- [libimhex](https://github.com/werwolv/imhex/tree/master/lib/libimhex): core SDK · Central shared runtime and plugin-facing API used by the application and extensions. · `lib/libimhex`
- [Registry](https://github.com/werwolv/imhex/tree/master/lib/libimhex/include/hex/api/content_registry): extension API · Registers views, tools, providers, formatters, processors, settings, and commands. · `lib/libimhex/include/hex/api/content_registry`
- [Events](https://github.com/werwolv/imhex/blob/master/lib/libimhex/include/hex/api/event_manager.hpp): event bus · Lifecycle, GUI, interaction, provider, and request event routing. · `lib/libimhex/include/hex/api/event_manager.hpp`
- [Plugins core](https://github.com/werwolv/imhex/blob/master/lib/libimhex/include/hex/api/plugin_manager.hpp): plugin host · Loads plugins and mediates their integration with the application runtime. · `lib/libimhex/include/hex/api/plugin_manager.hpp`
- [Managers](https://github.com/werwolv/imhex/tree/master/lib/libimhex/include/hex/api): runtime services · Workspace, theme, localization, layout, shortcuts, tasks, project files, tutorials, and achievements. · `lib/libimhex/include/hex/api`
- [Providers](https://github.com/werwolv/imhex/tree/master/lib/libimhex/include/hex/providers): data source layer · Abstraction for files, disks, memory, network, remote access, and decoded sources. · `lib/libimhex/include/hex/providers`
- [Undo/patch](https://github.com/werwolv/imhex/tree/master/lib/libimhex/include/hex/providers/undo_redo): mutation flow · Provider-backed edit history and patch operations. · `lib/libimhex/include/hex/providers/undo_redo`
- [Processors](https://github.com/werwolv/imhex/tree/master/lib/libimhex/include/hex/data_processor): node pipeline · Graph-based preprocessing pipeline for decode, transform, and analysis stages. · `lib/libimhex/include/hex/data_processor`
- [Pattern language](https://github.com/werwolv/imhex/tree/master/lib/external/pattern_language): parser/runtime · C-like pattern descriptor system for structure, types, highlights, and visualizations. · `lib/external/pattern_language`

### Plugins

Built-in and feature plugins registered into the core content system.

- [Builtin plugin](https://github.com/werwolv/imhex/tree/master/plugins/builtin): default feature set · Registers core editor behavior, file handlers, views, processors, themes, workspaces, tutorials, and commands. · `plugins/builtin`
- [UI plugin](https://github.com/werwolv/imhex/tree/master/plugins/ui): shared widgets · Common widgets, editors, markdown, pattern UI, and text editor components used by other plugins. · `plugins/ui`
- [Fonts plugin](https://github.com/werwolv/imhex/tree/master/plugins/fonts): asset plugin · Manages bundled fonts and font selection. · `plugins/fonts`
- [Feature plugins](https://github.com/werwolv/imhex/tree/master/plugins): extension pack · Diffing, disassembler, hashes, remote, script loader, visualizers, windows, yara rules, and decompression features. · `plugins`

### Assets & packaging

Embedded resources, release packaging, and web bundle assets.

- [Web build](https://github.com/werwolv/imhex/tree/master/dist/web): wasm target · Browser/WebAssembly runtime and bundled web assets. · `dist/web`
- [ROMFS assets](https://github.com/werwolv/imhex/tree/master/plugins/builtin/romfs): embedded content · Themes, layouts, icons, localization, shaders, workspaces, splash assets, and plugin-provided content. · `plugins/builtin/romfs`
- [Packaging](https://github.com/werwolv/imhex/tree/master/dist): release targets · Desktop and distro packaging for Windows, Linux, macOS, Flatpak, Snap, AppImage, and related formats. · `dist`

## Connections

- Forwarder → GUI app: launches · Forwarder hands off into the main GUI app.
- GUI app → libimhex: uses · GUI bootstrap depends on the shared runtime and API.
- Updater → libimhex: shares core · Updater reuses shared infrastructure where needed.
- libimhex → Registry: exposes · Core library publishes the extension registration surface.
- libimhex → Events: routes · Shared event bus coordinates runtime and plugin communication.
- libimhex → Plugins core: hosts · Plugin manager is part of the core host layer.
- libimhex → Managers: bundles · Core runtime includes workspace, theme, task, shortcut, and project managers.
- libimhex → Providers: defines · Provider abstraction is central to data access.
- libimhex → Undo/patch: tracks · Mutation history and patching live on the provider layer.
- libimhex → Processors: defines · Node-based preprocessing pipeline is a core primitive.
- libimhex → Pattern language: integrates · Pattern language is part of the analysis and visualization stack.
- Builtin plugin → Registry: registers · Builtin plugin contributes most default views, providers, processors, and commands.
- Builtin plugin → Providers: implements · Builtin plugin ships the standard provider implementations.
- Builtin plugin → Processors: adds · Builtin plugin provides the default processing nodes.
- Builtin plugin → Pattern language: extends · Builtin plugin wires built-in types, functions, pragmas, and visualizers.
- Builtin plugin → ROMFS assets: ships · Default themes, layouts, locales, shaders, and workspaces are embedded here.
- UI plugin → Registry: registers · Shared UI contributes widgets and editors.
- Fonts plugin → Registry: registers · Font management is exposed through the content registry.
- Feature plugins → Registry: registers · Feature plugins add views, tools, providers, and analyzers through the registry.
- Feature plugins → Providers: uses · Feature plugins operate on the same provider abstraction.
- Feature plugins → UI plugin: builds on · Many feature plugins reuse shared UI components.
- Web build → GUI app: targets · Web build follows the GUI startup path in a browser runtime.
- Packaging → GUI app: packages · Release engineering bundles the desktop app into platform-specific distributions.
- Packaging → Updater: packages · Updater is packaged as a separate binary where needed.
- ROMFS assets → Builtin plugin: feeds · Embedded assets are consumed by the builtin plugin at startup.
- Feature plugins → ROMFS assets: localizes · Plugins commonly ship their own embedded assets and translations.
