# turgut-kalyon/sway-wallpi architecture

> Architecture diagram of the GitHub repository turgut-kalyon/sway-wallpi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/turgut-kalyon/sway-wallpi
- Repository: https://github.com/turgut-kalyon/sway-wallpi

## Overview

Wallpi is a terminal wallpaper browser. The main workflow loads configured wallpaper paths into a Vim-navigable list, previews the highlighted image, and on selection replaces a configured symlink and can reload the desktop wallpaper. The graph separates configuration, browsing, preview, and wallpaper application, with the Textual app as the workflow owner. Evidence comes from the supplied README and source excerpts; the README documents the user-facing capabilities, while some internal details were not sampled.

Main entry points: [`src/app/wallpi_app.py`](https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/wallpi_app.py) (Textual app), [`src/app/core/link/link_wp.py`](https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/core/link/link_wp.py) (Symlink manager), [`src/app/widgets/wallpaper_list.py`](https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/widgets/wallpaper_list.py) (Wallpaper listing), [`src/app/core/config/config_loader.py`](https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/core/config/config_loader.py) (Config loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Configuration"]
  node_config_loader["Config loader<br/>[config_loader.py]"]
end

subgraph group_browse["Wallpaper browsing"]
  node_app["Textual app<br/>[wallpi_app.py]"]
  node_wallpaper_list["Wallpaper listing<br/>[wallpaper_list.py]"]
  node_vim_view["Vim list view<br/>[vim_list_view.py]"]
end

subgraph group_preview["Image preview"]
  node_preview_image["Terminal image preview<br/>[wallpi_app.py]"]
  node_preview_worker["Preview loader<br/>[wallpi_app.py]"]
end

subgraph group_apply["Wallpaper setting"]
  node_linker["Symlink manager<br/>[link_wp.py]"]
  node_wallpaper_backend["Wallpaper backend"]
  node_notifications["Desktop notifications"]
end

node_user(("Terminal user"))

node_user -->|"uses"| node_app
node_app -->|"reads settings"| node_config_loader
node_app -->|"loads wallpapers"| node_wallpaper_list
node_wallpaper_list -->|"reads folder"| node_config_loader
node_wallpaper_list -->|"builds list"| node_vim_view
node_app -.->|"handles selection"| node_vim_view
node_app -->|"loads highlighted image"| node_preview_worker
node_preview_worker -->|"sets preview"| node_preview_image
node_app -->|"sets selected wallpaper"| node_linker
node_linker -->|"reads reload setting"| node_config_loader
node_linker -->|"invokes available tool"| node_wallpaper_backend
node_linker -->|"reports outcome"| node_notifications

click node_app "https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/wallpi_app.py"
click node_config_loader "https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/core/config/config_loader.py"
click node_wallpaper_list "https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/widgets/wallpaper_list.py"
click node_vim_view "https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/widgets/vim_list_view.py"
click node_preview_image "https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/wallpi_app.py"
click node_preview_worker "https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/wallpi_app.py"
click node_linker "https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/core/link/link_wp.py"

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_config_loader,node_user toneBlue
class node_app,node_wallpaper_list,node_vim_view toneAmber
class node_preview_image,node_preview_worker toneMint
class node_linker,node_wallpaper_backend,node_notifications toneRose
```

## Components

### Configuration

- [Config loader](https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/core/config/config_loader.py): `src/app/core/config/config_loader.py`

### Wallpaper browsing

- [Textual app](https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/wallpi_app.py): `src/app/wallpi_app.py`
- [Wallpaper listing](https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/widgets/wallpaper_list.py): `src/app/widgets/wallpaper_list.py`
- [Vim list view](https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/widgets/vim_list_view.py): `src/app/widgets/vim_list_view.py`

### Image preview

- [Terminal image preview](https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/wallpi_app.py): `src/app/wallpi_app.py`
- [Preview loader](https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/wallpi_app.py): `src/app/wallpi_app.py`

### Wallpaper setting

- [Symlink manager](https://github.com/turgut-kalyon/sway-wallpi/blob/main/src/app/core/link/link_wp.py): `src/app/core/link/link_wp.py`
- **Wallpaper backend**
- **Desktop notifications**

### Other components

- **Terminal user**

## Connections

- Terminal user → Textual app: uses (evidence: `README.md`)
- Textual app → Config loader: reads settings (evidence: `src/app/wallpi_app.py`)
- Textual app → Wallpaper listing: loads wallpapers (evidence: `src/app/wallpi_app.py`)
- Wallpaper listing → Config loader: reads folder (evidence: `src/app/widgets/wallpaper_list.py`)
- Wallpaper listing → Vim list view: builds list (evidence: `src/app/widgets/wallpaper_list.py`)
- Textual app → Vim list view: handles selection
- Textual app → Preview loader: loads highlighted image (evidence: `src/app/wallpi_app.py`)
- Preview loader → Terminal image preview: sets preview (evidence: `src/app/wallpi_app.py`)
- Textual app → Symlink manager: sets selected wallpaper (evidence: `src/app/wallpi_app.py`)
- Symlink manager → Config loader: reads reload setting (evidence: `src/app/core/link/link_wp.py`)
- Symlink manager → Wallpaper backend: invokes available tool (evidence: `src/app/core/link/link_wp.py`)
- Symlink manager → Desktop notifications: reports outcome (evidence: `src/app/core/link/link_wp.py`)
