# amardeepxy/rand_wallhaven architecture

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

- Interactive diagram: https://gitdiagram.com/amardeepxy/rand_wallhaven
- Repository: https://github.com/amardeepxy/rand_wallhaven

## Overview

1. **What this repo is**
   - `rand_wallhaven` is a **Node.js command-line wallpaper tool** for **Wayland** desktops.
   - Its purpose is to fetch a random wallpaper from **Wallhaven** and apply it through the local **`swww`** wallpaper daemon.

2. **Top-level architecture**
   - The code is split into a small set of focused modules under `app/`.
   - A build step produces `dist/index.cjs`, and the project is then compiled into a runnable CLI executable named `wallhaven`.

3. **Main runtime boundary**
   - The app runs as a **local CLI process**.
   - It depends on two outside systems:
     - the **Wallhaven web API** for wallpaper source images
     - the local **`swww`** binary/service for actually changing the desktop wallpaper

4. **Entry/orchestration layer**
   - `app/wallhaven.js` appears to be the main application entrypoint and coordinator.
   - This is where CLI arguments are likely interpreted and the sequence “choose image → apply wallpaper” is driven.

5. **Wallhaven API subsystem**
   - `app/wallhaven/client.js` is the network client boundary.
   - It encapsulates communication with Wallhaven rather than mixing HTTP logic into the rest of the app.
   - This module is the main dependency on internet access and Wallhaven’s response format.

6. **Wallpaper application subsystem**
   - `app/swww/swww.js` is the adapter around **`swww`**.
   - It likely maps the app’s options, such as transition type and transition step, into the commands expected by `swww`.
   - This keeps Wayland-specific wallpaper-setting logic isolated from image retrieval.

7. **Shared utility layer**
   - `app/utility/utility.js` holds reusable helper logic used across the CLI.
   - This kind of module typically contains common operations such as argument handling helpers, path/string helpers, or small transformation functions.
   - It functions as the shared support layer between the orchestrator, API client, and wallpaper adapter.

8. **Data flow through the app**
   - User runs the CLI with options like `--transition-type wipe --transition-step 50`.
   - The main module resolves behavior, calls the Wallhaven client to get a random image, then passes the selected image plus transition settings to the `swww` wrapper.
   - The final effect is a desktop wallpaper change on the local Wayland session.

9. **Build and distribution path**
   - Source lives in `app/`.
   - A build output is checked in or generated under `dist/` as `index.cjs`.
   - The project is then compiled into a standalone executable, which is how releases are distributed.

10. **Repository contents that are not runtime-critical**
   - `demo/` and the screenshots in the README are presentation assets.
   - `README.md` documents installation, build, and usage, but it is not part of runtime behavior.

11. **Important architectural constraint**
   - The project is not a general wallpaper engine; it is specifically a **Wayland CLI wrapper around `swww` plus Wallhaven**.
   - So the key architecture diagram should show:
     - user/CLI input
     - Wallhaven API fetch
     - local `swww` wallpaper application
     - build packaging into a standalone executable

Main entry points: [`app/wallhaven.js`](https://github.com/amardeepxy/rand_wallhaven/blob/main/app/wallhaven.js) (Main app), [`app/wallhaven/client.js`](https://github.com/amardeepxy/rand_wallhaven/blob/main/app/wallhaven/client.js) (Wallhaven client), [`app/swww/swww.js`](https://github.com/amardeepxy/rand_wallhaven/blob/main/app/swww/swww.js) (swww adapter), [`app/wallhaven`](https://github.com/amardeepxy/rand_wallhaven/tree/main/app/wallhaven) (wallhaven CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["App"]
  node_node_main["Main app<br/>orchestrator<br/>[wallhaven.js]"]
  node_node_client["Wallhaven client<br/>http client<br/>[client.js]"]
  node_node_swww["swww adapter<br/>shell adapter<br/>[swww.js]"]
  node_node_util["Utilities<br/>shared helpers<br/>[utility.js]"]
end

subgraph group_grp_build["Build"]
  node_node_cli["wallhaven CLI<br/>entrypoint"]
  node_node_dist["Built bundle<br/>compiled output<br/>[index.cjs]"]
  node_node_package["Package config<br/>npm package<br/>[package.json]"]
end

subgraph group_grp_external["External"]
  node_node_user(("User<br/>actor"))
  node_node_wallhaven[("Wallhaven API<br/>external api")]
  node_node_swwwd[("swww daemon<br/>local daemon")]
end

node_node_user -->|"run"| node_node_cli
node_node_cli -->|"execute"| node_node_dist
node_node_dist -->|"load"| node_node_main
node_node_main -->|"fetch wallpaper"| node_node_client
node_node_client -->|"HTTP request"| node_node_wallhaven
node_node_main -->|"apply wallpaper"| node_node_swww
node_node_swww -->|"command"| node_node_swwwd
node_node_main -.->|"helpers"| node_node_util
node_node_client -.->|"helpers"| node_node_util
node_node_swww -.->|"helpers"| node_node_util
node_node_package -->|"builds"| node_node_cli
node_node_package -->|"bundle output"| node_node_dist

click node_node_cli "https://github.com/amardeepxy/rand_wallhaven/tree/main/app/wallhaven"
click node_node_main "https://github.com/amardeepxy/rand_wallhaven/blob/main/app/wallhaven.js"
click node_node_client "https://github.com/amardeepxy/rand_wallhaven/blob/main/app/wallhaven/client.js"
click node_node_swww "https://github.com/amardeepxy/rand_wallhaven/blob/main/app/swww/swww.js"
click node_node_util "https://github.com/amardeepxy/rand_wallhaven/blob/main/app/utility/utility.js"
click node_node_dist "https://github.com/amardeepxy/rand_wallhaven/blob/main/dist/index.cjs"
click node_node_package "https://github.com/amardeepxy/rand_wallhaven/blob/main/package.json"

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_node_main,node_node_client,node_node_swww,node_node_util toneBlue
class node_node_cli,node_node_dist,node_node_package toneAmber
class node_node_user,node_node_wallhaven,node_node_swwwd toneMint
```

## Components

### App

Runtime source modules

- [Main app](https://github.com/amardeepxy/rand_wallhaven/blob/main/app/wallhaven.js): orchestrator · Coordinates random wallpaper selection and application · `app/wallhaven.js`
- [Wallhaven client](https://github.com/amardeepxy/rand_wallhaven/blob/main/app/wallhaven/client.js): http client · Fetches random wallpaper data from the Wallhaven API · `app/wallhaven/client.js`
- [swww adapter](https://github.com/amardeepxy/rand_wallhaven/blob/main/app/swww/swww.js): shell adapter · Wraps the local swww wallpaper daemon and its options · `app/swww/swww.js`
- [Utilities](https://github.com/amardeepxy/rand_wallhaven/blob/main/app/utility/utility.js): shared helpers · Common helper functions used across the app · `app/utility/utility.js`

### Build

Packaged CLI output

- [wallhaven CLI](https://github.com/amardeepxy/rand_wallhaven/tree/main/app/wallhaven): entrypoint · Installed command that launches the application · `app/wallhaven`
- [Built bundle](https://github.com/amardeepxy/rand_wallhaven/blob/main/dist/index.cjs): compiled output · Generated CommonJS runtime bundle for distribution · `dist/index.cjs`
- [Package config](https://github.com/amardeepxy/rand_wallhaven/blob/main/package.json): npm package · Defines scripts and build/package metadata · `package.json`

### External

Outside services and binaries

- **User**: actor · Runs the CLI with wallpaper and transition options
- **Wallhaven API**: external api · Remote image source for random wallpapers
- **swww daemon**: local daemon · Wayland wallpaper service invoked by the adapter

## Connections

- User → wallhaven CLI: run · User invokes the installed command
- wallhaven CLI → Built bundle: execute · The packaged bundle starts the runtime
- Built bundle → Main app: load · Bundled entrypoint resolves the main app logic
- Main app → Wallhaven client: fetch wallpaper · Orchestrator asks for a random Wallhaven image
- Wallhaven client → Wallhaven API: HTTP request · Client communicates with the external wallpaper API
- Main app → swww adapter: apply wallpaper · Orchestrator passes selected image and transition settings
- swww adapter → swww daemon: command · Adapter calls the local swww service/binary
- Main app → Utilities: helpers · Main flow reuses shared utility functions
- Wallhaven client → Utilities: helpers · Client may reuse shared transformations or parsing helpers
- swww adapter → Utilities: helpers · Wallpaper adapter may reuse shared helpers
- Package config → wallhaven CLI: builds · Package metadata produces the distributable CLI
- Package config → Built bundle: bundle output · Build script emits the runnable CommonJS artifact
