# kojix2/gpscan_viewer architecture

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

- Interactive diagram: https://gitdiagram.com/kojix2/gpscan_viewer
- Repository: https://github.com/kojix2/gpscan_viewer

## Overview

1. **What this repo is**
   - `gpscan_viewer` is a small **Qt 6 desktop application** for viewing GrandPerspective-compatible scan XML files, including XML emitted by `gpscan`.
   - Architecturally, it is a **single native GUI app** with a narrow pipeline: **XML input → in-memory tree model → layout computation → custom canvas rendering**.

2. **Top-level runtime boundary**
   - The executable entry point is `src/main.cpp`.
   - From there, the app boots a Qt application and creates the main window/UI shell defined in `ViewerWindow.*`.
   - There is no backend service or network layer; all data is local file input and in-process rendering.

3. **Input and parsing subsystem**
   - `src/TreeReader.*` is the ingestion layer for the scan XML format.
   - It is responsible for turning on-disk XML into the internal tree structure consumed by the rest of the app.
   - `resources/sample.xml` serves as a bundled example input and is useful for understanding expected file shape.

4. **Core data model**
   - `src/TreeModel.*` holds the logical representation of the scan tree.
   - This is the central domain object that bridges parsing, layout, and rendering.
   - The model likely stores hierarchy, sizes/weights, and metadata needed to draw treemap-style boxes.

5. **Layout / geometry subsystem**
   - `src/TreeLayout.*` computes the 2D arrangement of the tree nodes for display.
   - This layer transforms the logical hierarchy into screen-space rectangles or regions.
   - It is the key boundary between “data” and “visualization,” and probably encapsulates treemap layout rules.

6. **Rendering subsystem**
   - `src/CanvasWidget.*` is the custom Qt widget that performs drawing.
   - It consumes the layout/model output and paints the visualization in the main window.
   - This widget is the main interactive surface of the application and the likely place for zoom/selection handling if present.

7. **Visual styling and color mapping**
   - `src/Palette.*` centralizes color selection for the visualization.
   - This is a separate concern from layout so the app can vary appearance without changing geometry.
   - It likely maps node attributes or categories to colors used by the canvas renderer.

8. **UI composition**
   - `src/ViewerWindow.*` is the application shell that connects parsing, model state, and the canvas.
   - It is the main coordination layer for user actions such as opening a file and refreshing the view.
   - The window likely owns or references the central model and the canvas widget.

9. **Shared utilities**
   - `src/Utils.*` contains cross-cutting helper functions used across parsing, layout, or rendering.
   - Keeping these helpers separate prevents the domain modules from accumulating incidental logic.

10. **Data flow through the app**
   - The primary flow is: **XML file** → `TreeReader` → `TreeModel` → `TreeLayout` → `CanvasWidget` → on-screen visualization.
   - `Palette` influences the final visual output during rendering, but does not alter the underlying data model.
   - `ViewerWindow` coordinates the handoff between these stages.

11. **Build and packaging boundary**
   - The project is built with **CMake** (`CMakeLists.txt`) and depends on **Qt 6** and **zlib** as noted in the README.
   - The build also supports packaging via CPack for **DEB/RPM** outputs.
   - This matters architecturally because the repo is designed as a native distributable GUI tool, not a library or service.

12. **Testing and automation**
   - `tests/TestMain.cpp` indicates a dedicated test entry point, suggesting a Qt/CMake test target rather than end-to-end UI automation.
   - GitHub Actions workflows in `.github/workflows/` provide CI build validation and screenshot-related automation.
   - That implies the repo values regression checking around both compilation and visual output.

13. **Desktop integration**
   - `resources/gpscan_viewer.desktop` shows this app is intended to integrate with desktop environments on Linux.
   - The `resources/` directory also reinforces that the project is packaged as a desktop utility with sample assets rather than a service or library.

14. **Overall architecture to diagram**
   - A good diagram would show four main zones: **file input/parsing**, **domain model**, **layout/rendering**, and **Qt windowing/UI**.
   - The central flow is strictly one-way from parsed XML into visual state, with the main window orchestrating user interaction around that pipeline.

Main entry points: [`src/ViewerWindow.h`](https://github.com/kojix2/gpscan_viewer/blob/main/src/ViewerWindow.h) (Viewer Window), [`src/TreeReader.h`](https://github.com/kojix2/gpscan_viewer/blob/main/src/TreeReader.h) (Tree Reader), [`src/CanvasWidget.h`](https://github.com/kojix2/gpscan_viewer/blob/main/src/CanvasWidget.h) (Canvas Widget), [`src/TreeModel.h`](https://github.com/kojix2/gpscan_viewer/blob/main/src/TreeModel.h) (Tree Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Qt app"]
  node_main(("Main<br/>entrypoint<br/>[main.cpp]"))
  node_window["Viewer Window<br/>ui shell<br/>[ViewerWindow.h]"]
end

subgraph group_pipeline["Scan pipeline"]
  node_reader["Tree Reader<br/>xml parser<br/>[TreeReader.h]"]
  node_model["Tree Model<br/>domain model<br/>[TreeModel.h]"]
  node_layout{{"Tree Layout<br/>geometry<br/>[TreeLayout.h]"}}
  node_canvas["Canvas Widget<br/>custom widget<br/>[CanvasWidget.h]"]
  node_palette(("Palette<br/>color mapping<br/>[Palette.h]"))
  node_utils["Utils<br/>helpers<br/>[Utils.h]"]
  node_sample["Sample XML<br/>fixture<br/>[sample.xml]"]
end

subgraph group_build["Build & CI"]
  node_cmake["CMake<br/>build system<br/>[CMakeLists.txt]"]
  node_tests(("Test Main<br/>test entry<br/>[TestMain.cpp]"))
  node_ci["CI Workflows<br/>automation<br/>[build.yml]"]
  node_desktop["Desktop File<br/>packaging"]
end

node_main -->|"creates"| node_window
node_window -->|"loads"| node_reader
node_reader -->|"builds"| node_model
node_model -->|"feeds"| node_layout
node_layout -->|"renders"| node_canvas
node_model -->|"supplies"| node_canvas
node_palette -->|"colors"| node_canvas
node_window -->|"hosts"| node_canvas
node_utils -.->|"supports"| node_reader
node_utils -.->|"supports"| node_layout
node_cmake -->|"builds"| node_main
node_cmake -->|"builds"| node_tests
node_ci -.->|"checks"| node_cmake
node_desktop -.->|"integrates"| node_window
node_sample -.->|"exercises"| node_reader

click node_main "https://github.com/kojix2/gpscan_viewer/blob/main/src/main.cpp"
click node_window "https://github.com/kojix2/gpscan_viewer/blob/main/src/ViewerWindow.h"
click node_reader "https://github.com/kojix2/gpscan_viewer/blob/main/src/TreeReader.h"
click node_model "https://github.com/kojix2/gpscan_viewer/blob/main/src/TreeModel.h"
click node_layout "https://github.com/kojix2/gpscan_viewer/blob/main/src/TreeLayout.h"
click node_canvas "https://github.com/kojix2/gpscan_viewer/blob/main/src/CanvasWidget.h"
click node_palette "https://github.com/kojix2/gpscan_viewer/blob/main/src/Palette.h"
click node_utils "https://github.com/kojix2/gpscan_viewer/blob/main/src/Utils.h"
click node_sample "https://github.com/kojix2/gpscan_viewer/blob/main/resources/sample.xml"
click node_cmake "https://github.com/kojix2/gpscan_viewer/blob/main/CMakeLists.txt"
click node_tests "https://github.com/kojix2/gpscan_viewer/blob/main/tests/TestMain.cpp"
click node_ci "https://github.com/kojix2/gpscan_viewer/blob/main/.github/workflows/build.yml"
click node_desktop "https://github.com/kojix2/gpscan_viewer/blob/main/resources/gpscan_viewer.desktop"

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,node_window toneBlue
class node_reader,node_model,node_layout,node_canvas,node_palette,node_utils,node_sample toneAmber
class node_cmake,node_tests,node_ci,node_desktop toneMint
```

## Components

### Qt app

Desktop application runtime and UI shell

- [Main](https://github.com/kojix2/gpscan_viewer/blob/main/src/main.cpp): entrypoint · Qt application startup and window creation · `src/main.cpp`
- [Viewer Window](https://github.com/kojix2/gpscan_viewer/blob/main/src/ViewerWindow.h): ui shell · Main window that coordinates file loading and view updates · `src/ViewerWindow.h`

### Scan pipeline

XML ingestion, model, layout, and rendering

- [Tree Reader](https://github.com/kojix2/gpscan_viewer/blob/main/src/TreeReader.h): xml parser · Reads GrandPerspective-compatible scan XML into memory · `src/TreeReader.h`
- [Tree Model](https://github.com/kojix2/gpscan_viewer/blob/main/src/TreeModel.h): domain model · In-memory hierarchy and node metadata used by the app · `src/TreeModel.h`
- [Tree Layout](https://github.com/kojix2/gpscan_viewer/blob/main/src/TreeLayout.h): geometry · Computes display rectangles for the tree visualization · `src/TreeLayout.h`
- [Canvas Widget](https://github.com/kojix2/gpscan_viewer/blob/main/src/CanvasWidget.h): custom widget · Paints the treemap and handles interactive view behavior · `src/CanvasWidget.h`
- [Palette](https://github.com/kojix2/gpscan_viewer/blob/main/src/Palette.h): color mapping · Centralized color selection for visual rendering · `src/Palette.h`
- [Utils](https://github.com/kojix2/gpscan_viewer/blob/main/src/Utils.h): helpers · Shared helper routines used across the app · `src/Utils.h`
- [Sample XML](https://github.com/kojix2/gpscan_viewer/blob/main/resources/sample.xml): fixture · Bundled example scan file showing the expected input shape · `resources/sample.xml`

### Build & CI

Build configuration, tests, and automation

- [CMake](https://github.com/kojix2/gpscan_viewer/blob/main/CMakeLists.txt): build system · Project build and packaging configuration · `CMakeLists.txt`
- [Test Main](https://github.com/kojix2/gpscan_viewer/blob/main/tests/TestMain.cpp): test entry · Dedicated test target entry point · `tests/TestMain.cpp`
- [CI Workflows](https://github.com/kojix2/gpscan_viewer/blob/main/.github/workflows/build.yml): automation · GitHub Actions builds and screenshot regression automation · `.github/workflows/build.yml`
- [Desktop File](https://github.com/kojix2/gpscan_viewer/blob/main/resources/gpscan_viewer.desktop): packaging · Linux desktop integration metadata · `resources/gpscan_viewer.desktop`

## Connections

- Main → Viewer Window: creates · Application startup instantiates the main window
- Viewer Window → Tree Reader: loads · Window triggers XML import for opened files
- Tree Reader → Tree Model: builds · Parsed XML becomes the in-memory tree model
- Tree Model → Tree Layout: feeds · Logical tree data is transformed into display geometry
- Tree Layout → Canvas Widget: renders · Computed rectangles are painted on the custom widget
- Tree Model → Canvas Widget: supplies · The canvas consumes model state for drawing and selection
- Palette → Canvas Widget: colors · Color mapping is applied during painting
- Viewer Window → Canvas Widget: hosts · Main window embeds the drawing surface
- Utils → Tree Reader: supports · Shared helpers assist parsing and data handling
- Utils → Tree Layout: supports · Shared helpers assist layout calculations
- CMake → Main: builds · CMake config defines the application target
- CMake → Test Main: builds · CMake config defines the test target
- CI Workflows → CMake: checks · Automation validates builds and visual regressions
- Desktop File → Viewer Window: integrates · Desktop entry exposes the app in native environments
- Sample XML → Tree Reader: exercises · Bundled sample demonstrates the input format
