# jaquadro/nbtexplorer architecture

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

- Interactive diagram: https://gitdiagram.com/jaquadro/nbtexplorer
- Repository: https://github.com/jaquadro/nbtexplorer

## Overview

#### Purpose and solution layout
NBTExplorer is a desktop editor for Minecraft-oriented Named Binary Tag (NBT) data. It reads and writes standalone NBT, schematic, region/anvil, and Cubic Chunks region files. The solution separates reusable NBT/domain logic (`NBTModel`), graphical editor front ends (`NBTExplorer`), and a command-line utility (`NBTUtil`). `NBTExplorer.sln` is the top-level integration point.

#### Application entry points and platform shells
The graphical application has distinct Windows/Mono WinForms and native macOS startup paths: `NBTExplorer/Program.cs`, `NBTExplorer/ProgramMac.cs`, and `NBTExplorer/Mac/AppDelegate.cs`. Windows centers on `NBTExplorer/Windows/MainForm.cs`; macOS centers on `NBTExplorer/Mac/MainWindowController.cs`. Both shells provide equivalent tree-oriented document editing while adapting menus, dialogs, clipboard, and search UI to their runtime toolkits.

#### NBT domain and file abstraction
`NBTModel` defines the application’s canonical editable tree model. `NBTModel/Data/Nodes/DataNode.cs` is the common node abstraction; concrete NBT scalar, array, list, and compound representations live under `NBTModel/Data/Nodes/`, including `TagDataNode.cs` and `TagCompoundDataNode.cs`. Container behavior is separated into `NBTModel/Data/CompoundTagContainer.cs` and `NBTModel/Data/ListTagContainer.cs`, allowing UI and operations to manipulate structured NBT independent of file format.

#### File loading, format selection, and persistence
`NBTModel/Data/FileTypeRegistry.cs` selects supported document/file implementations. File-backed and filesystem hierarchy nodes, such as `NBTModel/Data/Nodes/NbtFileDataNode.cs`, `NBTModel/Data/Nodes/RegionFileDataNode.cs`, and `NBTModel/Data/Nodes/DirectoryDataNode.cs`, bridge on-disk NBT sources into the shared `DataNode` hierarchy. Region-specific structures include chunk nodes and Cubic Chunks support in `NBTModel/Data/Nodes/RegionChunkDataNode.cs` and `NBTModel/Data/CubicRegionFile.cs`. The core boundary is therefore: format-specific storage parsing/serialization below, normalized editable node tree above.

#### Editor coordination and user operations
Controllers coordinate the visual tree, selection, and explorer commands rather than embedding this behavior directly in platform forms: `NBTExplorer/Controllers/NodeTreeController.cs`, `NBTExplorer/Controllers/ExplorerBarController.cs`, and `NBTExplorer/Controllers/RuleTreeController.cs`. Platform-specific create/edit/find dialogs collect user input, while controller-driven mutations apply it to model nodes. Clipboard interoperability is abstracted in `NBTModel/Interop/NbtClipboardController.cs` and implemented per UI platform in `NBTExplorer/Windows/NbtClipboardControllerWin.cs` and `NBTExplorer/Mac/NbtClipboardControllerMac.cs`.

#### Search and filtering pipeline
Search rules are model-level objects in `NBTModel/Search/SearchRule.cs`, with parsing support in `NBTModel/FilterExpressionParser.cs` and path representation in `NBTModel/NbtPath.cs`. `NBTExplorer/SearchWorker.cs` performs search work outside the interactive UI flow; each platform supplies state/UI integration through `NBTExplorer/Windows/SearchStateWin.cs` or `NBTExplorer/Mac/SearchStateMac.cs`. This separates long-running traversal and rule evaluation from cancellation/progress presentation.

#### CLI and delivery infrastructure
`NBTUtil/Program.cs` and `NBTUtil/ConsoleRunner.cs` provide a separate automation-oriented entry point over the model, dispatching commands such as editing, JSON conversion, printing, and tree printing from `NBTUtil/Ops/EditOperation.cs`, `NBTUtil/Ops/JsonOperation.cs`, and `NBTUtil/Ops/PrintTreeOperation.cs`. Material runtime targets are .NET Framework/WinForms and Mono, plus native macOS UI bindings. Windows packaging is defined by the WiX installer project at `NBTExplorer.Installer/NBTExplorer.Installer.wixproj` and `NBTExplorer.Installer/Product.wxs`; no network service or backend dependency is represented.

Main entry points: [`NBTModel/Data/Nodes/DataNode.cs`](https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/Nodes/DataNode.cs) (DataNode tree), [`NBTExplorer.sln`](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer.sln) (Solution), [`NBTExplorer/Program.cs`](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Program.cs) (Desktop startup), [`NBTExplorer/Controllers/NodeTreeController.cs`](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Controllers/NodeTreeController.cs) (Editor controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["NBTModel"]
  node_data_node["DataNode tree<br/>domain model<br/>[DataNode.cs]"]
  node_tag_nodes["NBT tag nodes<br/>domain nodes<br/>[TagDataNode.cs]"]
  node_containers["Tag containers<br/>domain containers"]
  node_file_registry["File type registry<br/>format selection"]
  node_storage_nodes[("File and region nodes<br/>storage adapters<br/>[NbtFileDataNode.cs]")]
  node_region_chunks["Region and cubic chunks<br/>region storage"]
  node_search_rules["Search rules and paths<br/>search model<br/>[SearchRule.cs]"]
  node_clipboard_api["Clipboard abstraction<br/>interop API"]
end

subgraph group_desktop["Desktop editor"]
  node_app_startup(("Desktop startup<br/>application entry<br/>[Program.cs]"))
  node_windows_shell["Windows main form<br/>WinForms shell<br/>[MainForm.cs]"]
  node_mac_shell["macOS window controller<br/>macOS shell"]
  node_editor_controllers["Editor controllers<br/>editor coordination"]
  node_platform_clipboard["Platform clipboard<br/>platform adapter"]
  node_search_worker["Search worker<br/>background search<br/>[SearchWorker.cs]"]
  node_platform_search["Platform search state<br/>UI search integration<br/>[SearchStateWin.cs]"]
end

subgraph group_cli["NBTUtil"]
  node_cli_entry(("CLI runner<br/>command entry<br/>[ConsoleRunner.cs]"))
  node_cli_operations["CLI operations<br/>command operations<br/>[EditOperation.cs]"]
end

subgraph group_delivery["Delivery"]
  node_installer["WiX installer<br/>Windows packaging"]
end

node_solution{{"Solution<br/>[NBTExplorer.sln]"}}

node_solution -->|"includes"| node_data_node
node_solution -->|"includes"| node_app_startup
node_solution -->|"includes"| node_cli_entry
node_solution -->|"includes"| node_installer
node_tag_nodes -->|"implements tree nodes"| node_data_node
node_containers -->|"structures"| node_tag_nodes
node_file_registry -->|"selects"| node_storage_nodes
node_storage_nodes -->|"exposes as"| node_data_node
node_region_chunks -->|"extends"| node_storage_nodes
node_search_rules -->|"evaluates against"| node_data_node
node_app_startup -->|"Windows/Mono"| node_windows_shell
node_app_startup -->|"macOS"| node_mac_shell
node_windows_shell -->|"uses"| node_editor_controllers
node_mac_shell -->|"uses"| node_editor_controllers
node_editor_controllers -->|"edits"| node_data_node
node_platform_clipboard -->|"implements"| node_clipboard_api
node_editor_controllers -->|"uses"| node_platform_clipboard
node_platform_search -->|"drives"| node_search_worker
node_search_worker -->|"applies"| node_search_rules
node_search_worker -->|"traverses"| node_data_node
node_cli_entry -->|"dispatches"| node_cli_operations
node_cli_operations -->|"reads and edits"| node_data_node
node_cli_operations -->|"opens formats"| node_file_registry
node_installer -->|"packages"| node_app_startup

click node_solution "https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer.sln"
click node_data_node "https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/Nodes/DataNode.cs"
click node_tag_nodes "https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/Nodes/TagDataNode.cs"
click node_containers "https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/CompoundTagContainer.cs"
click node_file_registry "https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/FileTypeRegistry.cs"
click node_storage_nodes "https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/Nodes/NbtFileDataNode.cs"
click node_region_chunks "https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/Nodes/RegionChunkDataNode.cs"
click node_search_rules "https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Search/SearchRule.cs"
click node_clipboard_api "https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Interop/NbtClipboardController.cs"
click node_app_startup "https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Program.cs"
click node_windows_shell "https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Windows/MainForm.cs"
click node_mac_shell "https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Mac/MainWindowController.cs"
click node_editor_controllers "https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Controllers/NodeTreeController.cs"
click node_platform_clipboard "https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Windows/NbtClipboardControllerWin.cs"
click node_search_worker "https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/SearchWorker.cs"
click node_platform_search "https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Windows/SearchStateWin.cs"
click node_cli_entry "https://github.com/jaquadro/nbtexplorer/blob/master/NBTUtil/ConsoleRunner.cs"
click node_cli_operations "https://github.com/jaquadro/nbtexplorer/blob/master/NBTUtil/Ops/EditOperation.cs"
click node_installer "https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer.Installer/NBTExplorer.Installer.wixproj"

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_data_node,node_tag_nodes,node_containers,node_file_registry,node_storage_nodes,node_region_chunks,node_search_rules,node_clipboard_api toneBlue
class node_app_startup,node_windows_shell,node_mac_shell,node_editor_controllers,node_platform_clipboard,node_search_worker,node_platform_search toneAmber
class node_cli_entry,node_cli_operations toneMint
class node_installer toneRose
class node_solution toneNeutral
```

## Components

### NBTModel

Reusable NBT domain, storage, and search layer.

- [DataNode tree](https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/Nodes/DataNode.cs): domain model · Canonical editable NBT tree abstraction. · `NBTModel/Data/Nodes/DataNode.cs`
- [NBT tag nodes](https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/Nodes/TagDataNode.cs): domain nodes · Scalar, array, list, and compound tag representations. · `NBTModel/Data/Nodes/TagDataNode.cs`
- [Tag containers](https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/CompoundTagContainer.cs): domain containers · Structured compound and list behavior. · `NBTModel/Data/CompoundTagContainer.cs`
- [File type registry](https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/FileTypeRegistry.cs): format selection · Selects supported document implementations. · `NBTModel/Data/FileTypeRegistry.cs`
- [File and region nodes](https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/Nodes/NbtFileDataNode.cs): storage adapters · Maps files, directories, and regions into the editable tree. · `NBTModel/Data/Nodes/NbtFileDataNode.cs`
- [Region and cubic chunks](https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Data/Nodes/RegionChunkDataNode.cs): region storage · Region chunk and Cubic Chunks support. · `NBTModel/Data/Nodes/RegionChunkDataNode.cs`
- [Search rules and paths](https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Search/SearchRule.cs): search model · Filter expressions, rules, and NBT paths. · `NBTModel/Search/SearchRule.cs`
- [Clipboard abstraction](https://github.com/jaquadro/nbtexplorer/blob/master/NBTModel/Interop/NbtClipboardController.cs): interop API · `NBTModel/Interop/NbtClipboardController.cs`

### Desktop editor

WinForms/Mono and native macOS editing shells.

- [Desktop startup](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Program.cs): application entry · Selects WinForms/Mono or native macOS startup. · `NBTExplorer/Program.cs`
- [Windows main form](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Windows/MainForm.cs): WinForms shell · `NBTExplorer/Windows/MainForm.cs`
- [macOS window controller](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Mac/MainWindowController.cs): macOS shell · `NBTExplorer/Mac/MainWindowController.cs`
- [Editor controllers](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Controllers/NodeTreeController.cs): editor coordination · Coordinates tree, explorer commands, and rules. · `NBTExplorer/Controllers/NodeTreeController.cs`
- [Platform clipboard](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Windows/NbtClipboardControllerWin.cs): platform adapter · Windows and macOS clipboard implementations. · `NBTExplorer/Windows/NbtClipboardControllerWin.cs`
- [Search worker](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/SearchWorker.cs): background search · Runs traversal and rule evaluation outside the UI flow. · `NBTExplorer/SearchWorker.cs`
- [Platform search state](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer/Windows/SearchStateWin.cs): UI search integration · Cancellation and progress integration per platform. · `NBTExplorer/Windows/SearchStateWin.cs`

### NBTUtil

Automation-oriented command-line utility.

- [CLI runner](https://github.com/jaquadro/nbtexplorer/blob/master/NBTUtil/ConsoleRunner.cs): command entry · Dispatches automation commands. · `NBTUtil/ConsoleRunner.cs`
- [CLI operations](https://github.com/jaquadro/nbtexplorer/blob/master/NBTUtil/Ops/EditOperation.cs): command operations · Edit, JSON conversion, printing, and tree printing. · `NBTUtil/Ops/EditOperation.cs`

### Delivery

- [WiX installer](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer.Installer/NBTExplorer.Installer.wixproj): Windows packaging · `NBTExplorer.Installer/NBTExplorer.Installer.wixproj`

### Other components

- [Solution](https://github.com/jaquadro/nbtexplorer/blob/master/NBTExplorer.sln): solution · Top-level integration point. · `NBTExplorer.sln`

## Connections

- Solution → DataNode tree: includes
- Solution → Desktop startup: includes
- Solution → CLI runner: includes
- Solution → WiX installer: includes
- NBT tag nodes → DataNode tree: implements tree nodes
- Tag containers → NBT tag nodes: structures
- File type registry → File and region nodes: selects
- File and region nodes → DataNode tree: exposes as
- Region and cubic chunks → File and region nodes: extends
- Search rules and paths → DataNode tree: evaluates against
- Desktop startup → Windows main form: Windows/Mono
- Desktop startup → macOS window controller: macOS
- Windows main form → Editor controllers: uses
- macOS window controller → Editor controllers: uses
- Editor controllers → DataNode tree: edits
- Platform clipboard → Clipboard abstraction: implements
- Editor controllers → Platform clipboard: uses
- Platform search state → Search worker: drives
- Search worker → Search rules and paths: applies
- Search worker → DataNode tree: traverses
- CLI runner → CLI operations: dispatches
- CLI operations → DataNode tree: reads and edits
- CLI operations → File type registry: opens formats
- WiX installer → Desktop startup: packages