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 a JSON API and an embedded browser interface from the same process.

How it fits together

Section titled “How it fits together”

Architecture diagram showing wallpaper source folders and uploads flowing through analysis into an in-memory index and disk cache, then a Go HTTP server serving clients.

Configured folders ─┐
                    ├─ Scanner → Analysis → Index
Uploads ────────────┘                  │
                                       ├─ Filter engine
                                       ├─ Image endpoints
                                       ├─ Metadata endpoints
                                       └─ Browser gallery / server / settings


Source images → Processing → Disk cache

The current client CLI uses the same public HTTP endpoints for metadata and image downloads as browser automation. Uploads and settings use guarded administrative routes; see Security and remote access.

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 browser interface share one server. The gallery at /, server overview at /server, and settings page at /settings are served by the same process that answers /api/... requests.

Runtime and trust boundary

Section titled “Runtime and trust boundary”

The request stack is the Go HTTP server, request logging, administrative access middleware and route handlers. Public retrieval endpoints remain accessible to reachable network clients; administrative endpoints require loopback access or a configured bearer token. The server has no built-in TLS or browser login. The exported source path is omitted from JSON metadata.

The in-memory wallpaper index is rebuilt by rescanning folders; uploads are included in scans even when the upload directory is not listed among the source folders. User-defined favourites, smart collections and persistent rotation histories are not yet implemented.

Section titled “Related”