# coatisoftware/sourcetrail architecture

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

- Interactive diagram: https://gitdiagram.com/coatisoftware/sourcetrail
- Repository: https://github.com/coatisoftware/sourcetrail

## Overview

##### Project Type & Purpose
- Sourcetrail is a cross-platform desktop application (C++/Qt) for exploring source code.
- It comprises a GUI front-end, a core application engine, and optional language indexer back-ends (C/C++, Java, Python).

##### High-Level File-Structure Analysis
- Top level:
- CMakeLists.txt & cmake/ – build orchestration
- src/app – application entrypoint (main.cpp)
- src/lib – core engine libraries (messaging, storage, data model, project management, settings)
- src/lib_gui – Qt-based UI layer (views, controllers, widgets, project wizard)
- src/lib_cxx, src/lib_java, src/lib_python – language-specific indexers and project support modules
- src/indexer – main dispatcher for external indexer processes
- src/external – bundled third-party libraries (Catch2, SQLite, TinyXML)
- deployment/, setup/, script/ – packaging, installation, CI scripts
- src/test, bin/test – automated tests and test data (Catch2 suites)

##### Core Architecture Components
a. Front-end GUI (src/lib_gui + src/app)
- Qt application, windows, views, controllers
- Implements MVC: controllers handle input/messages, views render data
b. Core Engine (src/lib)
- Messaging bus (inter-module events)
- Task scheduler (indexing, parsing, storage tasks)
- Data model & graph storage (SQLite via storage/sqlite)
- Project management (source group detection, custom commands)
- Settings & migration
c. Language Indexers
- In-process or child processes spawned via src/indexer
- C/C++: uses lib_cxx (Clang AST, compile database)
- Java: uses lib_java (JNI + Gradle tooling API)
- Python: uses prebuilt indexer (downloadable via script)
d. Storage Layer
- Intermediate shared memory (interprocess)
- Persistent SQLite database (SourcetrailDB schema)
- Full-text search index
e. External Dependencies
- Boost (filesystem, IPC), Qt (GUI & process launching), Clang, JDK/Maven, Python indexer

##### Components & Data Flow
1. User launches GUI (Qt) → core engine initializes
2. User opens a project → core bus broadcasts MessageLoadProject
3. Core engine schedules indexing tasks → indexer process(es) start via src/indexer
4. Indexer(s) parse source → emit SharedIndexerCommand via IPC into IntermediateStorage
5. Core engine polls IPC queue → merges data into persistent SQLite storage
6. UI controllers subscribe to data change messages → query storage layer
7. Views update: code view, graph view, search view, history, bookmarks, etc.

##### Architectural Patterns & Principles
- Modular layered architecture: separation of GUI, core, indexers, storage
- MVC/MVP in UI (controllers ↔ views ↔ data)
- Plugin-style language packages loaded by LanguagePackageManager
- Messaging / event-driven communication internally (MessageQueue)
- Build & deployment abstractions via CMake & scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "GUI Layer"
        direction TB
        Main["Application Entrypoint\nmain.cpp"]:::frontend
        UI["Qt-based UI Layer"]:::frontend
    end

    subgraph "Core Engine"
        direction TB
        CoreApp["Core Application &\nLanguage Packages"]:::core
        ComponentModel["Component Model\n(Controllers & Views)"]:::core
        ProjectMgmt["Project Management"]:::core
        Settings["Settings &\nMigrations"]:::core
        Messaging["Core Message Bus"]:::core
        Scheduler["Task Scheduler"]:::core
        DataModel["Data Model & Graph Storage"]:::core
    end

    subgraph "Language Indexers"
        direction TB
        Dispatcher["Indexer Dispatcher"]:::indexer
        Cxx["C/C++ Indexer"]:::indexer
        Java["Java Indexer"]:::indexer
        Python["Python Indexer"]:::indexer
    end

    subgraph "Storage Layer"
        direction TB
        Intermediate["Intermediate Shared Storage"]:::storage
        SQLite["SQLite-backed Storage"]:::storage
        FullText["Full-Text Search Index"]:::storage
    end

    subgraph "External Dependencies"
        direction TB
        ExternalLibs["Bundled Third-Party Libs"]:::external
        AppData["Runtime Data & Resources"]:::external
        Build["Build Orchestration"]:::external
    end

    %% Flow
    Main -->|"launch GUI"| Messaging
    UI -->|"user commands"| Messaging
    Messaging -->|"schedule tasks"| Scheduler
    Scheduler -->|"spawn indexers"| Dispatcher
    Dispatcher -->|"launch"| Cxx
    Dispatcher -->|"launch"| Java
    Dispatcher -->|"launch"| Python
    Cxx -->|"IndexerCommand via IPC"| Intermediate
    Java -->|"IndexerCommand via IPC"| Intermediate
    Python -->|"IndexerCommand via IPC"| Intermediate
    Intermediate -->|"poll & merge"| DataModel
    DataModel -->|"write/read"| SQLite
    DataModel -->|"update"| FullText
    DataModel -->|"notify"| ComponentModel
    ComponentModel -->|"render"| UI

    %% Click Events
    click Main "https://github.com/coatisoftware/sourcetrail/blob/master/src/app/main.cpp"
    click UI "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib_gui/"
    click CoreApp "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib/app/"
    click ComponentModel "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib/component/"
    click ProjectMgmt "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib/project/"
    click Settings "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib/settings/"
    click Messaging "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib/utility/messaging/"
    click Scheduler "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib/utility/scheduling/"
    click DataModel "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib/data/graph/"
    click FullText "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib/data/fulltextsearch/"
    click Intermediate "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib/data/storage/"
    click SQLite "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib/data/storage/sqlite/"
    click Dispatcher "https://github.com/coatisoftware/sourcetrail/tree/master/src/indexer/"
    click Cxx "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib_cxx/"
    click Java "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib_java/"
    click Python "https://github.com/coatisoftware/sourcetrail/tree/master/src/lib_python/"
    click ExternalLibs "https://github.com/coatisoftware/sourcetrail/tree/master/src/external/"
    click AppData "https://github.com/coatisoftware/sourcetrail/tree/master/bin/app/data/"
    click Build "https://github.com/coatisoftware/sourcetrail/blob/master/CMakeLists.txt"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#1E90FF,color:#000
    classDef core fill:#90EE90,stroke:#008000,color:#000
    classDef indexer fill:#FFA500,stroke:#FF8C00,color:#000
    classDef storage fill:#D2B48C,stroke:#A0522D,color:#000
    classDef external fill:#D3D3D3,stroke:#696969,color:#000
```
