# kbumsik/virtscreen architecture

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

- Interactive diagram: https://gitdiagram.com/kbumsik/virtscreen
- Repository: https://github.com/kbumsik/virtscreen

## Overview

##### Main Components

- User Interface (GUI) Component:
- Represents the primary interaction layer with the user.
- Includes the PyQt5-based system tray app and QML-defined windows (assets directory with AppWindow.qml, DisplayOptionsDialog.qml, etc.).

- Command-Line Interface (CLI) Component:
- Provides a way to start/configure the virtual screen without the GUI.
- Tied into the same backend methods as the GUI, sharing common configurations.

- Virtual Screen Manager:
- Core logic for creating and controlling the virtual screen.
- Modules include display.py, process.py, and qt_backend.py, which orchestrate the functionality.
- The xrandr.py module likely handles screen configuration using XRandR.

- External Dependencies and Services:
- The project uses external tools like x11vnc to serve the virtual screen as a VNC session.
- XRandR is used to manage the display properties of the virtual screen.

- Packaging/Deployment Layer:
- Contains distribution and packaging scripts (e.g., AppImage, Debian, ArchLinux, and PyPI packaging under the package directory).
- Dockerfile, Makefile, and CI configuration (.travis.yml) further support building and deploying the application.

##### Relationships and Interactions

- The UI (GUI and CLI) receives user inputs or arguments and communicates with the Virtual Screen Manager.
- The Virtual Screen Manager uses xrandr to configure the virtual display and initiates x11vnc to broadcast the new screen.
- Communication between the GUI front-end and the logic layer might be mediated by asyncio’s event loop, ensuring asynchronous operations.
- Packaging tools and configuration files are used mainly during build and deployment; they do not directly interact with the runtime architecture but are important for distribution considerations.

##### Architectural Patterns and Design Principles

- Separation of Concerns: The project is cleanly separated into the front-end (UI), core logic (virtual screen management), and system integrations (xrandr, x11vnc).
- Modularization: Distinct modules (display.py, xrandr.py, process.py, qt_backend.py) manage their respective responsibilities.
- Extensibility: A well-defined packaging layer shows that the project is designed to be built, deployed, and installed in multiple formats across different Linux distributions.

3. From the Virtual Screen Manager, add connections indicating calls to external components:
- Another to the “x11vnc Service” (to start the VNC server).
4. An annotation near this central block that mentions the use of asyncio for asynchronous event handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        GUI["GUI (PyQt5+QML)"]:::frontend
        CLI["CLI Handler"]:::frontend
    end

    %% Core Application
    subgraph "Core Application"
        VSM["Virtual Screen Manager"]:::backend
        subgraph "VSM Modules"
            direction TB
            DISP["display.py"]:::backend
            PROC["process.py"]:::backend
            QTBE["qt_backend.py"]:::backend
            XRMOD["xrandr.py"]:::backend
        end
        Async["Asyncio Event Loop"]:::backendNote
    end

    %% External Dependencies
    subgraph "External Dependencies"
        XRandR["XRandR Interface"]:::external
        X11VNC["x11vnc Service"]:::external
    end

    %% Packaging/Deployment
    subgraph "Packaging/Deployment"
        PackDir["Packaging Scripts (package/)"]:::packaging
        AppImage["AppImage Package"]:::packaging
        Debian["Debian Package"]:::packaging
        Arch["ArchLinux Package"]:::packaging
        PyPI["PyPI Package"]:::packaging
        DockerFile["Dockerfile"]:::packaging
        MF["Makefile"]:::packaging
        Travis[".travis.yml"]:::packaging
        Setup["setup.py"]:::packaging
    end

    %% Relationships
    GUI -->|"input"| VSM
    CLI -->|"input"| VSM

    VSM -->|"triggers_async"| Async

    %% Internal module grouping (implicit: modules are part of VSM)
    VSM --- DISP
    VSM --- PROC
    VSM --- QTBE
    VSM --- XRMOD

    %% External interactions
    VSM -->|"configures"| XRandR
    VSM -->|"initiates"| X11VNC

    %% Specific module interactions
    XRMOD -->|"configures"| XRandR
    DISP -->|"triggers_vnc"| X11VNC

    %% Packaging linkage (build/deploy process)
    PackDir -.->|"build/deploy"| VSM

    %% Click events
    click GUI "https://github.com/kbumsik/virtscreen/tree/master/virtscreen/assets"
    click CLI "https://github.com/kbumsik/virtscreen/blob/master/virtscreen/__main__.py"
    click DISP "https://github.com/kbumsik/virtscreen/blob/master/virtscreen/display.py"
    click PROC "https://github.com/kbumsik/virtscreen/blob/master/virtscreen/process.py"
    click QTBE "https://github.com/kbumsik/virtscreen/blob/master/virtscreen/qt_backend.py"
    click XRMOD "https://github.com/kbumsik/virtscreen/blob/master/virtscreen/xrandr.py"
    click PackDir "https://github.com/kbumsik/virtscreen/tree/master/package/"
    click DockerFile "https://github.com/kbumsik/virtscreen/tree/master/Dockerfile"
    click MF "https://github.com/kbumsik/virtscreen/tree/master/Makefile"
    click Travis "https://github.com/kbumsik/virtscreen/blob/master/.travis.yml"
    click Setup "https://github.com/kbumsik/virtscreen/blob/master/setup.py"

    %% Styles
    classDef frontend fill:#a2d2ff,stroke:#083d77,stroke-width:2px;
    classDef backend fill:#fcbf49,stroke:#f77f00,stroke-width:2px;
    classDef backendNote fill:#ffe066,stroke:#fab005,stroke-width:2px;
    classDef external fill:#e0fbfc,stroke:#006494,stroke-width:2px;
    classDef packaging fill:#d8f3dc,stroke:#95d5b2,stroke-width:2px;
```
