# bnorthern42/wurmexplorer architecture

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

- Interactive diagram: https://gitdiagram.com/bnorthern42/wurmexplorer
- Repository: https://github.com/bnorthern42/wurmexplorer

## Overview

WurmExplorer is a native desktop toolkit for Wurm Online cartography, treasure finding, game-mechanics calculations, breeding, and client-log telemetry. The main workflow starts with a player selecting a map or feature in the desktop UI, then uses map/vision processing or a domain calculator to produce a visual result or analysis. The graph preserves README-described capabilities whose implementations were not sampled, using their exact tree paths. Edges are limited to relationships shown by the excerpts, SOURCE INDEX, or README; several feature-internal calls remain unknown.

Main entry points: [`src/ui/MainWindow.cpp`](https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/MainWindow.cpp) (Main Window), [`src/engine/ZoomMapCanvas.cpp`](https://github.com/bnorthern42/wurmexplorer/blob/main/src/engine/ZoomMapCanvas.cpp) (Deep-Zoom Canvas), [`src/features/tools/ToolsPanel.cpp`](https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/tools/ToolsPanel.cpp) (Calculators and Tools), [`src/ui/panels/SailingPanel.cpp`](https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/panels/SailingPanel.cpp) (Sailing Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop UI"]
  node_app["Application Startup<br/>[main.cpp]"]
  node_window["Main Window<br/>[MainWindow.cpp]"]
  node_navigation["Navigation Bar<br/>[NavigationBar.cpp]"]
  node_controls["Map Controls<br/>[TopControlBar.cpp]"]
end

subgraph group_maps["Maps and Navigation"]
  node_map_canvas["Deep-Zoom Canvas<br/>[ZoomMapCanvas.cpp]"]
  node_map_variants["Map Variants<br/>[MapVariants.cpp]"]
  node_sailing["Sailing Routes<br/>[SailingPanel.cpp]"]
  node_cluster_layout["Cluster Routing<br/>[ClusterLayout.cpp]"]
  node_cluster_drawings[("Route Overlays")]
  node_drawing["Map Drawing<br/>[DrawingPanel.cpp]"]
end

subgraph group_vision["Treasure Vision"]
  node_treasure["Treasure Locator<br/>[TreasurePanel.cpp]"]
  node_extractor["Clue Extraction<br/>[Extractor.cpp]"]
  node_matcher["Terrain Matching<br/>[Matcher.cpp]"]
  node_ocr["Coordinate OCR<br/>[Ocr.cpp]"]
end

subgraph group_player_tools["Player Tools"]
  node_granger["Breeding Evaluator<br/>[GrangerPanel.cpp]"]
  node_skills["Skills Monitor<br/>[SkillsPanel.cpp]"]
  node_log_parser["Skill Log Parser<br/>[SkillLogParser.cpp]"]
  node_tools["Calculators and Tools<br/>[ToolsPanel.cpp]"]
  node_grinder["Mechanics Simulation<br/>[GrinderEngine.cpp]"]
  node_bridge["Bridge Pillar Math"]
  node_imping["Imping Calculator<br/>[ImpCalculator.cpp]"]
end

subgraph group_state["Domain State"]
  node_annotations["Map Annotations"]
  node_annotation_store[("Annotation Store")]
  node_artifacts["Artifact Triangulation<br/>[ArtifactPanel.cpp]"]
  node_artifact_store[("Artifact Store<br/>[ArtifactStore.cpp]")]
  node_map_data["Map Data and Overlays<br/>[MapDataPanel.cpp]"]
  node_drawing_store[("Drawing Store<br/>[DrawingStore.cpp]")]
end

node_player(("Player"))
node_client_logs["Client Logs"]
node_map_files["Map Files"]

node_player -->|"launches"| node_app
node_app -->|"opens"| node_window
node_window -->|"creates"| node_navigation
node_window -->|"creates"| node_controls
node_window -->|"uses"| node_map_canvas
node_window -->|"hosts"| node_treasure
node_window -->|"hosts"| node_drawing
node_window -->|"hosts"| node_annotations
node_window -->|"hosts"| node_artifacts
node_window -->|"hosts"| node_map_data
node_window -->|"hosts"| node_sailing
node_window -->|"hosts"| node_granger
node_window -->|"hosts"| node_skills
node_window -->|"hosts"| node_tools
node_window -->|"discovers maps"| node_map_variants
node_window -->|"uses"| node_extractor
node_window -->|"uses"| node_matcher
node_controls -.->|"selects type"| node_map_files
node_map_files -.->|"renders"| node_map_canvas
node_treasure -.->|"extracts clue"| node_extractor
node_extractor -.->|"prepares patch"| node_matcher
node_matcher -.->|"returns matches"| node_map_canvas
node_map_canvas -.->|"tracks coordinates"| node_ocr
node_sailing -->|"plots crossings"| node_cluster_layout
node_sailing -->|"loads plans"| node_cluster_drawings
node_map_data -.->|"configures overlays"| node_map_canvas
node_annotations -.->|"uses store"| node_annotation_store
node_artifacts -.->|"uses store"| node_artifact_store
node_drawing -->|"uses store"| node_drawing_store
node_map_canvas -->|"displays drawings"| node_drawing_store
node_map_canvas -->|"displays annotations"| node_annotation_store
node_client_logs -.->|"provides entries"| node_log_parser
node_log_parser -.->|"feeds tracking"| node_skills
node_tools -.->|"runs simulation"| node_grinder
node_tools -.->|"calculates pillars"| node_bridge
node_tools -.->|"calculates improvements"| node_imping
node_player -.->|"evaluates herd"| node_granger
node_player -.->|"records locate casts"| node_artifacts

click node_app "https://github.com/bnorthern42/wurmexplorer/blob/main/src/main.cpp"
click node_window "https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/MainWindow.cpp"
click node_navigation "https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/components/NavigationBar.cpp"
click node_controls "https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/components/TopControlBar.cpp"
click node_map_canvas "https://github.com/bnorthern42/wurmexplorer/blob/main/src/engine/ZoomMapCanvas.cpp"
click node_map_variants "https://github.com/bnorthern42/wurmexplorer/blob/main/src/core/MapVariants.cpp"
click node_sailing "https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/panels/SailingPanel.cpp"
click node_cluster_layout "https://github.com/bnorthern42/wurmexplorer/blob/main/src/models/ClusterLayout.cpp"
click node_cluster_drawings "https://github.com/bnorthern42/wurmexplorer/blob/main/src/models/ClusterDrawingStore.cpp"
click node_treasure "https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/treasure/TreasurePanel.cpp"
click node_extractor "https://github.com/bnorthern42/wurmexplorer/blob/main/src/engine/cv/Extractor.cpp"
click node_matcher "https://github.com/bnorthern42/wurmexplorer/blob/main/src/engine/cv/Matcher.cpp"
click node_ocr "https://github.com/bnorthern42/wurmexplorer/blob/main/src/engine/cv/Ocr.cpp"
click node_granger "https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/granger/GrangerPanel.cpp"
click node_skills "https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/skills/SkillsPanel.cpp"
click node_log_parser "https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/skills/SkillLogParser.cpp"
click node_tools "https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/tools/ToolsPanel.cpp"
click node_grinder "https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/tools/GrinderEngine.cpp"
click node_bridge "https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/tools/BridgePillarCalculator.cpp"
click node_imping "https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/tools/ImpCalculator.cpp"
click node_drawing "https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/drawing/DrawingPanel.cpp"
click node_annotations "https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/panels/AnnotationPanel.cpp"
click node_annotation_store "https://github.com/bnorthern42/wurmexplorer/blob/main/src/models/AnnotationStore.cpp"
click node_artifacts "https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/panels/ArtifactPanel.cpp"
click node_artifact_store "https://github.com/bnorthern42/wurmexplorer/blob/main/src/models/ArtifactStore.cpp"
click node_map_data "https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/panels/MapDataPanel.cpp"
click node_drawing_store "https://github.com/bnorthern42/wurmexplorer/blob/main/src/models/DrawingStore.cpp"

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_app,node_window,node_navigation,node_controls,node_client_logs toneBlue
class node_map_canvas,node_map_variants,node_sailing,node_cluster_layout,node_cluster_drawings,node_drawing toneAmber
class node_treasure,node_extractor,node_matcher,node_ocr toneMint
class node_granger,node_skills,node_log_parser,node_tools,node_grinder,node_bridge,node_imping toneRose
class node_annotations,node_annotation_store,node_artifacts,node_artifact_store,node_map_data,node_drawing_store,node_player,node_map_files toneIndigo
```

## Components

### Desktop UI

- [Application Startup](https://github.com/bnorthern42/wurmexplorer/blob/main/src/main.cpp): `src/main.cpp`
- [Main Window](https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/MainWindow.cpp): `src/ui/MainWindow.cpp`
- [Navigation Bar](https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/components/NavigationBar.cpp): `src/ui/components/NavigationBar.cpp`
- [Map Controls](https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/components/TopControlBar.cpp): `src/ui/components/TopControlBar.cpp`

### Maps and Navigation

- [Deep-Zoom Canvas](https://github.com/bnorthern42/wurmexplorer/blob/main/src/engine/ZoomMapCanvas.cpp): `src/engine/ZoomMapCanvas.cpp`
- [Map Variants](https://github.com/bnorthern42/wurmexplorer/blob/main/src/core/MapVariants.cpp): `src/core/MapVariants.cpp`
- [Sailing Routes](https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/panels/SailingPanel.cpp): `src/ui/panels/SailingPanel.cpp`
- [Cluster Routing](https://github.com/bnorthern42/wurmexplorer/blob/main/src/models/ClusterLayout.cpp): `src/models/ClusterLayout.cpp`
- [Route Overlays](https://github.com/bnorthern42/wurmexplorer/blob/main/src/models/ClusterDrawingStore.cpp): `src/models/ClusterDrawingStore.cpp`
- [Map Drawing](https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/drawing/DrawingPanel.cpp): `src/features/drawing/DrawingPanel.cpp`

### Treasure Vision

- [Treasure Locator](https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/treasure/TreasurePanel.cpp): `src/features/treasure/TreasurePanel.cpp`
- [Clue Extraction](https://github.com/bnorthern42/wurmexplorer/blob/main/src/engine/cv/Extractor.cpp): `src/engine/cv/Extractor.cpp`
- [Terrain Matching](https://github.com/bnorthern42/wurmexplorer/blob/main/src/engine/cv/Matcher.cpp): `src/engine/cv/Matcher.cpp`
- [Coordinate OCR](https://github.com/bnorthern42/wurmexplorer/blob/main/src/engine/cv/Ocr.cpp): `src/engine/cv/Ocr.cpp`

### Player Tools

- [Breeding Evaluator](https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/granger/GrangerPanel.cpp): `src/features/granger/GrangerPanel.cpp`
- [Skills Monitor](https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/skills/SkillsPanel.cpp): `src/features/skills/SkillsPanel.cpp`
- [Skill Log Parser](https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/skills/SkillLogParser.cpp): `src/features/skills/SkillLogParser.cpp`
- [Calculators and Tools](https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/tools/ToolsPanel.cpp): `src/features/tools/ToolsPanel.cpp`
- [Mechanics Simulation](https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/tools/GrinderEngine.cpp): `src/features/tools/GrinderEngine.cpp`
- [Bridge Pillar Math](https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/tools/BridgePillarCalculator.cpp): `src/features/tools/BridgePillarCalculator.cpp`
- [Imping Calculator](https://github.com/bnorthern42/wurmexplorer/blob/main/src/features/tools/ImpCalculator.cpp): `src/features/tools/ImpCalculator.cpp`

### Domain State

- [Map Annotations](https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/panels/AnnotationPanel.cpp): `src/ui/panels/AnnotationPanel.cpp`
- [Annotation Store](https://github.com/bnorthern42/wurmexplorer/blob/main/src/models/AnnotationStore.cpp): `src/models/AnnotationStore.cpp`
- [Artifact Triangulation](https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/panels/ArtifactPanel.cpp): `src/ui/panels/ArtifactPanel.cpp`
- [Artifact Store](https://github.com/bnorthern42/wurmexplorer/blob/main/src/models/ArtifactStore.cpp): `src/models/ArtifactStore.cpp`
- [Map Data and Overlays](https://github.com/bnorthern42/wurmexplorer/blob/main/src/ui/panels/MapDataPanel.cpp): `src/ui/panels/MapDataPanel.cpp`
- [Drawing Store](https://github.com/bnorthern42/wurmexplorer/blob/main/src/models/DrawingStore.cpp): `src/models/DrawingStore.cpp`

### Other components

- **Player**
- **Client Logs**
- **Map Files**

## Connections

- Player → Application Startup: launches (evidence: `src/main.cpp`)
- Application Startup → Main Window: opens (evidence: `src/main.cpp`)
- Main Window → Navigation Bar: creates (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Map Controls: creates (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Deep-Zoom Canvas: uses (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Treasure Locator: hosts (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Map Drawing: hosts (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Map Annotations: hosts (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Artifact Triangulation: hosts (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Map Data and Overlays: hosts (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Sailing Routes: hosts (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Breeding Evaluator: hosts (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Skills Monitor: hosts (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Calculators and Tools: hosts (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Map Variants: discovers maps (evidence: `src/ui/MainWindow.cpp`)
- Main Window → Clue Extraction: uses
- Main Window → Terrain Matching: uses
- Map Controls → Map Files: selects type
- Map Files → Deep-Zoom Canvas: renders
- Treasure Locator → Clue Extraction: extracts clue
- Clue Extraction → Terrain Matching: prepares patch
- Terrain Matching → Deep-Zoom Canvas: returns matches
- Deep-Zoom Canvas → Coordinate OCR: tracks coordinates
- Sailing Routes → Cluster Routing: plots crossings
- Sailing Routes → Route Overlays: loads plans
- Map Data and Overlays → Deep-Zoom Canvas: configures overlays
- Map Annotations → Annotation Store: uses store
- Artifact Triangulation → Artifact Store: uses store
- Map Drawing → Drawing Store: uses store
- Deep-Zoom Canvas → Drawing Store: displays drawings
- Deep-Zoom Canvas → Annotation Store: displays annotations
- Client Logs → Skill Log Parser: provides entries
- Skill Log Parser → Skills Monitor: feeds tracking
- Calculators and Tools → Mechanics Simulation: runs simulation
- Calculators and Tools → Bridge Pillar Math: calculates pillars
- Calculators and Tools → Imping Calculator: calculates improvements
- Player → Breeding Evaluator: evaluates herd
- Player → Artifact Triangulation: records locate casts
