# funap/hex-editor architecture

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

- Interactive diagram: https://gitdiagram.com/funap/hex-editor
- Repository: https://github.com/funap/hex-editor

## Overview

1. **Runtime and entry point**
   - This is a native Rust desktop application built on **GPUI**. `src/main.rs` is the binary entry point and likely wires application startup, window creation, and global action registration.
   - The presence of **Tokio** in the README suggests asynchronous file and data operations are offloaded so the UI stays responsive on large binaries.

2. **Top-level control boundary**
   - `src/actions.rs`, `src/app_state.rs`, and `src/service/` form the control layer above the domain logic.
   - `app_state` is the central state holder, while actions represent user-triggered commands and services coordinate mutations across documents, editors, and views.

3. **Core binary editing engine**
   - `src/core/` is the main domain layer for hex-editor behavior.
   - Key responsibilities include:
     - `buffer.rs` for binary data storage/access
     - `document.rs` for file-backed editable content
     - `editor.rs` for edit/session state
     - `history.rs` for undo/redo
     - `diff.rs` for file comparison
     - `search.rs` for binary/text searching
     - `encoding.rs` for ASCII/UTF-8/UTF-16 rendering
     - `command.rs` for editor commands
     - `appearance.rs` for presentation-related settings used by the UI

4. **Structure-definition subsystem**
   - `src/core/structure/` is a distinct subsystem for interpreting binary formats beyond plain hex view.
   - It includes:
     - `expression.rs` and `interpreter.rs` for evaluating structure rules
     - `types.rs` and `palette.rs` for typed field/visual mapping
     - `kaitai.rs` for Kaitai-related integration or import
     - `tests.rs` for validating the structure engine
   - The `docs/structure-definition-spec.md` file indicates this is a documented feature, not an incidental helper.

5. **UI composition**
   - `src/ui/` is the presentation layer, implemented with GPUI components.
   - `workspace.rs` likely owns the overall screen layout and coordinates the main panes.
   - `ui/panels/` defines the major workspace regions: editor, left sidebar, diff view, and settings.

6. **Reusable UI components**
   - `src/ui/components/` contains the building blocks used inside panels:
     - `hex_view.rs` for byte-level rendering
     - `struct_tree_view.rs` for displaying parsed structures
     - `file_tree_view.rs` for filesystem navigation
     - `search_bar.rs` for query input
     - `toolbar.rs`, `activity_bar.rs`, and `status_bar.rs` for global controls and feedback
   - This separation suggests a componentized UI where panels are composed from smaller render primitives.

7. **Primary data flows**
   - User interaction starts in the UI, emits actions, and is handled by the service layer.
   - Services call into `core` to open files, mutate buffers, search, diff, or apply edits.
   - Updated document/editor state flows back into `app_state`, which drives rerendering of the panels and components.

8. **Editor and inspection experiences**
   - The main editing surface appears to combine **hex and ASCII views** with synchronized navigation.
   - Structured binary inspection is an additional mode layered on top of the raw byte buffer, likely feeding the `struct_tree_view` and custom line breaks mentioned in the README.

9. **Diff and multi-document support**
   - `src/ui/panels/diff_panel.rs` plus `core/diff.rs` indicate first-class binary comparison.
   - `src/service/editor_service.rs` suggests orchestration across multiple documents/editors rather than a single-file-only model.

10. **Filesystem navigation and workspace layout**
   - `file_tree_view.rs` indicates integrated file browsing inside the editor workspace.
   - This implies the app can open files or folders directly, with the file tree acting as an input path to the editor/document subsystem.

11. **Theming and visual configuration**
   - `theme.rs` and `themes/ayu.json` define the app’s visual styling.
   - `core/appearance.rs` likely carries user-facing display preferences that affect rendering across the workspace.

12. **Project boundaries for diagramming**
   - A useful architecture diagram should separate:
     - **UI layer**: workspace, panels, components
     - **Orchestration layer**: actions, app state, services
     - **Core engine**: buffers, documents, editing, search, diff, encoding, history
     - **Structure interpreter**: custom binary-format parsing/visualization
     - **Theme/configuration**: appearance and theme assets
   - The main dependency direction is from UI → services/state → core/structure, with rendered state flowing back up to the UI.

Main entry points: [`src/ui/workspace.rs`](https://github.com/funap/hex-editor/blob/main/src/ui/workspace.rs) (Workspace), [`src/service/editor_service.rs`](https://github.com/funap/hex-editor/blob/main/src/service/editor_service.rs) (Editor svc), [`src/core/structure/interpreter.rs`](https://github.com/funap/hex-editor/blob/main/src/core/structure/interpreter.rs) (Interpreter), [`src/main.rs`](https://github.com/funap/hex-editor/blob/main/src/main.rs) (main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("main<br/>binary entry<br/>[main.rs]"))
end

subgraph group_orchestration["Orchestration"]
  node_actions["Actions<br/>command layer<br/>[actions.rs]"]
  node_app_state[("App state<br/>state store<br/>[app_state.rs]")]
  node_editor_service["Editor svc<br/>coordination service<br/>[editor_service.rs]"]
end

subgraph group_core["Core"]
  node_buffer[("Buffer<br/>byte storage<br/>[buffer.rs]")]
  node_document["Document<br/>file model<br/>[document.rs]"]
  node_editor["Editor<br/>session model<br/>[editor.rs]"]
  node_history["History<br/>undo stack<br/>[history.rs]"]
  node_search["Search<br/>query engine<br/>[search.rs]"]
  node_diff["Diff<br/>compare engine<br/>[diff.rs]"]
  node_encoding["Encoding<br/>decode formats<br/>[encoding.rs]"]
  node_appearance["Appearance<br/>view settings<br/>[appearance.rs]"]
end

subgraph group_structure["Structure"]
  node_expr{{"Expr<br/>rule evaluator<br/>[expression.rs]"}}
  node_interp{{"Interpreter<br/>parse engine<br/>[interpreter.rs]"}}
  node_types["Types<br/>field schema<br/>[types.rs]"]
  node_palette["Palette<br/>visual mapping<br/>[palette.rs]"]
  node_kaitai["Kaitai<br/>import bridge<br/>[kaitai.rs]"]
end

subgraph group_ui["UI"]
  node_workspace["Workspace<br/>layout root<br/>[workspace.rs]"]
  node_editor_panel["Editor panel<br/>main pane<br/>[editor_panel.rs]"]
  node_left_panel["Left panel<br/>sidebar<br/>[left_panel.rs]"]
  node_diff_panel["Diff panel<br/>comparison pane<br/>[diff_panel.rs]"]
  node_settings_panel["Settings<br/>preferences pane<br/>[settings_panel.rs]"]
  node_hex_view["Hex view<br/>byte renderer<br/>[hex_view.rs]"]
  node_struct_tree_view["Struct tree<br/>structure view"]
  node_file_tree_view["File tree<br/>filesystem view<br/>[file_tree_view.rs]"]
  node_search_bar["Search bar<br/>query input<br/>[search_bar.rs]"]
  node_toolbar["Toolbar<br/>global controls<br/>[toolbar.rs]"]
  node_activity_bar["Activity bar<br/>navigation rail<br/>[activity_bar.rs]"]
  node_status_bar["Status bar<br/>feedback bar<br/>[status_bar.rs]"]
end

subgraph group_theme["Theme"]
  node_theme_file["Ayu theme<br/>theme asset<br/>[ayu.json]"]
end

node_main -->|"registers"| node_actions
node_main -->|"creates"| node_app_state
node_main -->|"launches"| node_workspace
node_actions -->|"dispatches"| node_editor_service
node_editor_service -->|"updates"| node_app_state
node_editor_service -->|"opens"| node_document
node_editor_service -->|"drives"| node_editor
node_editor_service -->|"runs"| node_search
node_editor_service -->|"compares"| node_diff
node_editor_service -->|"mutates"| node_buffer
node_document -->|"owns"| node_buffer
node_editor -->|"tracks"| node_history
node_editor -->|"renders"| node_encoding
node_workspace -->|"contains"| node_editor_panel
node_workspace -->|"contains"| node_left_panel
node_workspace -->|"contains"| node_diff_panel
node_workspace -->|"contains"| node_settings_panel
node_workspace -->|"uses"| node_toolbar
node_workspace -->|"uses"| node_activity_bar
node_workspace -->|"uses"| node_status_bar
node_editor_panel -->|"composes"| node_hex_view
node_editor_panel -->|"composes"| node_struct_tree_view
node_left_panel -->|"composes"| node_file_tree_view
node_left_panel -->|"composes"| node_search_bar
node_diff_panel -->|"shows"| node_diff
node_settings_panel -->|"edits"| node_appearance
node_theme_file -.->|"informs"| node_appearance
node_interp -->|"evaluates"| node_expr
node_interp -->|"produces"| node_types
node_interp -->|"maps"| node_palette
node_interp -->|"imports"| node_kaitai
node_struct_tree_view -->|"renders"| node_interp
node_struct_tree_view -->|"shows"| node_types
node_hex_view -->|"reads"| node_buffer
node_file_tree_view -->|"opens"| node_document
node_search_bar -->|"queries"| node_search
node_toolbar -->|"invokes"| node_actions
node_status_bar -->|"reflects"| node_app_state
node_activity_bar -->|"switches"| node_workspace

click node_main "https://github.com/funap/hex-editor/blob/main/src/main.rs"
click node_actions "https://github.com/funap/hex-editor/blob/main/src/actions.rs"
click node_app_state "https://github.com/funap/hex-editor/blob/main/src/app_state.rs"
click node_editor_service "https://github.com/funap/hex-editor/blob/main/src/service/editor_service.rs"
click node_buffer "https://github.com/funap/hex-editor/blob/main/src/core/buffer.rs"
click node_document "https://github.com/funap/hex-editor/blob/main/src/core/document.rs"
click node_editor "https://github.com/funap/hex-editor/blob/main/src/core/editor.rs"
click node_history "https://github.com/funap/hex-editor/blob/main/src/core/history.rs"
click node_search "https://github.com/funap/hex-editor/blob/main/src/core/search.rs"
click node_diff "https://github.com/funap/hex-editor/blob/main/src/core/diff.rs"
click node_encoding "https://github.com/funap/hex-editor/blob/main/src/core/encoding.rs"
click node_appearance "https://github.com/funap/hex-editor/blob/main/src/core/appearance.rs"
click node_expr "https://github.com/funap/hex-editor/blob/main/src/core/structure/expression.rs"
click node_interp "https://github.com/funap/hex-editor/blob/main/src/core/structure/interpreter.rs"
click node_types "https://github.com/funap/hex-editor/blob/main/src/core/structure/types.rs"
click node_palette "https://github.com/funap/hex-editor/blob/main/src/core/structure/palette.rs"
click node_kaitai "https://github.com/funap/hex-editor/blob/main/src/core/structure/kaitai.rs"
click node_workspace "https://github.com/funap/hex-editor/blob/main/src/ui/workspace.rs"
click node_editor_panel "https://github.com/funap/hex-editor/blob/main/src/ui/panels/editor_panel.rs"
click node_left_panel "https://github.com/funap/hex-editor/blob/main/src/ui/panels/left_panel.rs"
click node_diff_panel "https://github.com/funap/hex-editor/blob/main/src/ui/panels/diff_panel.rs"
click node_settings_panel "https://github.com/funap/hex-editor/blob/main/src/ui/panels/settings_panel.rs"
click node_hex_view "https://github.com/funap/hex-editor/blob/main/src/ui/components/hex_view.rs"
click node_struct_tree_view "https://github.com/funap/hex-editor/blob/main/src/ui/components/struct_tree_view.rs"
click node_file_tree_view "https://github.com/funap/hex-editor/blob/main/src/ui/components/file_tree_view.rs"
click node_search_bar "https://github.com/funap/hex-editor/blob/main/src/ui/components/search_bar.rs"
click node_toolbar "https://github.com/funap/hex-editor/blob/main/src/ui/components/toolbar.rs"
click node_activity_bar "https://github.com/funap/hex-editor/blob/main/src/ui/components/activity_bar.rs"
click node_status_bar "https://github.com/funap/hex-editor/blob/main/src/ui/components/status_bar.rs"
click node_theme_file "https://github.com/funap/hex-editor/blob/main/themes/ayu.json"

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 toneBlue
class node_actions,node_app_state,node_editor_service toneAmber
class node_buffer,node_document,node_editor,node_history,node_search,node_diff,node_encoding,node_appearance toneMint
class node_expr,node_interp,node_types,node_palette,node_kaitai toneRose
class node_workspace,node_editor_panel,node_left_panel,node_diff_panel,node_settings_panel,node_hex_view,node_struct_tree_view,node_file_tree_view,node_search_bar,node_toolbar,node_activity_bar,node_status_bar toneIndigo
class node_theme_file toneTeal
```

## Components

### Runtime

App entry and startup wiring

- [main](https://github.com/funap/hex-editor/blob/main/src/main.rs): binary entry · Starts the desktop app and wires global setup · `src/main.rs`

### Orchestration

User actions, app state, and services

- [Actions](https://github.com/funap/hex-editor/blob/main/src/actions.rs): command layer · User-triggered commands and app intents · `src/actions.rs`
- [App state](https://github.com/funap/hex-editor/blob/main/src/app_state.rs): state store · Central application state shared by UI and services · `src/app_state.rs`
- [Editor svc](https://github.com/funap/hex-editor/blob/main/src/service/editor_service.rs): coordination service · Coordinates editor, document, and workspace mutations · `src/service/editor_service.rs`

### Core

Binary editing engine and document model

- [Buffer](https://github.com/funap/hex-editor/blob/main/src/core/buffer.rs): byte storage · Binary data access and mutation substrate · `src/core/buffer.rs`
- [Document](https://github.com/funap/hex-editor/blob/main/src/core/document.rs): file model · Editable file-backed content and persistence boundary · `src/core/document.rs`
- [Editor](https://github.com/funap/hex-editor/blob/main/src/core/editor.rs): session model · Editing session state and cursor/selection behavior · `src/core/editor.rs`
- [History](https://github.com/funap/hex-editor/blob/main/src/core/history.rs): undo stack · Undo and redo tracking for edits · `src/core/history.rs`
- [Search](https://github.com/funap/hex-editor/blob/main/src/core/search.rs): query engine · Binary and text searching across data · `src/core/search.rs`
- [Diff](https://github.com/funap/hex-editor/blob/main/src/core/diff.rs): compare engine · Binary comparison and change inspection · `src/core/diff.rs`
- [Encoding](https://github.com/funap/hex-editor/blob/main/src/core/encoding.rs): decode formats · ASCII, UTF-8, UTF-16 and related rendering rules · `src/core/encoding.rs`
- [Appearance](https://github.com/funap/hex-editor/blob/main/src/core/appearance.rs): view settings · Presentation settings shared with the UI · `src/core/appearance.rs`

### Structure

Binary-structure parsing and visualization

- [Expr](https://github.com/funap/hex-editor/blob/main/src/core/structure/expression.rs): rule evaluator · Evaluates structure definition expressions · `src/core/structure/expression.rs`
- [Interpreter](https://github.com/funap/hex-editor/blob/main/src/core/structure/interpreter.rs): parse engine · Executes structure rules over binary content · `src/core/structure/interpreter.rs`
- [Types](https://github.com/funap/hex-editor/blob/main/src/core/structure/types.rs): field schema · Typed structure fields and metadata · `src/core/structure/types.rs`
- [Palette](https://github.com/funap/hex-editor/blob/main/src/core/structure/palette.rs): visual mapping · Maps parsed fields to colors and visual roles · `src/core/structure/palette.rs`
- [Kaitai](https://github.com/funap/hex-editor/blob/main/src/core/structure/kaitai.rs): import bridge · Kaitai-related integration for structure definitions · `src/core/structure/kaitai.rs`

### UI

GPUI workspace, panels, and reusable components

- [Workspace](https://github.com/funap/hex-editor/blob/main/src/ui/workspace.rs): layout root · Top-level UI composition and pane coordination · `src/ui/workspace.rs`
- [Editor panel](https://github.com/funap/hex-editor/blob/main/src/ui/panels/editor_panel.rs): main pane · Primary hex editing and inspection surface · `src/ui/panels/editor_panel.rs`
- [Left panel](https://github.com/funap/hex-editor/blob/main/src/ui/panels/left_panel.rs): sidebar · Navigation and auxiliary workspace pane · `src/ui/panels/left_panel.rs`
- [Diff panel](https://github.com/funap/hex-editor/blob/main/src/ui/panels/diff_panel.rs): comparison pane · Dedicated binary diff view · `src/ui/panels/diff_panel.rs`
- [Settings](https://github.com/funap/hex-editor/blob/main/src/ui/panels/settings_panel.rs): preferences pane · Application configuration and display options · `src/ui/panels/settings_panel.rs`
- [Hex view](https://github.com/funap/hex-editor/blob/main/src/ui/components/hex_view.rs): byte renderer · Renders bytes with synchronized hex/ASCII presentation · `src/ui/components/hex_view.rs`
- [Struct tree](https://github.com/funap/hex-editor/blob/main/src/ui/components/struct_tree_view.rs): structure view · Shows parsed binary structures as a tree · `src/ui/components/struct_tree_view.rs`
- [File tree](https://github.com/funap/hex-editor/blob/main/src/ui/components/file_tree_view.rs): filesystem view · Browser for opening and navigating files · `src/ui/components/file_tree_view.rs`
- [Search bar](https://github.com/funap/hex-editor/blob/main/src/ui/components/search_bar.rs): query input · Search entry and control surface · `src/ui/components/search_bar.rs`
- [Toolbar](https://github.com/funap/hex-editor/blob/main/src/ui/components/toolbar.rs): global controls · Primary commands and editor actions · `src/ui/components/toolbar.rs`
- [Activity bar](https://github.com/funap/hex-editor/blob/main/src/ui/components/activity_bar.rs): navigation rail · Switches between major workspace modes · `src/ui/components/activity_bar.rs`
- [Status bar](https://github.com/funap/hex-editor/blob/main/src/ui/components/status_bar.rs): feedback bar · Shows cursor, mode, and operation status · `src/ui/components/status_bar.rs`

### Theme

Visual styling and theme assets

- [Ayu theme](https://github.com/funap/hex-editor/blob/main/themes/ayu.json): theme asset · JSON theme palette used by the application · `themes/ayu.json`

## Connections

- main → Actions: registers · Startup wires application commands
- main → App state: creates · Initializes shared application state
- main → Workspace: launches · Opens the main UI workspace
- Actions → Editor svc: dispatches · Actions are executed by services
- Editor svc → App state: updates · Service mutations flow into shared state
- Editor svc → Document: opens · Loads and manages file-backed documents
- Editor svc → Editor: drives · Updates editing session state
- Editor svc → Search: runs · Coordinates search operations
- Editor svc → Diff: compares · Coordinates binary comparison workflows
- Editor svc → Buffer: mutates · Applies edits to byte storage
- Document → Buffer: owns · Documents wrap the underlying byte buffer
- Editor → History: tracks · Editing session records undoable changes
- Editor → Encoding: renders · Editor view depends on decoding rules
- Workspace → Editor panel: contains · Main pane is part of the workspace
- Workspace → Left panel: contains · Sidebar is part of the workspace
- Workspace → Diff panel: contains · Diff mode is part of the workspace
- Workspace → Settings: contains · Settings pane is part of the workspace
- Workspace → Toolbar: uses · Workspace exposes global controls
- Workspace → Activity bar: uses · Workspace exposes mode navigation
- Workspace → Status bar: uses · Workspace shows status feedback
- Editor panel → Hex view: composes · Primary editor surface uses the hex renderer
- Editor panel → Struct tree: composes · Structured inspection is shown alongside raw bytes
- Left panel → File tree: composes · Sidebar includes filesystem navigation
- Left panel → Search bar: composes · Sidebar includes search entry
- Diff panel → Diff: shows · Diff pane presents comparison results
- Settings → Appearance: edits · Preferences affect presentation settings
- Ayu theme → Appearance: informs · Theme asset influences rendering choices
- Interpreter → Expr: evaluates · Interpreter executes expressions during parsing
- Interpreter → Types: produces · Parsed structures are typed fields
- Interpreter → Palette: maps · Interpreter output feeds visual styling
- Interpreter → Kaitai: imports · Supports Kaitai-based structure definitions
- Struct tree → Interpreter: renders · Tree view displays parsed structure results
- Struct tree → Types: shows · Uses typed field metadata for presentation
- Hex view → Buffer: reads · Hex view renders the underlying bytes
- File tree → Document: opens · File selection feeds the document subsystem
- Search bar → Search: queries · Search UI triggers search engine operations
- Toolbar → Actions: invokes · Toolbar exposes common commands
- Status bar → App state: reflects · Status feedback is derived from shared state
- Activity bar → Workspace: switches · Navigation changes active workspace mode
