1 files changed, 52 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..346e910
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+# 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.