# quarkslab/numbatui architecture

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

- Interactive diagram: https://gitdiagram.com/quarkslab/numbatui
- Repository: https://github.com/quarkslab/numbatui

## Overview

1. This repository is a desktop source-code/graph explorer, forked from Sourcetrail and adapted for Numbat-generated graph databases. The main runtime is a Qt GUI application written in C++, with separate support for indexing, persistence, and optional language-specific parsers.

2. The top-level executable is the GUI app in `src/app`. It boots the application, loads a `.srctrlprj` project file, and hands control to the core library. A separate executable in `src/indexer` performs indexing work off the main UI thread/process boundary.

3. The code is split into a reusable core library in `src/lib`, GUI-specific Qt bindings in `src/lib_gui`, and optional language packages in `src/lib_cxx` and `src/lib_python`. This separation is important: the core owns the domain model and workflows, while the GUI layer only adapts those concepts to Qt widgets, windows, and graphics items.

4. The central domain model lives in `src/lib/data`: graph nodes/edges/tokens, source locations, names, bookmarks, search matches, tooltips, and error/status metadata. This is the data shape that flows through the whole app, from parsing/indexing into storage, then back out into views like graph, code, search, and history.

5. Persistence is handled by `src/lib/data/storage`, with SQLite-backed implementations under `src/lib/data/storage/sqlite`. The storage layer also includes migrations and access/cache wrappers, so project state, index data, bookmarks, and related metadata survive across runs and can be upgraded over time.

6. Indexing is modeled as a task pipeline. Core task classes in `src/lib/data/indexer` and `src/lib/data/parser` orchestrate command queues, parsing, storage injection, merging, and cleanup. For C++, `src/lib_cxx` adds Clang-based parsing and compilation-database handling; for Python, `src/lib_python` provides a separate language package path. These language packages feed the same core storage/index abstractions.

7. The app uses an interprocess boundary for indexing and progress reporting. `src/lib/data/indexer/interprocess` plus `src/lib/utility/interprocess` and shared-memory helpers coordinate commands, intermediate storage, and status between the UI process and the indexer process. This is the main architectural boundary for long-running work and responsive UI behavior.

8. User interaction is organized around a component/controller/view split in `src/lib/component`. Controllers handle behavior and state changes; views render those states; components connect the two. The app supports graph, code, search, tabs, status bar, bookmarks, tooltips, refresh, undo/redo, custom trail, and screen-search subsystems, each with matching controller/view pairs.

9. The Qt layer in `src/lib_gui` adapts the generic component system to actual windows, graphics items, dialogs, and widgets. It also includes platform-specific Qt application wrappers, custom graph rendering, project wizard screens, path detection helpers, and IDE/network communication pieces. In diagram terms, this is the presentation adapter between the domain/component model and the OS GUI.

10. Input projects are configured through `src/lib/project` and `src/lib/settings`. Projects contain source groups, source paths, exclude filters, language settings, and refresh info; settings cover application preferences, color schemes, and migrations. The repo also includes sample projects and GUI resources under `bin/app/data` and `bin/app/user`, showing that runtime assets, templates, and user project data are part of the product architecture, not just build artifacts.

11. Auxiliary infrastructure matters because it shapes deployment: CMake drives the build, Docker is provided for Linux execution, and setup/package scripts target Linux, macOS, and Windows. External libraries are vendored or integrated in `src/external`, notably SQLite, TinyXML, and Catch for tests, while Clang/LLVM and Qt are the major system dependencies.

12. Tests are broad and architecture-revealing. `src/test` covers file/path utilities, parsers, storage, search, graph/layout, messaging, schedulers, settings, shared memory, and language-specific indexing, while `testing/` contains UI/interaction fixtures and expected outputs. That implies the codebase is designed around stable domain APIs with thin UI wrappers and explicit workflow pipelines.

Main entry points: [`src/lib/data/indexer/IndexerBase.cpp`](https://github.com/quarkslab/numbatui/blob/main/src/lib/data/indexer/IndexerBase.cpp) (Index pipeline), [`src/lib_gui/qt/QtApplication.cpp`](https://github.com/quarkslab/numbatui/blob/main/src/lib_gui/qt/QtApplication.cpp) (Qt adapter), [`src/lib/app/Application.cpp`](https://github.com/quarkslab/numbatui/blob/main/src/lib/app/Application.cpp) (App runtime), [`src/test/test_main.cpp`](https://github.com/quarkslab/numbatui/blob/main/src/test/test_main.cpp) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app_main(("App<br/>Qt desktop entry<br/>[main.cpp]"))
  node_indexer_main(("Indexer<br/>worker entry<br/>[main.cpp]"))
end

subgraph group_core["Core"]
  node_app_runtime["App runtime<br/>application shell<br/>[Application.cpp]"]
  node_project_settings["Project config<br/>project/settings model<br/>[Project.cpp]"]
  node_domain_data["Domain data<br/>graph/storage model<br/>[Graph.cpp]"]
  node_storage[("Storage<br/>persistence layer<br/>[Storage.cpp]")]
  node_indexing_tasks["Index pipeline<br/>task pipeline<br/>[IndexerBase.cpp]"]
  node_ipc_boundary["IPC boundary<br/>interprocess sync"]
  node_scheduler["Scheduler<br/>task system<br/>[TaskScheduler.cpp]"]
  node_messaging["Messaging<br/>event bus<br/>[MessageQueue.cpp]"]
  node_filesystem["Files<br/>path/fs utilities<br/>[FileSystem.cpp]"]
  node_component_model["Components<br/>component framework"]
end

subgraph group_ui["UI"]
  node_ui_qt["Qt adapter<br/>Qt presentation<br/>[QtApplication.cpp]"]
  node_graph_rendering["Graph UI<br/>graph presentation<br/>[QtGraphicsView.cpp]"]
  node_project_wizard["Project wizard<br/>Qt setup flow"]
end

subgraph group_lang["Language packages"]
  node_cxx_package["C++ package<br/>language extension"]
  node_python_package["Python package<br/>language extension"]
end

subgraph group_assets["Assets"]
  node_assets_runtime["Runtime assets<br/>product assets"]
end

subgraph group_infra["Infra"]
  node_tests["Tests<br/>validation suite<br/>[test_main.cpp]"]
  node_build_packaging["Build & package<br/>build/deploy<br/>[CMakeLists.txt]"]
end

node_app_main -->|"boots"| node_app_runtime
node_app_runtime -->|"loads"| node_project_settings
node_app_runtime -->|"assembles"| node_component_model
node_app_runtime -->|"adapts"| node_ui_qt
node_indexer_main -->|"runs"| node_indexing_tasks
node_indexing_tasks -->|"produces"| node_domain_data
node_indexing_tasks -->|"writes"| node_storage
node_indexing_tasks -->|"reports"| node_ipc_boundary
node_ipc_boundary -->|"translates"| node_messaging
node_component_model -->|"uses"| node_messaging
node_component_model -->|"binds"| node_ui_qt
node_ui_qt -->|"renders"| node_graph_rendering
node_ui_qt -->|"configures"| node_project_wizard
node_ui_qt -->|"loads"| node_assets_runtime
node_project_settings -->|"persists"| node_storage
node_project_settings -->|"specializes"| node_cxx_package
node_project_settings -->|"specializes"| node_python_package
node_cxx_package -->|"feeds"| node_indexing_tasks
node_python_package -->|"feeds"| node_indexing_tasks
node_domain_data -->|"stored in"| node_storage
node_domain_data -->|"broadcast via"| node_messaging
node_scheduler -->|"orchestrates"| node_indexing_tasks
node_filesystem -->|"supports"| node_app_runtime
node_tests -.->|"covers"| node_domain_data
node_tests -.->|"covers"| node_storage
node_tests -.->|"covers"| node_indexing_tasks
node_tests -.->|"covers"| node_ui_qt
node_build_packaging -->|"builds"| node_app_main
node_build_packaging -->|"builds"| node_indexer_main
node_build_packaging -->|"packages"| node_assets_runtime

click node_app_main "https://github.com/quarkslab/numbatui/blob/main/src/app/main.cpp"
click node_indexer_main "https://github.com/quarkslab/numbatui/blob/main/src/indexer/main.cpp"
click node_app_runtime "https://github.com/quarkslab/numbatui/blob/main/src/lib/app/Application.cpp"
click node_project_settings "https://github.com/quarkslab/numbatui/blob/main/src/lib/project/Project.cpp"
click node_domain_data "https://github.com/quarkslab/numbatui/blob/main/src/lib/data/graph/Graph.cpp"
click node_storage "https://github.com/quarkslab/numbatui/blob/main/src/lib/data/storage/Storage.cpp"
click node_indexing_tasks "https://github.com/quarkslab/numbatui/blob/main/src/lib/data/indexer/IndexerBase.cpp"
click node_ipc_boundary "https://github.com/quarkslab/numbatui/blob/main/src/lib/data/indexer/interprocess/InterprocessIndexer.cpp"
click node_scheduler "https://github.com/quarkslab/numbatui/blob/main/src/lib/utility/scheduling/TaskScheduler.cpp"
click node_messaging "https://github.com/quarkslab/numbatui/blob/main/src/lib/utility/messaging/MessageQueue.cpp"
click node_filesystem "https://github.com/quarkslab/numbatui/blob/main/src/lib/utility/file/FileSystem.cpp"
click node_component_model "https://github.com/quarkslab/numbatui/blob/main/src/lib/component/ComponentManager.cpp"
click node_ui_qt "https://github.com/quarkslab/numbatui/blob/main/src/lib_gui/qt/QtApplication.cpp"
click node_graph_rendering "https://github.com/quarkslab/numbatui/blob/main/src/lib_gui/qt/graphics/QtGraphicsView.cpp"
click node_project_wizard "https://github.com/quarkslab/numbatui/blob/main/src/lib_gui/qt/project_wizard/QtProjectWizard.cpp"
click node_cxx_package "https://github.com/quarkslab/numbatui/blob/main/src/lib_cxx/LanguagePackageCxx.cpp"
click node_python_package "https://github.com/quarkslab/numbatui/blob/main/src/lib_python/project/SourceGroupFactoryModulePython.cpp"
click node_assets_runtime "https://github.com/quarkslab/numbatui/blob/main/bin/app/data/ProjectSettings_template.xml"
click node_tests "https://github.com/quarkslab/numbatui/blob/main/src/test/test_main.cpp"
click node_build_packaging "https://github.com/quarkslab/numbatui/blob/main/CMakeLists.txt"

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_main,node_indexer_main toneBlue
class node_app_runtime,node_project_settings,node_domain_data,node_storage,node_indexing_tasks,node_ipc_boundary,node_scheduler,node_messaging,node_filesystem,node_component_model toneAmber
class node_ui_qt,node_graph_rendering,node_project_wizard toneMint
class node_cxx_package,node_python_package toneRose
class node_assets_runtime toneIndigo
class node_tests,node_build_packaging toneTeal
```

## Components

### Runtime

Executable entrypoints and long-running app processes

- [App](https://github.com/quarkslab/numbatui/blob/main/src/app/main.cpp): Qt desktop entry · Boots the GUI application and loads projects · `src/app/main.cpp`
- [Indexer](https://github.com/quarkslab/numbatui/blob/main/src/indexer/main.cpp): worker entry · Separate process for background indexing · `src/indexer/main.cpp`

### Core

Domain model, workflows, storage, and utilities

- [App runtime](https://github.com/quarkslab/numbatui/blob/main/src/lib/app/Application.cpp): application shell · Application bootstrap, language package loading, and path wiring · `src/lib/app/Application.cpp`
- [Project config](https://github.com/quarkslab/numbatui/blob/main/src/lib/project/Project.cpp): project/settings model · Project state, source groups, preferences, and migrations · `src/lib/project/Project.cpp`
- [Domain data](https://github.com/quarkslab/numbatui/blob/main/src/lib/data/graph/Graph.cpp): graph/storage model · Nodes, edges, locations, names, bookmarks, search, tooltips, and status data · `src/lib/data/graph/Graph.cpp`
- [Storage](https://github.com/quarkslab/numbatui/blob/main/src/lib/data/storage/Storage.cpp): persistence layer · Persistent and intermediate storage with SQLite backends and migrations · `src/lib/data/storage/Storage.cpp`
- [Index pipeline](https://github.com/quarkslab/numbatui/blob/main/src/lib/data/indexer/IndexerBase.cpp): task pipeline · Parsing, command queues, storage injection, merge, cleanup, and index build tasks · `src/lib/data/indexer/IndexerBase.cpp`
- [IPC boundary](https://github.com/quarkslab/numbatui/blob/main/src/lib/data/indexer/interprocess/InterprocessIndexer.cpp): interprocess sync · Shared memory and command/status managers between UI and indexer process · `src/lib/data/indexer/interprocess/InterprocessIndexer.cpp`
- [Scheduler](https://github.com/quarkslab/numbatui/blob/main/src/lib/utility/scheduling/TaskScheduler.cpp): task system · Reusable task runner, sequencing, branching, and blackboard execution · `src/lib/utility/scheduling/TaskScheduler.cpp`
- [Messaging](https://github.com/quarkslab/numbatui/blob/main/src/lib/utility/messaging/MessageQueue.cpp): event bus · Typed application messages used across controllers, views, and workflow state · `src/lib/utility/messaging/MessageQueue.cpp`
- [Files](https://github.com/quarkslab/numbatui/blob/main/src/lib/utility/file/FileSystem.cpp): path/fs utilities · File, path, text, codec, timestamp, and OS utility support · `src/lib/utility/file/FileSystem.cpp`
- [Components](https://github.com/quarkslab/numbatui/blob/main/src/lib/component/ComponentManager.cpp): component framework · Generic component, controller, view, tab, and network factories · `src/lib/component/ComponentManager.cpp`

### UI

Qt presentation layer and adapters

- [Qt adapter](https://github.com/quarkslab/numbatui/blob/main/src/lib_gui/qt/QtApplication.cpp): Qt presentation · Qt application wrappers, windows, widgets, dialogs, and graphics views · `src/lib_gui/qt/QtApplication.cpp`
- [Graph UI](https://github.com/quarkslab/numbatui/blob/main/src/lib_gui/qt/graphics/QtGraphicsView.cpp): graph presentation · Qt graph nodes, edges, styles, and focus handling · `src/lib_gui/qt/graphics/QtGraphicsView.cpp`
- [Project wizard](https://github.com/quarkslab/numbatui/blob/main/src/lib_gui/qt/project_wizard/QtProjectWizard.cpp): Qt setup flow · Project creation and source-group configuration screens · `src/lib_gui/qt/project_wizard/QtProjectWizard.cpp`

### Language packages

Optional language-specific indexing and parsing extensions

- [C++ package](https://github.com/quarkslab/numbatui/blob/main/src/lib_cxx/LanguagePackageCxx.cpp): language extension · Clang-based indexing, compilation-database handling, and C++ source-group support · `src/lib_cxx/LanguagePackageCxx.cpp`
- [Python package](https://github.com/quarkslab/numbatui/blob/main/src/lib_python/project/SourceGroupFactoryModulePython.cpp): language extension · Python source-group and indexing support · `src/lib_python/project/SourceGroupFactoryModulePython.cpp`

### Assets

Runtime resources, templates, and sample projects

- [Runtime assets](https://github.com/quarkslab/numbatui/blob/main/bin/app/data/ProjectSettings_template.xml): product assets · Application templates, color schemes, GUI resources, fonts, and sample projects · `bin/app/data/ProjectSettings_template.xml`

### Infra

Build, packaging, and test infrastructure

- [Tests](https://github.com/quarkslab/numbatui/blob/main/src/test/test_main.cpp): validation suite · Architecture-level unit and interaction suites for storage, parsing, graphing, search, and UI workflows · `src/test/test_main.cpp`
- [Build & package](https://github.com/quarkslab/numbatui/blob/main/CMakeLists.txt): build/deploy · CMake, Docker, scripts, and platform packaging assets · `CMakeLists.txt`

## Connections

- App → App runtime: boots · GUI executable enters the reusable application runtime
- App runtime → Project config: loads · Application startup reads projects and settings
- App runtime → Components: assembles · Application composes controllers, views, and tabs
- App runtime → Qt adapter: adapts · Qt layer hosts the runtime UI shell
- Indexer → Index pipeline: runs · Indexer executable executes the indexing pipeline
- Index pipeline → Domain data: produces · Parsing and indexing fill the shared domain model
- Index pipeline → Storage: writes · Indexing stages persist intermediate and final data
- Index pipeline → IPC boundary: reports · Background work communicates progress and commands across process boundaries
- IPC boundary → Messaging: translates · IPC status integrates with the app message flow
- Components → Messaging: uses · Controllers and views communicate via typed messages
- Components → Qt adapter: binds · Generic components are rendered as Qt widgets and windows
- Qt adapter → Graph UI: renders · Qt presentation includes graph-specific visuals and interaction
- Qt adapter → Project wizard: configures · Qt flow guides project and source-group setup
- Qt adapter → Runtime assets: loads · Runtime resources and templates feed the interface
- Project config → Storage: persists · Project and settings state survive across runs
- Project config → C++ package: specializes · C++ project settings extend the base project model
- Project config → Python package: specializes · Python project settings extend the base project model
- C++ package → Index pipeline: feeds · C++ parsing plugs into the shared indexing pipeline
- Python package → Index pipeline: feeds · Python parsing plugs into the shared indexing pipeline
- Domain data → Storage: stored in · Core graph, locations, bookmarks, and search data are persisted
- Domain data → Messaging: broadcast via · Domain changes are surfaced through messages
- Scheduler → Index pipeline: orchestrates · Task framework powers index and parsing workflows
- Files → App runtime: supports · Filesystem and text utilities underpin project loading and resource handling
- Tests → Domain data: covers · Tests exercise the central domain APIs and workflows
- Tests → Storage: covers · Tests validate persistence and migrations
- Tests → Index pipeline: covers · Tests validate parser and indexing pipelines
- Tests → Qt adapter: covers · UI interaction tests exercise the Qt layer
- Build & package → App: builds · Build and packaging targets produce the desktop app
- Build & package → Indexer: builds · Build and packaging targets produce the worker executable
- Build & package → Runtime assets: packages · Runtime data and templates are shipped with the product
