# tomahawk-player/tomahawk architecture

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

- Interactive diagram: https://gitdiagram.com/tomahawk-player/tomahawk
- Repository: https://github.com/tomahawk-player/tomahawk

## Overview

##### Main Logical Layers & Components
- Presentation Layer (Qt UI)
– TomahawkApp, TomahawkWindow, dialogs, viewpages, widgets
– Event handling, user interactions, view controllers
- Core Layer (libtomahawk)
– PluginLoader & ModuleManager
– AccountManager & account plugins (Spotify, Google, XMPP, Zeroconf, etc.)
– ResolverEngine & script/native resolvers (JS, playdar, external)
– InfoSystem & info plugins (MusicBrainz, Echonest, Discogs…)
– Pipeline (job queue / asynchronous tasks)
– AudioEngine (wraps libVLC, output streams)
– Network layer (ConnectionManager, Servent for P2P, HTTP, WebSocket)
– Database subsystem (SQLite via DatabaseWorker, commands, schema, migrations, fuzzy index)
– Collection & Metadata modules (MusicScanner, Tag handlers, Collection API)
- External Interfaces
– Local file system (scanning local library)
– Subscription services (Spotify, Beats, Google Music, TIDAL…)
– Free platforms (SoundCloud, YouTube, Bandcamp…)
– P2P network of other Tomahawk peers (Servent)
– System services (notifications, media keys, UPower)
- Support Tools & Build Infrastructure
– CrashReporter (separate process)
– CMake / CPack build scripts, packaging modules, Docker scripts
– Tests (unit tests for database, network, etc.)

##### Relationships & Data Flows
- UI → Core
– User actions (search, play, browse) invoke Core APIs (Pipeline)
– Core pushes updates (model changes, job status) back to UI viewpages
- Core → Database
– Queries & commands flow from Pipeline to DatabaseWorker (SQLite)
– Database schema updates, migrations under data/sql
- Core → Network & External Services
– ResolverEngine dispatches network requests (HTTP, WebSocket) via ConnectionManager
– Servent handles P2P discovery and streaming
- Core → AudioEngine
– Pipeline tasks hand off media URLs/streams to AudioEngine for playback
- Plugin Loader → Plugins
– Dynamically loads account, info, resolver, viewpage, widget plugins at runtime

##### Architectural Patterns
- Plugin architecture (DLLs / Qt plugins) – dynamic extension points for accounts, resolvers, info, viewpages
- Model-View-Controller / Model-View-Delegate in UI (Qt’s MVC using models, views, delegates)
- Pipeline / Job queue pattern for async tasks (indexing, network calls, database commands)
- Layered separation (UI / Core / Data / External)
- Repository + Factory patterns in resolvers and accounts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        UIApp["TomahawkApp"]:::ui
        UIWindow["TomahawkWindow"]:::ui
        Dialogs["Dialogs & View Controllers"]:::ui
        Widgets["Custom Widgets"]:::ui
    end

    %% Core Layer
    subgraph "Core Layer (libtomahawk)"
        direction TB
        Pipeline["Pipeline"]:::core
        PluginLoader["PluginLoader"]:::plugin
        subgraph "Accounts Subsystem"
            direction TB
            AccountManager["AccountManager"]:::core
        end
        subgraph "Resolver Engine"
            direction TB
            ResolverEngine["ResolverEngine"]:::core
        end
        subgraph "InfoSystem"
            direction TB
            InfoSystem["InfoSystem"]:::core
        end
        subgraph "Network & P2P"
            direction TB
            ConnectionManager["ConnectionManager"]:::core
            Servent["Servent"]:::core
        end
        subgraph "Audio Engine"
            direction TB
            AudioEngine["AudioEngine"]:::core
        end
        subgraph "Database Subsystem"
            direction TB
            DatabaseWorker["DatabaseWorker"]:::db
        end
        subgraph "Collection & Metadata"
            direction TB
            Collection["Collection"]:::core
        end
    end

    %% Data & External Interfaces
    subgraph "Data & External Interfaces"
        direction TB
        SQLiteDB["SQLite Database"]:::db
        LocalFS["Local File System"]:::ext
        Subscription["Subscription Services"]:::ext
        FreePlatforms["Free Platforms"]:::ext
        P2PPeers["Tomahawk Peers (P2P)"]:::ext
        SystemServices["System Services"]:::ext
        CrashReporter["CrashReporter Process"]:::ext
    end

    %% Relationships
    UIApp -->|launches| UIWindow
    UIWindow -->|opens| Dialogs
    UIWindow -->|hosts| Widgets
    UIWindow -->|calls| Pipeline

    Pipeline -->|executes tasks| DatabaseWorker
    Pipeline -->|hands off streams| AudioEngine
    Pipeline -->|dispatches requests| ConnectionManager
    Pipeline -->|loads plugins| PluginLoader

    PluginLoader -->|provides| AccountManager
    PluginLoader -->|provides| ResolverEngine
    PluginLoader -->|provides| InfoSystem

    ResolverEngine -->|HTTP/WebSocket| ConnectionManager
    Servent -->|P2P TCP| P2PPeers
    ConnectionManager -->|HTTP| Subscription
    ConnectionManager -->|HTTP| FreePlatforms

    DatabaseWorker -->|reads/writes| SQLiteDB
    Collection -->|stores metadata| DatabaseWorker
    LocalFS -->|scan library| Collection

    AudioEngine -->|plays via libVLC| SystemServices

    CrashReporter -->|reports| Pipeline

    %% Callbacks
    Pipeline -- "updates" --> UIWindow

    %% Click Events
    click UIApp "https://github.com/tomahawk-player/tomahawk/blob/master/src/tomahawk/TomahawkApp.cpp"
    click UIWindow "https://github.com/tomahawk-player/tomahawk/blob/master/src/tomahawk/TomahawkWindow.cpp"
    click Dialogs "https://github.com/tomahawk-player/tomahawk/blob/master/src/tomahawk/dialogs/SettingsDialog.cpp"
    click Dialogs "https://github.com/tomahawk-player/tomahawk/blob/master/src/tomahawk/dialogs/DiagnosticsDialog.cpp"
    click Widgets "https://github.com/tomahawk-player/tomahawk/blob/master/src/tomahawk/widgets/AccountWidget.cpp"
    click PluginLoader "https://github.com/tomahawk-player/tomahawk/blob/master/src/libtomahawk/utils/PluginLoader.cpp"
    click AccountManager "https://github.com/tomahawk-player/tomahawk/blob/master/src/libtomahawk/accounts/AccountManager.cpp"
    click ResolverEngine "https://github.com/tomahawk-player/tomahawk/blob/master/src/libtomahawk/resolvers/Resolver.cpp"
    click InfoSystem "https://github.com/tomahawk-player/tomahawk/blob/master/src/libtomahawk/infosystem/InfoSystem.cpp"
    click ConnectionManager "https://github.com/tomahawk-player/tomahawk/blob/master/src/libtomahawk/network/ConnectionManager.cpp"
    click Servent "https://github.com/tomahawk-player/tomahawk/blob/master/src/libtomahawk/network/Servent.cpp"
    click AudioEngine "https://github.com/tomahawk-player/tomahawk/blob/master/src/libtomahawk/audio/AudioEngine.cpp"
    click DatabaseWorker "https://github.com/tomahawk-player/tomahawk/blob/master/src/libtomahawk/database/DatabaseWorker.cpp"
    click Collection "https://github.com/tomahawk-player/tomahawk/blob/master/src/libtomahawk/collection/Collection.cpp"
    click CrashReporter "https://github.com/tomahawk-player/tomahawk/blob/master/src/crashreporter/main.cpp"

    %% Styles
    classDef ui fill:#e0ffe0,stroke:#333,stroke-width:1px
    classDef core fill:#e0f0ff,stroke:#333,stroke-width:1px
    classDef db fill:#ffe0b3,stroke:#333,stroke-width:1px
    classDef ext fill:#ffffcc,stroke:#333,stroke-width:1px
    classDef plugin fill:#f0f0f0,stroke:#333,stroke-width:1px
```
