Skip to content
Wallpaper Server Wallpaper Server Docs

Architecture

Wallpaper Server is a single Go binary with no external database. It scans your folders, analyses each image, keeps an in-memory index, and serves both a JSON API and a browser gallery from the same process.

How it fits together

Section titled “How it fits together”
Configured folders ─┐
                    ├─ Scanner → Analysis → Index
Uploads ────────────┘                  │
                                       ├─ Filter engine
                                       ├─ Image endpoints
                                       ├─ Metadata endpoints
                                       └─ Browser gallery


Source images → Processing → Disk cache

The pipeline, in words: configured source folders and uploaded files are walked by the scanner; each image is passed through analysis (brightness, hue, aspect ratio, orientation); the results populate an in-memory index. Incoming requests run through the filter engine and are answered either as direct images or as JSON metadata. Cached copies and thumbnails are written to the disk cache.

Key properties

Section titled “Key properties”
  • Single binary, no database. State lives in the in-memory index plus the on-disk cache. A refresh rebuilds the index atomically.
  • Configuration is YAML. Loaded from a file chosen by flag, environment variable or the XDG default path — see configuration.
  • The API and gallery share one server. The gallery at / is served by the same process that answers /api/... requests.
Section titled “Related”