# pop-os/libcosmic architecture

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

- Interactive diagram: https://gitdiagram.com/pop-os/libcosmic
- Repository: https://github.com/pop-os/libcosmic

## Overview

##### Project type and purpose
- This repository is a Rust-based UI toolkit (“libcosmic”) built on top of the iced framework.
- It provides:
- A core library (`src/`) exposing widgets, theming, configuration, and app scaffolding.
- Two helper crates: `cosmic-config-derive` (a procedural-macro crate for code generation) and `cosmic-config` (runtime settings management via D-Bus/calloop).
- Example applications showing how consumers use libcosmic.

##### File structure
- Top-level crates:
- `cosmic-config-derive/` (proc-macro)
- `cosmic-config/` (runtime settings daemon & subscription)
- `cosmic-theme/` (theme model, derivation, output)
- Root crate (`src/`): the core `libcosmic` library (widgets, app, executor, surfaces)
- `examples/` demonstrating usage
- Key modules inside the core crate (`src/`):
- `app/`: scaffolding for cosmic applets/apps
- `applet/`: token-based Applet API (Wayland/X11 support)
- `config/`: core hooks into `cosmic-config` crate
- `executor/`: single/multi-threaded runtimes (smol/tokio vs iced default)
- `widget/`: hundreds of custom widgets (buttons, menus, dialogs, etc.)
- `theme/`: runtime styling (portal dialogs, style sheets)
- Integration points: D-Bus activation, file-chooser portal, calloop event loop, Wayland vs winit, GPU rendering (wgpu vs softbuffer).

##### README for additional insights
- The library is used to build COSMIC desktop components (applets, panels, launchers, etc.).
- It is organized as multiple Cargo workspaces/crates.
- Feature flags drive async runtime, windowing backend, GPU or software rendering, and XDG portal integration.

- cosmic-config-derive (Proc-Macro)
- cosmic-config (Settings Daemon + D-Bus Subscription)
- cosmic-theme (Theme Model + Derivation + Output modules)
- libcosmic core:
– App & Applet APIs
– Executor (iced runtime or smol/tokio)
– Widget Library
– Theme Engine (consumes cosmic-theme outputs)
– Config Bridge (consumes cosmic-config)
– Dialog & Portal integration
- External Dependencies: iced (GUI framework), calloop (event loop), D-Bus, Wayland/Winit, XDG Portal, wgpu/softbuffer.
- Consumers: Example applications or downstream COSMIC desktop components.

- Proc-Macro (`cosmic-config-derive`) → codegen into libcosmic consumer code
- libcosmic ↔ cosmic-config via D-Bus subscription to system settings
- libcosmic → iced for widget rendering
- iced → calloop (or chosen executor) → OS event loop
- libcosmic → file-chooser portal → XDG portal or native dialogs
- libcosmic → Wayland or winit for surface creation
- libcosmic → wgpu or softbuffer for rendering
- Application code → libcosmic APIs → drives UI

c. Architectural patterns & principles
- Modular crate separation (proc-macro, runtime config, theming, core UI)
- Inversion of control: consumers supply callbacks, libcosmic owns the event loop
- Feature-flag–driven backends (async runtime, windowing, rendering)
- Pub-sub pattern for settings (using D-Bus subscription)
- Theming pipeline: model → derivation → multi-format output

d. Key technologies
- Rust & Cargo Workspaces
- iced GUI framework
- calloop / async executors (smol, tokio)
- D-Bus (system settings daemon)
- Wayland / winit (windowing)
- wgpu or softbuffer (rendering)
- XDG portals (file dialogs)
- Procedural macros for code generation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Crates Layer
    subgraph "Workspace Crates"
        direction TB
        CCD["cosmic-config-derive<br/>(Proc-Macro)"]:::proc
        CC["cosmic-config<br/>(Settings Daemon & D-Bus)"]:::config
        CT["cosmic-theme<br/>(Theming Engine)"]:::theme
        Core["libcosmic Core<br/>(Widgets, App, Executor, Theme, Config)"]:::core
        Examples["Examples<br/>(Consumer Apps)"]:::example
    end

    %% External Dependencies
    subgraph "External Systems & Frameworks"
        direction TB
        Iced["iced GUI Framework"]:::external
        Calloop["calloop Event Loop"]:::external
        DBus["D-Bus"]:::external
        Wayland["Wayland / winit"]:::external
        Portal["XDG Portal"]:::external
        Renderer["wgpu / softbuffer"]:::external
    end

    %% Relationships
    CCD -->|"codegen"| Core
    Core -->|"RPC & Subscription"| CC
    Core -->|"fetch palettes & styles"| CT
    Core -->|"use for rendering"| Iced
    Iced -->|"drives event loop"| Calloop
    Calloop -->|"OS events"| Wayland
    Core -->|"file chooser"| Portal
    Core -->|"surface creation"| Wayland
    Core -->|"render frame"| Renderer
    Examples -->|"use APIs"| Core

    %% Click Events for Component Mapping
    click CCD "https://github.com/pop-os/libcosmic/blob/master/cosmic-config-derive/Cargo.toml"
    click CCD "https://github.com/pop-os/libcosmic/blob/master/cosmic-config-derive/src/lib.rs"

    click CC "https://github.com/pop-os/libcosmic/blob/master/cosmic-config/Cargo.toml"
    click CC "https://github.com/pop-os/libcosmic/blob/master/cosmic-config/src/lib.rs"
    click CC "https://github.com/pop-os/libcosmic/blob/master/cosmic-config/src/settings_daemon.rs"
    click CC "https://github.com/pop-os/libcosmic/blob/master/cosmic-config/src/subscription.rs"
    click CC "https://github.com/pop-os/libcosmic/blob/master/cosmic-config/src/dbus.rs"
    click CC "https://github.com/pop-os/libcosmic/blob/master/cosmic-config/src/calloop.rs"

    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/Cargo.toml"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/lib.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/model/mod.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/model/cosmic_palette.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/model/derivation.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/model/layout.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/model/mode.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/model/spacing.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/model/theme.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/model/corner.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/model/density.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/model/dark.ron"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/model/light.ron"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/output/mod.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/output/gtk4_output.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/output/vs_code.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/composite.rs"
    click CT "https://github.com/pop-os/libcosmic/blob/master/cosmic-theme/src/steps.rs"

    click Core "https://github.com/pop-os/libcosmic/blob/master/src/lib.rs"
    click Core "https://github.com/pop-os/libcosmic/blob/master/src/app/mod.rs"
    click Core "https://github.com/pop-os/libcosmic/blob/master/src/applet/mod.rs"
    click Core "https://github.com/pop-os/libcosmic/blob/master/src/config/mod.rs"
    click Core "https://github.com/pop-os/libcosmic/blob/master/src/executor/mod.rs"
    click Core "https://github.com/pop-os/libcosmic/blob/master/src/dialog/mod.rs"
    click Core "https://github.com/pop-os/libcosmic/blob/master/src/surface/mod.rs"
    click Core "https://github.com/pop-os/libcosmic/blob/master/src/theme/mod.rs"
    click Core "https://github.com/pop-os/libcosmic/blob/master/src/widget/mod.rs"

    click Examples "https://github.com/pop-os/libcosmic/blob/master/examples/README.md"
    click Examples "https://github.com/pop-os/libcosmic/blob/master/examples/about/src/main.rs"
    click Examples "https://github.com/pop-os/libcosmic/blob/master/examples/applet/src/main.rs"
    click Examples "https://github.com/pop-os/libcosmic/blob/master/examples/application/src/main.rs"
    click Examples "https://github.com/pop-os/libcosmic/blob/master/examples/calendar/src/main.rs"

    %% Styles
    classDef proc fill:#d8b4fe,stroke:#7c3aed,color:#000
    classDef config fill:#bfdbfe,stroke:#3b82f6,color:#000
    classDef theme fill:#bbf7d0,stroke:#22c55e,color:#000
    classDef core fill:#fed7aa,stroke:#f97316,color:#000
    classDef example fill:#a5b4fc,stroke:#6366f1,color:#000
    classDef external fill:#e5e7eb,stroke:#6b7280,color:#000
```
