# waycrate/wayshot architecture

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

- Interactive diagram: https://gitdiagram.com/waycrate/wayshot
- Repository: https://github.com/waycrate/wayshot

## Overview

##### Project Type and Purpose
- Project Type: This is a native command-line screenshot tool with a clear separation between its CLI frontend (in the “wayshot” directory) and its core library (in the “libwayshot” directory). It also includes example applications (e.g., waymirror-egl) that demonstrate how to leverage the library.
- Purpose: The tool is designed to capture screenshots in various modes (full screen, cropped, clipboard copying, etc.) for Wayland compositors (using wlroots), with emphasis on performance and native integration.

##### File Structure
- Top-Level Directories and Files:
- “wayshot” directory: Contains the CLI-specific source code (cli.rs, wayshot.rs, utils.rs) plus a Cargo.toml and a build.rs file. This is the main executable component.
- “libwayshot” directory: Provides the reusable library functionality (modules like dispatch.rs, image_util.rs, screencopy.rs, etc.) used by the CLI and examples. It also contains its own README and Cargo.toml.
- “libwayshot/examples”: Contains example projects (e.g., “waymirror-egl”) that illustrate specific use cases and integrations (including shader files for rendering).
- Supporting Files:
- Standard Rust build/configuration files (Cargo.toml, Cargo.lock) indicating a Cargo workspace setup.
- Documentation files (both in docs/ and in libwayshot/README.md) that provide installation, usage, and manpage generation (using scdoc).
- CI/CD workflows and Nix/flake configuration files indicate modern and reproducible build/deployment practices.

##### README for Additional Insights
- The README clearly states that wayshot is a “native, blazing-fast screenshot tool” and includes usage examples (for full screen, cropping, clipboard integration) and portal integration.
- It provides installation details, dependencies, and thanks to key contributors, which emphasize both the integration with Wayland compositors and the modular design where functionality may be accessed as either an executable or a library.

a. Main Components:
- User Interface (CLI): The “wayshot” executable that users interact with.
- Core Library (libwayshot): Handles screenshot capture, image processing, error handling, and platform-specific interactions.
- Examples/Extensions: Sample integrations (e.g., waymirror-egl) that may incorporate GPU resources via shader programs (note the “shaders” directory with frag.glsl and vert.glsl).
- Integration Points: External dependencies such as xdg-desktop-portal-luminous for portal integration and any wlroots-based compositor interfaces.
- Build/Deployment Infrastructure: CI/CD pipelines (.github/workflows), Nix/flake configurations for reproducible builds, and Makefiles for build automation.

b. Relationships and Interactions:
- The CLI layer (wayshot) calls functions from the libwayshot library, making use of its subcomponents (e.g., dispatch, image_util, screencopy, region handling).
- Libwayshot interacts with system-level APIs (via Rust modules and possibly EGL shader components in examples) to capture, process, and output screenshots.
- The example projects demonstrate how additional functionalities (e.g., GPU dispatch via EGL, shader-based processing) are integrated with the library.
- External integrations (such as desktop portals) interact with either the CLI or the underlying library to provide extended services like screenshot and screencast.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: The design cleanly splits user interaction (CLI) from core functionality (library) and further isolates specialized examples.
- Modular and Reusable Components: The libwayshot codebase is organized into specific functional modules (dispatch, error handling, image utilities, etc.) that can be maintained, tested, and reused independently.
- Extensibility: The presence of examples and integrations (like portal integrations) indicates a design that is open to future modifications and extension without overhauling the core.
- Lightweight and Performance-Oriented: Given its purpose and the use of Rust, the system is designed for speed and efficiency, with native integration for hardware-accelerated image processing (as seen in shader usage).

d. Relevant Technologies:
- Rust and Cargo: The programming language and package manager/build tool.
- Make/Nix/flake: Build automation and reproducible environment management.
- scdoc: Used for man-page generation.
- External libraries/integrations: References to wlroots, xdg-desktop-portal, and potentially EGL and shader processing libraries.

- A front-facing CLI component (wayshot) that processes user commands.
- A well-organized core library (libwayshot) that manages the actual screenshot capture and image processing tasks, with clear internal submodules.
- Supporting example modules (e.g., waymirror-egl) that show the library’s integration with advanced rendering techniques.
- External integration points (for Wayland compositors and desktop portals) that emphasize its interaction with native and system-level services.
- Build and deployment configuration components (CI/CD pipelines, Makefile, Nix/flake environment) that ensure reproducible builds and integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User("User"):::external

    subgraph "CLI Layer"
        CLI("CLI (wayshot)"):::cli
        subgraph "CLI Source Files"
            CLI1("cli.rs"):::cli
            CLI2("wayshot.rs"):::cli
            CLI3("utils.rs"):::cli
        end
    end

    subgraph "Core Library Layer"
        LIB("Core Library (libwayshot)"):::library
        subgraph "Library Modules"
            LIB1("dispatch.rs"):::library
            LIB2("image_util.rs"):::library
            LIB3("screencopy.rs"):::library
        end
    end

    subgraph "Example Applications"
        EX("Example: waymirror-egl"):::example
        subgraph "Example Source Files"
            EX1("main.rs"):::example
            EX2("error.rs"):::example
            EX3("dispatch.rs"):::example
            subgraph "Shaders"
                S1("frag.glsl"):::example
                S2("vert.glsl"):::example
            end
        end
    end

    subgraph "External Integrations"
        WL("wlroots Compositor"):::external
        XP("xdg-desktop-portal"):::external
    end

    subgraph "Build & Deployment"
        CI("CI/CD (.github/workflows)"):::build
        MF("Makefile"):::build
        NX("Nix/flake (flake.nix/flake.lock)"):::build
    end

    subgraph "Documentation"
        DOCS("Docs (wayshot.1.scd & wayshot.7.scd)"):::docs
        README("libwayshot/README.md"):::docs
    end

    User -->|"input"| CLI
    CLI -->|"calls"| LIB
    LIB -->|"provides_API"| EX
    LIB -->|"integrates_with"| WL
    LIB -->|"supports"| XP

    %% Click Events
    click CLI "https://github.com/waycrate/wayshot/tree/main/wayshot/"
    click CLI1 "https://github.com/waycrate/wayshot/blob/main/wayshot/src/cli.rs"
    click CLI2 "https://github.com/waycrate/wayshot/blob/main/wayshot/src/wayshot.rs"
    click CLI3 "https://github.com/waycrate/wayshot/blob/main/wayshot/src/utils.rs"
    click LIB "https://github.com/waycrate/wayshot/tree/main/libwayshot/"
    click LIB1 "https://github.com/waycrate/wayshot/blob/main/libwayshot/src/dispatch.rs"
    click LIB2 "https://github.com/waycrate/wayshot/blob/main/libwayshot/src/image_util.rs"
    click LIB3 "https://github.com/waycrate/wayshot/blob/main/libwayshot/src/screencopy.rs"
    click EX "https://github.com/waycrate/wayshot/tree/main/libwayshot/examples/waymirror-egl/"
    click EX1 "https://github.com/waycrate/wayshot/blob/main/libwayshot/examples/waymirror-egl/src/main.rs"
    click EX2 "https://github.com/waycrate/wayshot/blob/main/libwayshot/examples/waymirror-egl/src/error.rs"
    click EX3 "https://github.com/waycrate/wayshot/blob/main/libwayshot/examples/waymirror-egl/src/dispatch.rs"
    click S1 "https://github.com/waycrate/wayshot/blob/main/libwayshot/examples/waymirror-egl/shaders/frag.glsl"
    click S2 "https://github.com/waycrate/wayshot/blob/main/libwayshot/examples/waymirror-egl/shaders/vert.glsl"
    click CI "https://github.com/waycrate/wayshot/tree/main/.github/workflows/"
    click MF "https://github.com/waycrate/wayshot/tree/main/Makefile"
    click NX "https://github.com/waycrate/wayshot/blob/main/flake.nix/flake.lock"
    click DOCS "https://github.com/waycrate/wayshot/tree/main/docs/"
    click README "https://github.com/waycrate/wayshot/blob/main/libwayshot/README.md"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:2px;
    classDef library fill:#ccf,stroke:#333,stroke-width:2px;
    classDef example fill:#cfc,stroke:#333,stroke-width:2px;
    classDef build fill:#fcf,stroke:#333,stroke-width:2px;
    classDef docs fill:#ffc,stroke:#333,stroke-width:2px;
    classDef external fill:#eef,stroke:#333,stroke-width:2px;
```
