How funap/hex-editor works
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: workspace.rs Workspace · editor_service.rs Editor svc · interpreter.rs Interpreter · main.rs main
Components 30
Orchestration
User actions, app state, and services
- Actions · User-triggered commands and app intents
src/actions.rs - App state · Central application state shared by UI and services
src/app_state.rs - Editor svc · Coordinates editor, document, and workspace mutations
src/service/editor_service.rs
Core
Binary editing engine and document model
- Buffer · Binary data access and mutation substrate
src/core/buffer.rs - Document · Editable file-backed content and persistence boundary
src/core/document.rs - Editor · Editing session state and cursor/selection behavior
src/core/editor.rs - History · Undo and redo tracking for edits
src/core/history.rs - Search · Binary and text searching across data
src/core/search.rs - Diff · Binary comparison and change inspection
src/core/diff.rs - Encoding · ASCII, UTF-8, UTF-16 and related rendering rules
src/core/encoding.rs - Appearance · Presentation settings shared with the UI
src/core/appearance.rs
Structure
Binary-structure parsing and visualization
- Expr · Evaluates structure definition expressions
src/core/structure/expression.rs - Interpreter · Executes structure rules over binary content
src/core/structure/interpreter.rs - Types · Typed structure fields and metadata
src/core/structure/types.rs - Palette · Maps parsed fields to colors and visual roles
src/core/structure/palette.rs - Kaitai · Kaitai-related integration for structure definitions
src/core/structure/kaitai.rs
UI
GPUI workspace, panels, and reusable components
- Workspace · Top-level UI composition and pane coordination
src/ui/workspace.rs - Editor panel · Primary hex editing and inspection surface
src/ui/panels/editor_panel.rs - Left panel · Navigation and auxiliary workspace pane
src/ui/panels/left_panel.rs - Diff panel · Dedicated binary diff view
src/ui/panels/diff_panel.rs - Settings · Application configuration and display options
src/ui/panels/settings_panel.rs - Hex view · Renders bytes with synchronized hex/ASCII presentation
src/ui/components/hex_view.rs - Struct tree · Shows parsed binary structures as a tree
src/ui/components/struct_tree_view.rs - File tree · Browser for opening and navigating files
src/ui/components/file_tree_view.rs - Search bar · Search entry and control surface
src/ui/components/search_bar.rs - Toolbar · Primary commands and editor actions
src/ui/components/toolbar.rs - Activity bar · Switches between major workspace modes
src/ui/components/activity_bar.rs - Status bar · Shows cursor, mode, and operation status
src/ui/components/status_bar.rs
Theme
Visual styling and theme assets
- Ayu theme · JSON theme palette used by the application
themes/ayu.json
Connections 39
- 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