# pathways

A photo viewer that organises a PhotoPrism library into paths — shared labels,
keywords, cameras, lenses, and dominant colours — instead of a flat grid or
albums.

The live instance lives at <https://pathways.dax.ist> and reads the PhotoPrism
database directly (read-only) on the same machine. PhotoPrism's admin UI
stays behind basic auth at <https://prism.dax.ist>; pathways is public.

## How it works

- `server.mjs` — a single Node process (`nodejs_22`, no build step). It pools
  the MariaDB `photoprism` database, groups the primary files into *paths*
  (facets with ≥3 photos) and exposes three endpoints:
  - `GET /api/paths` — every photo (id, thumb, title, date) plus the paths
  - `GET /api/photo/:id` — one photo plus its connections across labels,
    keywords, camera, and lens
  - `GET /api/health` — liveness probe
- `public/` — the front end. Progressive reveal on scroll, a lightbox with
  connection chips that jump you to the linked path, and a dominant-colour
  swatch under every thumbnail. In colour mode the paths themselves are
  computed client-side from each photo's dominant hue.

Thumbnails are served as static files by Caddy from
`/srv/photoprism/storage/cache/thumbnails/{a}/{b}/{c}/{hash}_{size}.jpg`
(`720x720_fit` for the grid, `1920x1200_fit` in the lightbox).

## Run it

```bash
npm install
DB_HOST=127.0.0.1 DB_USER=photoprism DB_PASSWORD=… DB_NAME=photoprism \
  PORT=3100 THUMBS_ROOT=/srv/photoprism/storage/cache/thumbnails \
  node server.mjs
```

On NixOS the box runs it as a systemd unit (`systemd.services.pathways`),
started after `mysql.service`, as user `dax`.

## Layout

```
server.mjs        API + static file serving
public/index.html viewer page
public/app.css    styling
public/app.js     viewer logic (paths, colours, lightbox)
```

The thumbnail path sharding matches PhotoPrism: directory = first three
characters of the file hash. Note `file_hash` comes back from MariaDB as a
binary Buffer, so it is decoded to a string before building URLs.