# whysobad/hyprland-preview-share-picker architecture

> Architecture diagram of the GitHub repository whysobad/hyprland-preview-share-picker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whysobad/hyprland-preview-share-picker
- Repository: https://github.com/whysobad/hyprland-preview-share-picker

## Overview

Based on our analysis of the provided file tree and README, this project is an alternative share picker for the Hyprland window manager that integrates with xdg-desktop-portal-hyprland. It is written in Rust and clearly separates the core logic (located in the lib subproject) from the application aspects (in the src directory). The library encapsulates the toolkit-independent and Wayland/Hyprland-specific logic (e.g., handling protocols and image processing), while the application layer handles the configuration, command-line interface, and GTK4-based GUI creation.

##### Main Components & Their Roles
- Application Layer:
- Represented by the src directory files (main.rs, app.rs, cli.rs, config.rs, util.rs, and the views subdirectory). This is responsible for initializing the GUI (via GTK4 and gtk4-layer-shell integration) and handling user interactions.
- The CLI and configuration management (reading the YAML config file, applying style customizations and setting window properties) are also processed here.
- Core Library (lib subproject):
- Contains the protocol implementations, image processing, error handling, frame/buffer management, and other toolkit-independent logic.
- Examined in lib/src folder, it provides the abstraction over Hyprland protocols (see the protocols directory for hyprland_toplevel_export_v1.rs and mod.rs) and encapsulates the essential functionality that can be reused in custom frontends.
- External Services & Dependencies:
- GTK4 and gtk4-layer-shell: used for rendering the GUI widgets and managing the front-end layout.
- xdg-desktop-portal-hyprland: the protocol integration ensures that the share picker is invoked as part of the Hyprland ecosystem.
- hyprland itself, as well as the external tool “slurp” (for region selection via command-line call).
- Build and Packaging Components:
- The Cargo.toml files in both the project root and the lib subproject, along with build.rs, manage dependencies and build configuration. The PKGBUILD (in README) also describes how the tool is packaged and installed in Arch Linux environments.

##### Relationships and Interactions
- The Application Layer acts as the orchestrator: It starts up the GUI application (src/main.rs) and uses the CLI and configuration modules (src/cli.rs and src/config.rs) to load settings.
- The GUI interacts with the Core Library to display previews for windows and outputs. For example, image processing modules (src/image.rs and lib/src/image.rs) are responsible for resizing images and rendering them in the view.
- The lib subproject, being consumed as a Git submodule and compiled with the main binary, provides a clear interface to Hyprland protocols (handled in lib/src/protocols) that are crucial for integration with the Wayland-based environment.
- There is a clear separation between platform-independent logic (in lib) and the GTK frontend (in src), which allows for potential custom frontends if desired.

##### Architectural Patterns and Technologies
- Layered Architecture:
- Presentation/GUI Layer (GTK4-based).
- Business/Domain Logic Layer (Core functionalities in lib).
- Configuration and CLI Layer – handling application settings and command-line invocations.
- Modularity: The separation into "lib" and "src" shows that the application is designed to allow easy reuse of non-UI logic, consistent with good modular design principles.
- External Integration: The use of standard tools like “slurp” for region capture, xdg-desktop-portal configurations, and Nightly Rust toolchain indicate reliance on external dependencies and careful configuration management.

##### Key Architectural Patterns to Emphasize
- Separation of concerns via distinct modules for business logic and UI.
- Modularity with a clear API between the lib subproject (which can be reused in custom frontends) and the UI.
- Integration with external systems (Wayland protocols, xdg-desktop-portal configuration, and external tools like “slurp”) as clearly defined components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main project container
    subgraph "hyprland-preview-share-picker"
        %% Application Layer
        subgraph "Application Layer"
            MA["Main Application (src/main.rs)"]:::appInternal
            APP["App Module (src/app.rs)"]:::appInternal
            CLI["CLI Module (src/cli.rs)"]:::appInternal
            CFG["Configuration (src/config.rs)"]:::appInternal
            UTIL["Utility Functions (src/util.rs)"]:::appInternal
            %% GUI / View Components subgraph
            subgraph "GUI / View Components"
                VIEWS["Views (src/views)"]:::gui
            end
        end

        %% Core Library
        subgraph "Core Library"
            LIB["Core Library (lib)"]:::library
            BUF["Buffer Module"]:::library
            FRM["Frame Module"]:::library
            IMG["Image Processing"]:::library
            ERR["Error Handling"]:::library
            TL["Toplevel Management"]:::library
            OUT["Output Module"]:::library
            %% Hyprland Protocol Integration subgraph
            subgraph "Hyprland Protocol Integration"
                PROT["Protocol Modules"]:::protocol
            end
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        GTK["GTK4 & gtk4-layer-shell"]:::external
        XDG["xdg-desktop-portal-hyprland"]:::external
        HYP["Hyprland"]:::external
        SLURP["Slurp (region selection)"]:::external
    end

    %% Build and Packaging
    subgraph "Build & Packaging"
        ROOT_TOML["Root Cargo.toml"]:::build
        LIB_TOML["lib/Cargo.toml"]:::build
        BUILD_RS["build.rs"]:::build
        PKGBUILD["PKGBUILD (Arch packaging)"]:::build
    end

    %% Relationships within Application Layer
    MA -->|"init"| CLI
    MA -->|"init"| CFG
    MA -->|"init"| APP
    MA -->|"init"| UTIL
    MA -->|"launch_GUI"| VIEWS

    %% Application Layer interacting with Core Library
    VIEWS -->|"render_preview"| LIB
    CFG -->|"config_data"| LIB

    %% Core Library internal dependency
    LIB -->|"protocol_calls"| PROT

    %% External Dependencies interactions
    VIEWS -->|"uses_GUI"| GTK
    VIEWS -->|"portal_integration"| XDG
    CLI -->|"invoke_region_selection"| SLURP
    LIB -->|"wayland_integration"| HYP

    %% Build and Packaging relationships
    ROOT_TOML -->|"builds"| MA
    ROOT_TOML -->|"builds"| LIB
    LIB_TOML -->|"builds"| LIB
    BUILD_RS -->|"build_script"| LIB
    PKGBUILD -->|"packages"| ROOT_TOML

    %% Styles for clarity
    classDef appInternal fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef library fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef gui fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef protocol fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef build fill:#FAD7A0,stroke:#D35400,stroke-width:2px;

    %% Click Events for Application Layer components
    click MA "https://github.com/whysobad/hyprland-preview-share-picker/blob/master/src/main.rs"
    click APP "https://github.com/whysobad/hyprland-preview-share-picker/blob/master/src/app.rs"
    click CLI "https://github.com/whysobad/hyprland-preview-share-picker/blob/master/src/cli.rs"
    click CFG "https://github.com/whysobad/hyprland-preview-share-picker/blob/master/src/config.rs"
    click UTIL "https://github.com/whysobad/hyprland-preview-share-picker/blob/master/src/util.rs"
    click VIEWS "https://github.com/whysobad/hyprland-preview-share-picker/tree/master/src/views"

    %% Click Events for Core Library components
    click LIB "https://github.com/whysobad/hyprland-preview-share-picker/tree/master/lib/src"
    click PROT "https://github.com/whysobad/hyprland-preview-share-picker/tree/master/lib/src/protocols"

    %% Click Events for Build and Packaging components
    click ROOT_TOML "https://github.com/whysobad/hyprland-preview-share-picker/blob/master/Cargo.toml"
    click LIB_TOML "https://github.com/whysobad/hyprland-preview-share-picker/blob/master/lib/Cargo.toml"
    click BUILD_RS "https://github.com/whysobad/hyprland-preview-share-picker/blob/master/build.rs"
```
