How quarkslab/numbatui works
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: IndexerBase.cpp Index pipeline · QtApplication.cpp Qt adapter · Application.cpp App runtime · test_main.cpp Tests
Components 20
Runtime
Executable entrypoints and long-running app processes
Core
Domain model, workflows, storage, and utilities
- App runtime · Application bootstrap, language package loading, and path wiring
src/lib/app/Application.cpp - Project config · Project state, source groups, preferences, and migrations
src/lib/project/Project.cpp - Domain data · Nodes, edges, locations, names, bookmarks, search, tooltips, and status data
src/lib/data/graph/Graph.cpp - Storage · Persistent and intermediate storage with SQLite backends and migrations
src/lib/data/storage/Storage.cpp - Index pipeline · Parsing, command queues, storage injection, merge, cleanup, and index build tasks
src/lib/data/indexer/IndexerBase.cpp - IPC boundary · Shared memory and command/status managers between UI and indexer process
src/lib/data/indexer/interprocess/InterprocessIndexer.cpp - Scheduler · Reusable task runner, sequencing, branching, and blackboard execution
src/lib/utility/scheduling/TaskScheduler.cpp - Messaging · Typed application messages used across controllers, views, and workflow state
src/lib/utility/messaging/MessageQueue.cpp - Files · File, path, text, codec, timestamp, and OS utility support
src/lib/utility/file/FileSystem.cpp - Components · Generic component, controller, view, tab, and network factories
src/lib/component/ComponentManager.cpp
UI
Qt presentation layer and adapters
- Qt adapter · Qt application wrappers, windows, widgets, dialogs, and graphics views
src/lib_gui/qt/QtApplication.cpp - Graph UI · Qt graph nodes, edges, styles, and focus handling
src/lib_gui/qt/graphics/QtGraphicsView.cpp - Project wizard · 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 · Clang-based indexing, compilation-database handling, and C++ source-group support
src/lib_cxx/LanguagePackageCxx.cpp - Python package · Python source-group and indexing support
src/lib_python/project/SourceGroupFactoryModulePython.cpp
Assets
Runtime resources, templates, and sample projects
- Runtime assets · Application templates, color schemes, GUI resources, fonts, and sample projects
bin/app/data/ProjectSettings_template.xml
Infra
Build, packaging, and test infrastructure
- Tests · Architecture-level unit and interaction suites for storage, parsing, graphing, search, and UI workflows
src/test/test_main.cpp - Build & package · CMake, Docker, scripts, and platform packaging assets
CMakeLists.txt
Connections 30
- 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