# cachyos/cachyos-welcome architecture

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

- Interactive diagram: https://gitdiagram.com/cachyos/cachyos-welcome
- Repository: https://github.com/cachyos/cachyos-welcome

## Overview

##### Project type and purpose
- This is a desktop-GUI “welcome screen” application for CachyOS, written in Rust and GTK.
- At runtime it displays welcome pages, handles user actions (e.g. install, open browser), and interacts with system services (ALPM/pacman, systemd, D-Bus).

##### File structure
- Top-level “src/” folder holds the Rust modules:
- main.rs, application.rs, window.rs, pages.rs, actions.rs
- helper modules: alpm_helper.rs, installer.rs, kwin_dbus.rs, systemd_units.rs
- support: localization.rs, logger.rs, utils.rs
- embed_data.rs and gresource.rs for packing JSON, images, Glade, CSS into the binary
- “ui/” contains cachyos-hello.glade and style.css
- “data/” contains JSON definitions for pages (under data/pages/<lang>), default settings, and images
- “i18n/” and “i18n.toml” hold Fluent translation files (.ftl)
- Build: Meson (meson.build, build-aux scripts), Cargo (Cargo.toml, build.rs), postinstall.sh, hooks, scripts/rootshell.sh

##### README
- Confirms it is the “CachyOS Welcome” screen, Rust+GTK, CI status

1. Build System
- Meson + Cargo + build.rs + build-aux scripts
- GResource compiler (embed UI/CSS/JSON/images)
2. Application Binary
- Rust runtime
- UI Loader (gtk::Builder)
- Controllers/Modules
- Actions Module
- Pages/Model Module
- Installer/ALPM Module
- Systemd & D-Bus Module
- Localization & Logger
3. Embedded Resources
- Glade UI file, CSS
- JSON page data, images
- Fluent .ftl translation files
4. External Services
- Package manager backend (pacman via ALPM)
- systemd (via D-Bus)
- KWin D-Bus for window management
- root-elevation scripts (rootshell.sh, terminal-helper)
- File system (preferences.json)

- Build System → Application Binary (produces executable + embedded resources)
- At runtime:
- Binary → GResource API → loads UI, CSS, JSON, images
- UI Layer ←→ Controller Modules (actions/pages)
- Controllers → Localization Module → fetch translated strings
- Installer Module → root shell script / ALPM helper → pacman
- Systemd Module → D-Bus API → systemd daemon
- KWin D-Bus Module → KWin → window placement
- Logger → writes to file/console
- Preferences JSON → read/write by Config module

c. Architectural patterns & principles:
- MVC-like separation:
- View = GTK UI (Glade)
- Model = pages.rs + embed_data.rs (JSON models)
- Controller = actions.rs, installer.rs, alpm_helper.rs
- Resource embedding for single-binary distribution
- Modularization by concern: localization, logging, system integration
- CI/CD via GitHub Actions, dependency management via Cargo/Meson

d. Key technologies/frameworks:
- Rust (Cargo, build.rs)
- GTK3/Glade (gtk::Builder, GResource)
- Meson build integration
- Fluent (FTL) for i18n
- pacman ALPM library bindings
- systemd & D-Bus crates
- Shell scripts for privileged operations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build System
    subgraph "Build System"
        direction TB
        MesonRoot["meson.build"]:::build
        MesonSrc["src/meson.build"]:::build
        BuildAux["build-aux/"]:::build
        CargoToml["Cargo.toml"]:::build
        BuildRs["build.rs"]:::build
    end

    MesonRoot -->|configures| MesonSrc
    MesonRoot -->|drives| BuildAux
    MesonRoot -->|provides| CargoToml
    MesonRoot -->|invokes| BuildRs
    BuildAux -->|generates| ApplicationBinary

    %% Application Binary
    subgraph "Application Binary" 
        direction TB
        ApplicationBinary["CachyOS Welcome Executable"]:::app

        subgraph "UI & Loader"
            direction TB
            GResourceAPI["GResource API"]:::app
            UILoader["gtk::Builder Loader"]:::app
        end

        subgraph "Controller Modules"
            direction TB
            Actions["Actions Module"]:::app
            Pages["Pages Module"]:::app
            Installer["Installer Module"]:::app
            ALPMHelper["ALPM Helper"]:::app
            SystemdUnits["Systemd Units Module"]:::app
            KwinDBus["KWin D-Bus Module"]:::app
        end

        subgraph "Support Modules"
            direction TB
            Localization["Localization Module"]:::app
            Logger["Logger Module"]:::app
            Utils["Utils & Config Module"]:::app
        end
    end

    BuildAux -->|embeds resources into| ApplicationBinary
    ApplicationBinary -->|loads resources via| GResourceAPI
    GResourceAPI -->|builds UI model| UILoader
    UILoader -->|renders View| Actions
    UILoader -->|renders View| Pages

    Actions -->|triggers| Installer
    Actions -->|triggers| ALPMHelper
    Actions -->|triggers| SystemdUnits
    Actions -->|triggers| KwinDBus

    Installer -->|calls| ALPMHelper
    Installer -->|executes| RootShell

    ALPMHelper -->|invokes| Pacman
    SystemdUnits -->|via D-Bus| SystemdDaemon
    KwinDBus -->|via D-Bus| KWin

    Pages -->|reads/writes| PreferencesFS
    Localization -->|loads| FluentResources
    Logger -->|writes to| LogFS
    Utils -->|manages| PreferencesFS

    %% Embedded Resources
    subgraph "Embedded Resources"
        direction TB
        GResourceXML["cachyos-welcome.gresource.xml"]:::resource
        EmbedDataCode["src/embed_data.rs"]:::resource
        GResourceCode["src/gresource.rs"]:::resource
        GladeUI["ui/cachyos-hello.glade"]:::resource
        StyleCSS["ui/style.css"]:::resource
        JSONPages["data/pages/"]:::resource
        PrefsJSON["data/preferences.json"]:::resource
        UtilityJSON["data/application_utility/default.json"]:::resource
        Images["data/img/"]:::resource
        FluentFTL["i18n/*.ftl"]:::resource
        I18nToml["i18n.toml"]:::resource
    end

    GResourceXML -->|describes| EmbedDataCode
    GResourceXML -->|drives| GResourceCode
    EmbedDataCode -->|includes| GladeUI
    EmbedDataCode -->|includes| StyleCSS
    EmbedDataCode -->|includes| JSONPages
    EmbedDataCode -->|includes| PrefsJSON
    EmbedDataCode -->|includes| UtilityJSON
    EmbedDataCode -->|includes| Images
    EmbedDataCode -->|includes| FluentFTL
    EmbedDataCode -->|includes| I18nToml

    %% External Services
    subgraph "External Services"
        direction TB
        Pacman["Pacman/ALPM"]:::external
        SystemdDaemon["systemd Daemon"]:::external
        KWin["KWin Window Manager"]:::external
        RootShell["rootshell.sh & terminal-helper"]:::external
        PreferencesFS["File System (preferences.json)"]:::external
        LogFS["File System (logs)"]:::external
        FluentResources["Fluent .ftl Files"]:::external
    end

    ALPMHelper -->|uses| Pacman
    SystemdUnits -->|talks to| SystemdDaemon
    KwinDBus -->|talks to| KWin
    Installer -->|elevates via| RootShell
    Pages -->|loads settings from| PreferencesFS
    Logger -->|writes| LogFS
    Localization -->|reads| FluentResources

    %% Click Events
    click MesonRoot "https://github.com/cachyos/cachyos-welcome/blob/develop/meson.build"
    click MesonSrc "https://github.com/cachyos/cachyos-welcome/blob/develop/src/meson.build"
    click BuildAux "https://github.com/cachyos/cachyos-welcome/tree/develop/build-aux/"
    click CargoToml "https://github.com/cachyos/cachyos-welcome/blob/develop/Cargo.toml"
    click BuildRs "https://github.com/cachyos/cachyos-welcome/blob/develop/build.rs"
    click GResourceXML "https://github.com/cachyos/cachyos-welcome/blob/develop/cachyos-welcome.gresource.xml"
    click EmbedDataCode "https://github.com/cachyos/cachyos-welcome/blob/develop/src/embed_data.rs"
    click GResourceCode "https://github.com/cachyos/cachyos-welcome/blob/develop/src/gresource.rs"
    click GladeUI "https://github.com/cachyos/cachyos-welcome/blob/develop/ui/cachyos-hello.glade"
    click StyleCSS "https://github.com/cachyos/cachyos-welcome/blob/develop/ui/style.css"
    click JSONPages "https://github.com/cachyos/cachyos-welcome/tree/develop/data/pages/"
    click PrefsJSON "https://github.com/cachyos/cachyos-welcome/blob/develop/data/preferences.json"
    click UtilityJSON "https://github.com/cachyos/cachyos-welcome/blob/develop/data/application_utility/default.json"
    click Images "https://github.com/cachyos/cachyos-welcome/tree/develop/data/img/"
    click FluentFTL "https://github.com/cachyos/cachyos-welcome/blob/develop/i18n/*.ftl"
    click I18nToml "https://github.com/cachyos/cachyos-welcome/blob/develop/i18n.toml"
    click Localization "https://github.com/cachyos/cachyos-welcome/blob/develop/src/localization.rs"
    click Logger "https://github.com/cachyos/cachyos-welcome/blob/develop/src/logger.rs"
    click Utils "https://github.com/cachyos/cachyos-welcome/blob/develop/src/utils.rs"
    click MesonRoot "https://github.com/cachyos/cachyos-welcome/blob/develop/meson.build"
    click MesonSrc "https://github.com/cachyos/cachyos-welcome/blob/develop/src/meson.build"
    click MesonRoot "https://github.com/cachyos/cachyos-welcome/blob/develop/meson.build"
    click BuildAux "https://github.com/cachyos/cachyos-welcome/tree/develop/build-aux/"
    click CargoToml "https://github.com/cachyos/cachyos-welcome/blob/develop/Cargo.toml"
    click BuildRs "https://github.com/cachyos/cachyos-welcome/blob/develop/build.rs"
    click MainEntry "https://github.com/cachyos/cachyos-welcome/blob/develop/src/main.rs"
    click ApplicationBinary "https://github.com/cachyos/cachyos-welcome/blob/develop/src/application.rs"
    click UILoader "https://github.com/cachyos/cachyos-welcome/blob/develop/src/window.rs"
    click Actions "https://github.com/cachyos/cachyos-welcome/blob/develop/src/actions.rs"
    click Pages "https://github.com/cachyos/cachyos-welcome/blob/develop/src/pages.rs"
    click Installer "https://github.com/cachyos/cachyos-welcome/blob/develop/src/installer.rs"
    click ALPMHelper "https://github.com/cachyos/cachyos-welcome/blob/develop/src/alpm_helper.rs"
    click RootShell "https://github.com/cachyos/cachyos-welcome/blob/develop/src/scripts/rootshell.sh"
    click Utils "https://github.com/cachyos/cachyos-welcome/blob/develop/src/utils.rs"

    %% Styles
    classDef build fill:#cce5ff,stroke:#004085,color:#004085
    classDef app fill:#d4edda,stroke:#155724,color:#155724
    classDef resource fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24
```
