# pop-os/cosmic-epoch architecture

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

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

## Overview

COSMIC Desktop is a Linux desktop environment composed of a login/session entry point, Wayland desktop rendering, shell services, system utilities, and first-party applications. The principal workflow is initiated by a user selecting COSMIC in an external display manager and logging in; the selected session then assembles the compositor and interactive desktop shell.

#### Components

##### Login and rendering
- **User** — path: `null`. External actor who selects a session, logs in, and interacts with the desktop.
- **Display manager** — path: `null`. External login/session chooser documented by the installation instructions.
- **COSMIC Greeter** — `cosmic-greeter`. COSMIC login and display-manager component; the README documents enabling it as a display manager.
- **COSMIC Session** — `cosmic-session`. Desktop-session entry point installed and selected from a display manager.
- **COSMIC Compositor** — `cosmic-comp`. Wayland window/compositing subsystem; its role is established by the component inventory and Wayland-focused dependency requirements.
- **COSMIC Workspaces** — `cosmic-workspaces-epoch`. Workspace organization for the desktop.
- **COSMIC Monitor** — `cosmic-monitor`. Monitor/display management application.
- **COSMIC RandR** — `cosmic-randr`. Display-output configuration utility.

##### Shell and interaction
- **COSMIC Panel** — `cosmic-panel`. Desktop panel and shell surface.
- **COSMIC App Library** — `cosmic-applibrary`. Graphical application browsing and launching surface.
- **COSMIC Launcher** — `cosmic-launcher`. Fast application search and launch interface.
- **COSMIC Applets** — `cosmic-applets`. Panel-resident desktop controls and applets.
- **COSMIC Notifications** — `cosmic-notifications`. User notification presentation and management.

##### State and platform services
- **COSMIC Settings** — `cosmic-settings`. User-facing desktop settings application.
- **COSMIC Settings Daemon** — `cosmic-settings-daemon`. Background settings/state service paired with the settings UI.
- **COSMIC Backgrounds** — `cosmic-bg`. Desktop background and wallpaper management.
- **COSMIC Idle** — `cosmic-idle`. Inactivity detection and idle-related desktop behavior.
- **COSMIC On-Screen Keyboard** — `cosmic-osk`. On-screen keyboard facility.
- **COSMIC Screenshot** — `cosmic-screenshot`. Desktop screenshot capture utility.
- **COSMIC Portal** — `xdg-desktop-portal-cosmic`. XDG desktop portal implementation for application-to-desktop integration.
- **COSMIC Initial Setup** — `cosmic-initial-setup`. First-run desktop configuration.

##### First-party applications
- **COSMIC Files** — `cosmic-files`. File-management application.
- **COSMIC Edit** — `cosmic-edit`. Text-editing application.
- **COSMIC Terminal** — `cosmic-term`. Terminal emulator.
- **COSMIC Player** — `cosmic-player`. Media-player application.
- **COSMIC Store** — `cosmic-store`. Software-store application.

#### Relationships

- **User -> Display manager:** selects the COSMIC desktop entry and logs in; directly documented by the installation instructions.
- **Display manager -> COSMIC Greeter:** may use the COSMIC greeter as its login frontend; the README documents this deployment option.
- **Display manager -> COSMIC Session:** launches the selected COSMIC session after login; documented by the session-selection instructions.
- **COSMIC Greeter -> COSMIC Session:** hands off a successful COSMIC login to the selected session when the COSMIC greeter is enabled; exact implementation is not shown.
- **COSMIC Session -> COSMIC Compositor:** assembles the compositor as part of the running desktop session; this is product-level composition, not a verified call sequence.
- **COSMIC Session -> COSMIC Panel:** owns or starts the desktop shell alongside the session; exact startup wiring is unavailable.
- **COSMIC Compositor -> COSMIC Workspaces:** provides the rendered window/workspace environment.
- **COSMIC Monitor -> COSMIC Compositor:** supplies monitor-management behavior for the rendered desktop; the concrete interface is not sampled.
- **COSMIC RandR -> COSMIC Compositor:** applies display-output configuration to the compositor; exact call direction is unverified.
- **COSMIC Panel -> COSMIC Applets:** hosts or exposes panel applets.
- **User -> COSMIC Launcher:** invokes application search and launch interaction.
- **COSMIC Launcher -> COSMIC Files:** launches a selected first-party application; the other listed applications are parallel targets, but their individual launch paths are not established.
- **User -> COSMIC App Library:** browses and selects applications through the application library.
- **COSMIC Settings -> COSMIC Settings Daemon:** forms the documented UI-to-background-settings boundary; the repository sample does not establish its IPC or persistence mechanism.
- **COSMIC Screenshot -> COSMIC Compositor:** obtains desktop display content for capture; this relationship is role-based because no source calls are available.
- **COSMIC Portal -> External applications:** exposes desktop integration interfaces to applications outside this repository.
- **External applications** — path: `null`. Applications that consume the desktop portal interfaces.

#### Coverage limits

No source excerpts were provided, so imports, process startup order, IPC, persistence, and concrete provider interfaces cannot be confirmed. The README also names libraries and a theme editor not present in the supplied tree; they are therefore not mapped as repository components.

Main entry points: [`cosmic-comp`](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-comp) (COSMIC Compositor), [`cosmic-session`](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-session) (COSMIC Session), [`cosmic-greeter`](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-greeter) (COSMIC Greeter), [`cosmic-panel`](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-panel) (COSMIC Panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_login_rendering["Login and Rendering"]
  node_cosmic_greeter["COSMIC Greeter<br/>login frontend"]
  node_cosmic_session["COSMIC Session<br/>desktop session"]
  node_cosmic_compositor["COSMIC Compositor<br/>Wayland compositor"]
  node_cosmic_workspaces["COSMIC Workspaces<br/>workspace manager"]
  node_cosmic_monitor["COSMIC Monitor<br/>monitor manager"]
  node_cosmic_randr["COSMIC RandR<br/>display configuration"]
end

subgraph group_shell_interaction["Shell and Interaction"]
  node_cosmic_panel["COSMIC Panel<br/>desktop panel"]
  node_cosmic_app_library["COSMIC App Library<br/>application browser"]
  node_cosmic_launcher["COSMIC Launcher<br/>application launcher"]
  node_cosmic_applets["COSMIC Applets<br/>panel controls"]
  node_cosmic_notifications["COSMIC Notifications<br/>notification manager"]
end

subgraph group_platform_services["State and Platform Services"]
  node_cosmic_settings["COSMIC Settings<br/>settings application"]
  node_cosmic_settings_daemon["COSMIC Settings Daemon<br/>background settings service"]
  node_cosmic_backgrounds["COSMIC Backgrounds<br/>wallpaper manager"]
  node_cosmic_idle["COSMIC Idle<br/>inactivity service"]
  node_cosmic_osk["COSMIC On-Screen Keyboard<br/>keyboard facility"]
  node_cosmic_screenshot["COSMIC Screenshot<br/>screenshot utility"]
  node_cosmic_portal["COSMIC Portal<br/>desktop portal"]
  node_cosmic_initial_setup["COSMIC Initial Setup<br/>first-run configuration"]
end

subgraph group_first_party_apps["First-Party Applications"]
  node_cosmic_files["COSMIC Files<br/>file manager"]
  node_cosmic_edit["COSMIC Edit<br/>text editor"]
  node_cosmic_terminal["COSMIC Terminal<br/>terminal emulator"]
  node_cosmic_player["COSMIC Player<br/>media player"]
  node_cosmic_store["COSMIC Store<br/>software store"]
end

subgraph group_external["External Actors"]
  node_user(("User<br/>external actor"))
  node_display_manager["Display Manager<br/>login/session chooser"]
  node_external_applications(("External Applications"))
end

node_user -->|"selects and logs in"| node_display_manager
node_display_manager -.->|"may use"| node_cosmic_greeter
node_display_manager -->|"launches"| node_cosmic_session
node_cosmic_greeter -.->|"hands off login"| node_cosmic_session
node_cosmic_session -->|"assembles"| node_cosmic_compositor
node_cosmic_session -->|"starts shell"| node_cosmic_panel
node_cosmic_compositor -->|"provides environment"| node_cosmic_workspaces
node_cosmic_monitor -->|"manages monitors"| node_cosmic_compositor
node_cosmic_randr -->|"configures outputs"| node_cosmic_compositor
node_cosmic_panel -->|"hosts applets"| node_cosmic_applets
node_user -->|"searches and launches"| node_cosmic_launcher
node_cosmic_launcher -->|"launches"| node_cosmic_files
node_user -->|"browses and selects"| node_cosmic_app_library
node_cosmic_settings -->|"uses settings service"| node_cosmic_settings_daemon
node_cosmic_screenshot -->|"captures display"| node_cosmic_compositor
node_cosmic_portal -->|"exposes interfaces"| node_external_applications

click node_cosmic_greeter "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-greeter"
click node_cosmic_session "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-session"
click node_cosmic_compositor "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-comp"
click node_cosmic_workspaces "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-workspaces-epoch"
click node_cosmic_monitor "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-monitor"
click node_cosmic_randr "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-randr"
click node_cosmic_panel "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-panel"
click node_cosmic_app_library "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-applibrary"
click node_cosmic_launcher "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-launcher"
click node_cosmic_applets "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-applets"
click node_cosmic_notifications "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-notifications"
click node_cosmic_settings "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-settings"
click node_cosmic_settings_daemon "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-settings-daemon"
click node_cosmic_backgrounds "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-bg"
click node_cosmic_idle "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-idle"
click node_cosmic_osk "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-osk"
click node_cosmic_screenshot "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-screenshot"
click node_cosmic_portal "https://github.com/pop-os/cosmic-epoch/tree/master/xdg-desktop-portal-cosmic"
click node_cosmic_initial_setup "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-initial-setup"
click node_cosmic_files "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-files"
click node_cosmic_edit "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-edit"
click node_cosmic_terminal "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-term"
click node_cosmic_player "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-player"
click node_cosmic_store "https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-store"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cosmic_greeter,node_cosmic_session,node_cosmic_compositor,node_cosmic_workspaces,node_cosmic_monitor,node_cosmic_randr toneBlue
class node_cosmic_panel,node_cosmic_app_library,node_cosmic_launcher,node_cosmic_applets,node_cosmic_notifications toneAmber
class node_cosmic_settings,node_cosmic_settings_daemon,node_cosmic_backgrounds,node_cosmic_idle,node_cosmic_osk,node_cosmic_screenshot,node_cosmic_portal,node_cosmic_initial_setup toneMint
class node_cosmic_files,node_cosmic_edit,node_cosmic_terminal,node_cosmic_player,node_cosmic_store toneRose
class node_user,node_display_manager,node_external_applications toneIndigo
```

## Components

### Login and Rendering

- [COSMIC Greeter](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-greeter): login frontend · `cosmic-greeter`
- [COSMIC Session](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-session): desktop session · `cosmic-session`
- [COSMIC Compositor](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-comp): Wayland compositor · `cosmic-comp`
- [COSMIC Workspaces](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-workspaces-epoch): workspace manager · `cosmic-workspaces-epoch`
- [COSMIC Monitor](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-monitor): monitor manager · `cosmic-monitor`
- [COSMIC RandR](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-randr): display configuration · `cosmic-randr`

### Shell and Interaction

- [COSMIC Panel](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-panel): desktop panel · `cosmic-panel`
- [COSMIC App Library](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-applibrary): application browser · `cosmic-applibrary`
- [COSMIC Launcher](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-launcher): application launcher · `cosmic-launcher`
- [COSMIC Applets](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-applets): panel controls · `cosmic-applets`
- [COSMIC Notifications](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-notifications): notification manager · `cosmic-notifications`

### State and Platform Services

- [COSMIC Settings](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-settings): settings application · `cosmic-settings`
- [COSMIC Settings Daemon](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-settings-daemon): background settings service · `cosmic-settings-daemon`
- [COSMIC Backgrounds](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-bg): wallpaper manager · `cosmic-bg`
- [COSMIC Idle](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-idle): inactivity service · `cosmic-idle`
- [COSMIC On-Screen Keyboard](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-osk): keyboard facility · `cosmic-osk`
- [COSMIC Screenshot](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-screenshot): screenshot utility · `cosmic-screenshot`
- [COSMIC Portal](https://github.com/pop-os/cosmic-epoch/tree/master/xdg-desktop-portal-cosmic): desktop portal · `xdg-desktop-portal-cosmic`
- [COSMIC Initial Setup](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-initial-setup): first-run configuration · `cosmic-initial-setup`

### First-Party Applications

- [COSMIC Files](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-files): file manager · `cosmic-files`
- [COSMIC Edit](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-edit): text editor · `cosmic-edit`
- [COSMIC Terminal](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-term): terminal emulator · `cosmic-term`
- [COSMIC Player](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-player): media player · `cosmic-player`
- [COSMIC Store](https://github.com/pop-os/cosmic-epoch/tree/master/cosmic-store): software store · `cosmic-store`

### External Actors

- **User**: external actor · Selects a session, logs in, and interacts with the desktop.
- **Display Manager**: login/session chooser
- **External Applications**: external applications · Applications consuming desktop portal interfaces.

## Connections

- User → Display Manager: selects and logs in
- Display Manager → COSMIC Greeter: may use · Optional login frontend deployment.
- Display Manager → COSMIC Session: launches
- COSMIC Greeter → COSMIC Session: hands off login · Applies when the COSMIC greeter is enabled.
- COSMIC Session → COSMIC Compositor: assembles · Product-level session composition; startup sequence is unverified.
- COSMIC Session → COSMIC Panel: starts shell · Product-level ownership; startup wiring is unavailable.
- COSMIC Compositor → COSMIC Workspaces: provides environment
- COSMIC Monitor → COSMIC Compositor: manages monitors · Concrete interface is not sampled.
- COSMIC RandR → COSMIC Compositor: configures outputs · Exact call direction is unverified.
- COSMIC Panel → COSMIC Applets: hosts applets
- User → COSMIC Launcher: searches and launches
- COSMIC Launcher → COSMIC Files: launches · Representative established first-party launch target.
- User → COSMIC App Library: browses and selects
- COSMIC Settings → COSMIC Settings Daemon: uses settings service · IPC and persistence mechanism are unconfirmed.
- COSMIC Screenshot → COSMIC Compositor: captures display · Role-based relationship; no source calls are available.
- COSMIC Portal → External Applications: exposes interfaces
