# albertlauncher/albert architecture

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

- Interactive diagram: https://gitdiagram.com/albertlauncher/albert
- Repository: https://github.com/albertlauncher/albert

## Overview

##### Project Type and Purpose
- Albert is a desktop-agnostic, plugin-based keyboard launcher written in C++/Qt.
- It consists of a core engine (query processing, plugin management), a Qt front end (UI), and many extension plugins.

##### Top-Level Architectural Components
a. Frontend (Qt GUI & IPC)
- Directory: `src/frontend`, plus Qt UI files under `src/settings`.
- Responsibilities: capture user keystrokes, display results, forward queries.
b. Core Engine
- Subsystems:
– Query Engine (`src/query`): processes queries, orchestrates handlers.
– Plugin Framework (`src/plugin`, `include/albert/*`): loads plugins, manages metadata, resolves dependencies.
– RPC Server (`src/app/rpcserver`): optional inter-process control.
– Telemetry & Logging (`src/app/telemetry*`, `include/albert/logging.h`).
c. Extensions (Plugins)
- Directory: `plugins/*`
- Each plugin implements `Extension`, `QueryHandler` or `TriggerQueryHandler` interfaces.
- Loaded at runtime by `PluginLoader`/`PluginProvider`.
d. Platform Abstraction
- Directory: `src/platform`
e. Utilities & Shared Models
- Directory: `src/util`, `src/common`: shared types (`Item`, `Action`), algorithms (Levenshtein), indexers.
f. Settings UI
- Directory: `src/settings`: MVC pattern for preferences dialogs.
g. External Services & Resources
- Telemetry endpoint (optional).
h. Build & Distribution
- CMake (`CMakeLists.txt`, `cmake/`), Dockerfiles (`.docker/`), Flatpak, macOS bundles (`dist/`).

##### Relationships & Data Flow
- User input → Frontend
- Frontend emits query → Core Query Engine
- Query Engine → Global/Trigger/Fallback handlers (in core & plugins)
- Handlers consult Plugin instances → return `Item`/`Action` objects
- Query Engine ranks `Items` → returns to Frontend
- Frontend renders list → User selects → Action invoked (via Core or Plugin)
- Core dispatches telemetry/logs, writes usage DB

##### Architectural Patterns & Principles
- Plugin-based architecture: loose coupling between core and extension code.
- Registry/Factory pattern for plugin discovery (`ExtensionRegistry`, `PluginRegistry`).
- Separation of concerns: Frontend vs. Core vs. Platform vs. Plugins.
- MVC in settings UI.
- Use of asynchronous execution (`BackgroundExecutor`) to avoid blocking UI.

- Clear component names (use the same terms: Frontend, QueryEngine, PluginLoader, ExtensionPlugin, PlatformAbstraction, TelemetryProvider).
- Annotations for major technologies: “Qt5/6”, “C++17”, “CMake”, “Docker/Flatpak”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Frontend["Frontend (Qt GUI & IPC)"]:::frontend
        SettingsUI["Settings UI (MVC)"]:::frontend
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        QueryEngine["QueryEngine"]:::core
        subgraph "Plugin Framework"
            direction TB
            PluginLoader["PluginLoader"]:::core
            PluginProvider["PluginProvider"]:::core
            ExtensionRegistry["ExtensionRegistry"]:::core
            ExtensionPlugin["ExtensionPlugin Interface"]:::core
        end
        RPCServer["RPCServer"]:::core
        Telemetry["Telemetry"]:::core
        Logging["Logging"]:::core
    end

    %% Plugins
    subgraph "Extensions (Plugins)"
        direction TB
        Plugins["Plugins"]:::plugin
    end

    %% Platform Abstraction
    Platform["Platform Abstraction"]:::platform

    %% Utilities & Shared Models
    subgraph "Utilities & Shared Models"
        direction TB
        Util["Util"]:::util
        Common["Common"]:::util
    end

    %% Build & Distribution
    subgraph "Build & Distribution"
        direction TB
        CMake["CMakeLists.txt"]:::build
        CMakeDir["cmake/"]:::build
        Docker[".docker/"]:::build
        Dist["dist/"]:::build
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        OS["OS/Desktop Env"]:::external
        FS["Filesystem/DB"]:::external
        TelemetryEndpoint["Telemetry Endpoint"]:::external
    end

    %% Data & Control Flows
    User -->|"input"| Frontend
    Frontend -->|"emit query"| QueryEngine
    QueryEngine -->|"load plugins"| PluginLoader
    PluginLoader --> Plugins
    PluginLoader --> PluginProvider
    PluginProvider --> ExtensionRegistry
    ExtensionRegistry --> ExtensionPlugin
    QueryEngine -->|"invoke handlers"| ExtensionPlugin
    ExtensionPlugin -->|"return Items/Actions"| QueryEngine
    QueryEngine -->|"results"| Frontend
    Frontend -->|"selection"| QueryEngine
    QueryEngine -->|"execute action"| ExtensionPlugin
    QueryEngine -->|"log/telemetry"| Telemetry
    Telemetry --> Logging
    Telemetry --> FS
    QueryEngine --> RPCServer
    Platform -->|"provides services"| Frontend
    Platform -->|"provides services"| QueryEngine
    Util --> QueryEngine
    Common --> QueryEngine
    Build --> Frontend
    Build --> Core
    Build --> Plugins

    %% OS Integrations
    OS --> Platform
    FS --> Platform
    FS --> Telemetry

    %% Click Events
    click Frontend "https://github.com/albertlauncher/albert/tree/main/src/frontend"
    click SettingsUI "https://github.com/albertlauncher/albert/tree/main/src/settings"
    click QueryEngine "https://github.com/albertlauncher/albert/tree/main/src/query"
    click PluginLoader "https://github.com/albertlauncher/albert/blob/main/include/albert/pluginloader.h"
    click PluginProvider "https://github.com/albertlauncher/albert/blob/main/include/albert/pluginprovider.h"
    click ExtensionRegistry "https://github.com/albertlauncher/albert/blob/main/include/albert/extensionregistry.h"
    click ExtensionPlugin "https://github.com/albertlauncher/albert/blob/main/include/albert/extensionplugin.h"
    click RPCServer "https://github.com/albertlauncher/albert/blob/main/src/app/rpcserver.cpp"
    click Telemetry "https://github.com/albertlauncher/albert/blob/main/src/app/telemetry.cpp"
    click Logging "https://github.com/albertlauncher/albert/blob/main/include/albert/logging.h"
    click Plugins "https://github.com/albertlauncher/albert/tree/main/plugins/"
    click Platform "https://github.com/albertlauncher/albert/tree/main/src/platform"
    click Util "https://github.com/albertlauncher/albert/tree/main/src/util"
    click Common "https://github.com/albertlauncher/albert/tree/main/src/common"
    click CMake "https://github.com/albertlauncher/albert/blob/main/CMakeLists.txt"
    click CMakeDir "https://github.com/albertlauncher/albert/tree/main/cmake/"
    click Docker "https://github.com/albertlauncher/albert/tree/main/.docker/"
    click Dist "https://github.com/albertlauncher/albert/tree/main/dist/"

    %% Styles
    classDef frontend fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6cf,stroke:#333,stroke-width:1px
    classDef plugin fill:#fc6,stroke:#333,stroke-width:1px
    classDef platform fill:#f96,stroke:#333,stroke-width:1px
    classDef util fill:#96f,stroke:#333,stroke-width:1px
    classDef build fill:#f9c,stroke:#333,stroke-width:1px
    classDef external fill:#ccc,stroke:#333,stroke-width:1px
```
