Photofield

Photofield is a high‑performance, tile‑based photo viewer designed for self‑hosted deployments. At its core, the application exposes a web‑based UI that streams multi‑resolution image tiles directly from an underlying storage layer, enabling instantaneous zoom and pan across tens of thousands of photos without the need for pre‑generated thumbnails. The viewer’s architecture leverages OpenLayers on the front end to orchestrate tile requests and compositing, while a lightweight Go server handles authentication, request routing, and image metadata lookup. The combination of static file serving for tiles and a minimal REST API for gallery management keeps the runtime footprint small, making it ideal for containerized environments or edge deployments.

Architecture

• Frontend – A single‑page application built with vanilla JavaScript and the OpenLayers library. It consumes a JSON metadata feed and requests image tiles over HTTP(S) using standard GET semantics. The UI is intentionally stateless; all view state (zoom level, pan offset, selected album) is encoded in the URL hash, enabling deep linking and bookmarkability.
• Backend – Implemented in Go (1.22+), the server provides three primary endpoints: /api/albums, /api/photos, and /tiles/{z}/{x}/{y}.jpg. The tile endpoint streams pre‑generated tiles from a local or network file system, while the API endpoints query a lightweight SQLite database that stores photo UUIDs, paths, dimensions, and optional EXIF metadata. The server uses gorilla/mux for routing and go-chi/render for JSON serialization.
• Storage – Photofield expects images to be stored in a directory hierarchy that mirrors the UUID namespace. Tile generation is performed offline using vips or ImageMagick, producing a set of pyramidal tiles per image. The application can also be configured to use an S3‑compatible object store; the tile endpoint simply proxies requests to the storage backend.
• Deployment – The entire stack is distributed as a single OCI image (ghcr.io/smilyorg/photofield) with a slim Alpine base. Docker Compose files and Helm charts are available for quick provisioning in Kubernetes or Docker Swarm. The service is stateless, allowing horizontal scaling behind a load balancer with sticky sessions disabled.

Core Capabilities

• Tile Streaming API – Exposes a /tiles/{z}/{x}/{y}.jpg endpoint that conforms to the Slippy Map tile schema, enabling integration with any client that understands XYZ tiles (OpenLayers, Leaflet, Mapbox GL).
• Gallery Management API – CRUD operations on albums and photos via /api/albums and /api/photos. Supports bulk uploads, tagging, and pagination.
• Metadata Extraction – On image ingestion, the Go service reads EXIF data (camera model, GPS coordinates) and stores it in SQLite. A /api/photos/{id}/metadata endpoint exposes this data for client consumption.
• Progressive Loading – The viewer first renders low‑resolution tiles and progressively refines them as the user zooms, providing a smooth experience even on limited bandwidth connections.

Deployment & Infrastructure

Photofield is designed for self‑hosting on commodity hardware. A single CPU core can comfortably serve a 10 k photo gallery with sub‑second tile response times, thanks to the pre‑generated tile cache. The application’s stateless nature means you can run multiple replicas behind a CDN or reverse proxy (e.g., Nginx, Traefik) without session affinity. Containerization is fully supported: the Docker image includes health checks, and the application can be orchestrated with Kubernetes ConfigMaps for configuration and PersistentVolumes for image storage. For high‑availability scenarios, a shared file system (NFS, GlusterFS) or object store ensures all replicas see the same tile cache.

Integration & Extensibility

• Plugin System – Photofield exposes a simple Go interface (PhotoProvider) that allows developers to plug in custom backends (e.g., Google Cloud Storage, Azure Blob). Implementing the interface requires only a handful of methods (ListPhotos, GetTile).
• Webhooks – When a new photo is uploaded or an album is updated, the server can emit JSON webhooks to external services (e.g., Slack, CI pipelines). The webhook payload includes photo ID, URL, and metadata.
• Custom Frontends – Because the tile API follows a standard schema, any JavaScript framework can consume it. Developers have already built integrations for React, Vue, and even native mobile wrappers using Cordova or Capacitor.
• Extensible Metadata – The SQLite schema can be extended with additional columns or JSON blobs, allowing custom tags, access control lists, or AI‑generated captions to be stored alongside each photo.

Developer Experience

The configuration is managed via environment variables (PHOTOFIELD_STORAGE_PATH, PHOTOFIELD_DB_FILE, PHOTOFIELD_PORT). The documentation (available at https://photofield.dev) is concise yet comprehensive, covering API endpoints, tile generation scripts, and deployment guides. An active Discord community provides quick support for integration questions, while the open‑source license (MIT) encourages experimentation and forkability. The codebase follows idiomatic Go patterns, making it approachable for developers familiar with the language.

Use Cases

• Enterprise Asset Management – A media company can host a private gallery for thousands of high‑resolution assets, providing editors with instant zoom and pan without the latency of cloud