# rudjigames/mtuner architecture

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

- Interactive diagram: https://gitdiagram.com/rudjigames/mtuner
- Repository: https://github.com/rudjigames/mtuner

## Overview

1. **What this repo builds**
   MTuner is split into two major runtime sides: a **capture side** that runs with the profiled application and records allocation history, and a **desktop analysis side** that opens the resulting capture and visualizes it. The desktop app is **Qt-based** and is currently functional on **Windows**; the capture SDK is designed to work more broadly.

2. **Top-level code layout**
   The repository is organized around `src/MTuner` for the GUI application, `src/libs` for reusable support libraries, and `src/tools` for auxiliary capture/injection binaries. `3rd/unordered_dense` is a vendored third-party dependency. The rest of the repo is mostly build scripts, resources, and localization assets.

3. **Capture pipeline**
   The capture side centers on **rmem**-style allocator interception. It records every `alloc`, `realloc`, and `free` together with **call stacks, thread IDs, heap/allocator identity, tags, sizes, and timestamps**. The README indicates two deployment modes: **Windows injection** into an existing process, or **SDK linking** into the target application.

4. **Capture file boundary**
   The output of the capture side is a portable **`.MTuner` file**, which is essentially a time-ordered history of memory operations. The capture path is optimized for low overhead: operations are serialized into compact records and written with **LZ4 compression** on a background thread.

5. **Loader and in-memory model**
   Inside the desktop app, the loading boundary is handled by `src/MTuner/src/loader/*` and related classes such as `capturecontext`, `binloaderview`, and `mtunerlib`. These components parse the capture file, reconstruct the operation stream, and build the in-memory analysis model used by the rest of the UI.

6. **Analysis layer**
   After loading, the app computes aggregate structures used for queries and drill-down: allocation statistics, grouped views, stack-trace trees, tag trees, module/thread/heap breakdowns, and the “Insights” findings. The design is explicitly **history-based**, so analysis is done over the whole timeline rather than a single live heap snapshot.

7. **Visualization/UI shell**
   `mtuner.cpp`, `mtunermain.cpp`, `centralwidget`, and the many `*.ui` files define a dockable Qt application with multiple specialized views. The UI includes timeline graphs, histograms, treemaps, stack traces, hotspots, modules, threads, heaps, source, project management, operations lists/search, and the new **Insights** tab.

8. **Visualization widgets as separate subsystems**
   The visual components are implemented as distinct widgets such as `graph*`, `histogram*`, `treemap*`, `stacktrace*`, `stacktreewidget`, `hotspots`, `insightswidget`, and `sourceview`. This separation matters architecturally: each view consumes the same loaded capture model but presents a different projection of the memory history.

9. **Symbol resolution boundary**
   `src/libs/rdebug` and classes like `symbolstore` provide the symbol-resolution layer. On Windows this relies on **PDB/DIA** and the **Microsoft public symbol server**; for GCC/Clang toolchains it uses **addr2line/nm**. That resolution feeds stack traces, source links, and navigation from findings back into code.

10. **Capture/injection tools**
    `src/tools/MTunerCmd`, `MTunerDLL`, and `MTunerInject` are supporting binaries for command-line control, injection, and runtime support. They form the operational boundary between the desktop analyzer and the profiled process, especially for the Windows injection workflow.

11. **Shared support libraries**
    `src/libs/rbase`, `rmem`, `rg_memory`, `rdebug`, and `rqt` look like the reusable substrate for memory utilities, capture/runtime logic, debugging/symbol resolution, and Qt integration. These libraries reduce duplication between the desktop app and the capture-related tools.

12. **Build and packaging architecture**
    The project is built with **GENie/zidar** and requires **Qt** plus **Lua** during generation. The repo includes scripts for Visual Studio 2022 and MinGW generation, AppVeyor CI config, and packaging scripts. Resources include fonts, icons, translations, and Qt resource files, which are all part of the shipped desktop application.

Main entry points: [`src/libs/rmem`](https://github.com/rudjigames/mtuner/tree/master/src/libs/rmem) (rmem SDK), [`src/MTuner/src/mtuner.cpp`](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/mtuner.cpp) (MTuner), [`src/MTuner/src/capturecontext.cpp`](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/capturecontext.cpp) (Capture model), [`src/MTuner/src/graph.cpp`](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/graph.cpp) (Analysis views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop analyzer"]
  node_mtuner_app["MTuner<br/>Qt desktop app<br/>[mtuner.cpp]"]
  node_mtuner_main["Main entry<br/>Qt entrypoint<br/>[mtunermain.cpp]"]
  node_central_widget["Workspace<br/>UI shell<br/>[centralwidget.cpp]"]
  node_loader_boundary["Loader<br/>capture parser<br/>[binloader.cpp]"]
  node_capture_context["Capture model<br/>analysis model<br/>[capturecontext.cpp]"]
  node_analysis_views["Analysis views<br/>visualization suite<br/>[graph.cpp]"]
  node_symbol_resolution["Symbols<br/>symbol resolver<br/>[symbolstore.cpp]"]
  node_project_tools["Project tools<br/>workflow widgets"]
end

subgraph group_capture["Capture runtime"]
  node_capture_sdk[("rmem SDK<br/>capture runtime")]
  node_injector["Injection<br/>process hook"]
  node_cmd_tool["MTunerCmd<br/>control tool"]
  node_dll_runtime["MTunerDLL<br/>runtime DLL"]
end

subgraph group_libs["Shared libraries"]
  node_rbase["rbase<br/>core utilities"]
  node_rg_memory["rg_memory<br/>memory utils"]
  node_rdebug["rdebug<br/>debug symbols"]
  node_rqt["rqt<br/>Qt helpers"]
end

subgraph group_build["Build & packaging"]
  node_genie_scripts["Genie scripts<br/>build gen<br/>[genie.lua]"]
  node_packaging["Packaging<br/>release scripts<br/>[MTunerPack.bat]"]
end

node_unordered_dense["unordered_dense<br/>vendored dep"]

node_mtuner_app -->|"starts at"| node_mtuner_main
node_mtuner_main -->|"hosts"| node_central_widget
node_mtuner_app -->|"opens MTuner"| node_loader_boundary
node_loader_boundary -->|"builds"| node_capture_context
node_capture_context -->|"feeds"| node_analysis_views
node_capture_context -->|"exposes"| node_project_tools
node_capture_context -->|"resolves through"| node_symbol_resolution
node_analysis_views -->|"drills into"| node_symbol_resolution
node_analysis_views -->|"rendered in"| node_central_widget
node_project_tools -->|"integrated in"| node_central_widget
node_injector -->|"deploys"| node_capture_sdk
node_cmd_tool -->|"controls"| node_capture_sdk
node_dll_runtime -->|"supports"| node_capture_sdk
node_capture_sdk -->|"emits files for"| node_loader_boundary
node_rdebug -->|"provides"| node_symbol_resolution
node_rbase -->|"supports"| node_capture_sdk
node_rg_memory -->|"supports"| node_capture_sdk
node_rqt -->|"supports"| node_mtuner_app
node_genie_scripts -->|"generates"| node_mtuner_app
node_packaging -->|"packages"| node_mtuner_app
node_unordered_dense -.->|"dependency"| node_capture_sdk

click node_mtuner_app "https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/mtuner.cpp"
click node_mtuner_main "https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/mtunermain.cpp"
click node_central_widget "https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/centralwidget.cpp"
click node_loader_boundary "https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/loader/binloader.cpp"
click node_capture_context "https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/capturecontext.cpp"
click node_analysis_views "https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/graph.cpp"
click node_symbol_resolution "https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/symbolstore.cpp"
click node_project_tools "https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/projectsmanager.cpp"
click node_capture_sdk "https://github.com/rudjigames/mtuner/tree/master/src/libs/rmem"
click node_injector "https://github.com/rudjigames/mtuner/tree/master/src/tools/MTunerInject"
click node_cmd_tool "https://github.com/rudjigames/mtuner/tree/master/src/tools/MTunerCmd"
click node_dll_runtime "https://github.com/rudjigames/mtuner/tree/master/src/tools/MTunerDLL"
click node_rbase "https://github.com/rudjigames/mtuner/tree/master/src/libs/rbase"
click node_rg_memory "https://github.com/rudjigames/mtuner/tree/master/src/libs/rg_memory"
click node_rdebug "https://github.com/rudjigames/mtuner/tree/master/src/libs/rdebug"
click node_rqt "https://github.com/rudjigames/mtuner/tree/master/src/libs/rqt"
click node_unordered_dense "https://github.com/rudjigames/mtuner/tree/master/3rd/unordered_dense"
click node_genie_scripts "https://github.com/rudjigames/mtuner/blob/master/src/MTuner/scripts/genie.lua"
click node_packaging "https://github.com/rudjigames/mtuner/blob/master/scripts/MTunerPack.bat"

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_mtuner_app,node_mtuner_main,node_central_widget,node_loader_boundary,node_capture_context,node_analysis_views,node_symbol_resolution,node_project_tools toneBlue
class node_capture_sdk,node_injector,node_cmd_tool,node_dll_runtime toneAmber
class node_rbase,node_rg_memory,node_rdebug,node_rqt toneMint
class node_genie_scripts,node_packaging toneRose
class node_unordered_dense toneNeutral
```

## Components

### Desktop analyzer

Qt application for loading and exploring capture files

- [MTuner](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/mtuner.cpp): Qt desktop app · Main analysis application shell and entrypoint · `src/MTuner/src/mtuner.cpp`
- [Main entry](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/mtunermain.cpp): Qt entrypoint · Application startup and main window bootstrap · `src/MTuner/src/mtunermain.cpp`
- [Workspace](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/centralwidget.cpp): UI shell · Dockable central workspace hosting the major views · `src/MTuner/src/centralwidget.cpp`
- [Loader](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/loader/binloader.cpp): capture parser · Loads MTuner files and reconstructs the operation stream · `src/MTuner/src/loader/binloader.cpp`
- [Capture model](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/capturecontext.cpp): analysis model · In-memory capture context and history-based analysis state · `src/MTuner/src/capturecontext.cpp`
- [Analysis views](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/graph.cpp): visualization suite · Timeline, histograms, treemap, stack, hotspots, and insights projections · `src/MTuner/src/graph.cpp`
- [Symbols](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/symbolstore.cpp): symbol resolver · Resolves stacks and source locations across toolchains · `src/MTuner/src/symbolstore.cpp`
- [Project tools](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/src/projectsmanager.cpp): workflow widgets · Project management, search, operations, and source navigation · `src/MTuner/src/projectsmanager.cpp`

### Capture runtime

Injection and SDK-side recording of memory operations

- [rmem SDK](https://github.com/rudjigames/mtuner/tree/master/src/libs/rmem): capture runtime · Allocator interception and low-overhead memory event recording · `src/libs/rmem`
- [Injection](https://github.com/rudjigames/mtuner/tree/master/src/tools/MTunerInject): process hook · Windows injection and runtime hookup into profiled processes · `src/tools/MTunerInject`
- [MTunerCmd](https://github.com/rudjigames/mtuner/tree/master/src/tools/MTunerCmd): control tool · Command-line control and operational helper for capture workflows · `src/tools/MTunerCmd`
- [MTunerDLL](https://github.com/rudjigames/mtuner/tree/master/src/tools/MTunerDLL): runtime DLL · Supporting DLL for capture or injection deployment · `src/tools/MTunerDLL`

### Shared libraries

Reusable support libraries used across analyzer and tools

- [rbase](https://github.com/rudjigames/mtuner/tree/master/src/libs/rbase): core utilities · Shared base utilities and low-level helpers · `src/libs/rbase`
- [rg_memory](https://github.com/rudjigames/mtuner/tree/master/src/libs/rg_memory): memory utils · Reusable memory-related support code · `src/libs/rg_memory`
- [rdebug](https://github.com/rudjigames/mtuner/tree/master/src/libs/rdebug): debug symbols · Debug and symbol-resolution substrate used by analysis · `src/libs/rdebug`
- [rqt](https://github.com/rudjigames/mtuner/tree/master/src/libs/rqt): Qt helpers · Qt integration helpers and shared UI support · `src/libs/rqt`

### Build & packaging

Generation, packaging, and release support

- [Genie scripts](https://github.com/rudjigames/mtuner/blob/master/src/MTuner/scripts/genie.lua): build gen · Build generation logic and project setup scripts · `src/MTuner/scripts/genie.lua`
- [Packaging](https://github.com/rudjigames/mtuner/blob/master/scripts/MTunerPack.bat): release scripts · Build, packaging, and CI automation scripts · `scripts/MTunerPack.bat`

### Other components

- [unordered_dense](https://github.com/rudjigames/mtuner/tree/master/3rd/unordered_dense): vendored dep · Third-party dense hash map dependency · `3rd/unordered_dense`

## Connections

- MTuner → Main entry: starts at · Application entrypoint initializes the desktop app
- Main entry → Workspace: hosts · Main window embeds the dockable workspace
- MTuner → Loader: opens MTuner · Loads capture files into the analysis pipeline
- Loader → Capture model: builds · Reconstructs the in-memory capture model from the file stream
- Capture model → Analysis views: feeds · Provides the shared model consumed by visual projections
- Capture model → Project tools: exposes · Backs operations, search, and navigation workflows
- Capture model → Symbols: resolves through · Connects stacks and findings to source and symbols
- Analysis views → Symbols: drills into · Stack and source views depend on resolved symbols
- Analysis views → Workspace: rendered in · Major analysis widgets live inside the main workspace
- Project tools → Workspace: integrated in · Workflow widgets are surfaced in the dockable shell
- Injection → rmem SDK: deploys · Injection path activates the capture runtime in target processes
- MTunerCmd → rmem SDK: controls · Command-line tooling supports the capture workflow
- MTunerDLL → rmem SDK: supports · DLL boundary participates in runtime capture deployment
- rmem SDK → Loader: emits files for · Serialized memory history becomes the MTuner capture file
- rdebug → Symbols: provides · Shared debug/symbol infrastructure underpins resolution
- rbase → rmem SDK: supports · Common utilities reused by runtime components
- rg_memory → rmem SDK: supports · Memory-oriented helpers shared by capture code
- rqt → MTuner: supports · Qt helper layer used by the desktop application
- Genie scripts → MTuner: generates · Build generation creates the application projects
- Packaging → MTuner: packages · Release scripts assemble the desktop application
- unordered_dense → rmem SDK: dependency · Vendored hash container used by internal components