# Albumen — Design Document

## Overview

Albumen is a self-hosted photo and media album. The guiding principle is
simplicity: the filesystem *is* the database. Every directory under
`MEDIA_ROOT` is an album; every image, video, or audio file inside it is
a media item. The only metadata that can't be derived from the filesystem
is stored in a small `album.json` sidecar file that lives alongside the
media in each directory.

There is no import step, no database to migrate, no ORM. Drop files into
a directory, run `update.rb`, and they are immediately browseable.

---

## System Architecture

```
Browser / mobile
      │  HTTPS
      ▼
Apache reverse proxy  (192.168.10.1 / albumen.jots.org)
      │  HTTP, forwards X-Forwarded-Proto
      ▼
Puma application server  (127.0.0.1:4567)
      │  Rack / Sinatra
      ▼
app.rb        ──reads──►  /var/albumen/   (media files + album.json + faces.json sidecars)
              ──reads──►  /opt/albumen/cache/thumbs/   (generated thumbnails)
              ──reads──►  /opt/albumen/config.yml       (password hash + session secret)

face_daemon.rb  ──reads──►  /var/albumen/   (image files)
                ──writes─►  /var/albumen/**/faces.json  (per-directory face sidecar)
```

### Process model

The web app runs as the `albumen` system user under systemd
(`config/albumen.service`). Puma is configured for 1 worker with 4–8
threads (`config/puma.rb`). Logs go to `/opt/albumen/log/`. On crash,
systemd restarts the process after 5 seconds.

The face detection daemon (`config/face_daemon.service`) runs as a
separate systemd service under the same `albumen` user. It polls
`MEDIA_ROOT` every `poll_interval` seconds (default 300), processes
any images not yet in a `faces.json` sidecar, and writes results
atomically. It never touches `album.json`, so there is no write
contention with `update.rb`. All process output is written to the
shared log at `/opt/albumen/log/albumen.log`.

### Reverse proxy

The proxy (Apache or nginx — a sample nginx config is in
`config/nginx-albumen.conf`) terminates HTTPS and forwards plain HTTP to
Puma on port 4567. It sets `X-Forwarded-Proto: https` so Sinatra's
redirect helpers produce correct `https://` URLs and
`Rack::Protection::HttpOrigin` sees the right scheme. `client_max_body_size`
is set to unlimited because large video files may be uploaded via rsync.

---

## Directory Layout

```
/opt/albumen/           ← application root (code + config)
  app.rb
  config.ru
  Gemfile / Gemfile.lock
  config/
    albumen.service     ← systemd unit file for the web app
    face_daemon.service ← systemd unit file for the face detection daemon
    puma.rb             ← Puma config
    nginx-albumen.conf  ← sample reverse-proxy config
  views/
    layout.erb          ← site chrome (header, nav)
    album.erb           ← browse page (grid + lightbox)
    slideshow.erb       ← full-screen slideshow page
    admin/
      login.erb
      album.erb         ← per-album edit form
  public/
    css/style.css
    js/album.js         ← lightbox logic
    js/slideshow.js     ← slideshow logic
    img/audio.svg       ← placeholder thumbnail for audio files
  scripts/
    update.rb           ← post-upload scan/enrich script
    face_daemon.rb      ← face detection daemon (polls for new images, writes faces.json)
    faces.py            ← dlib CNN face detection helper called by the daemon
    set_password.rb     ← PBKDF2-SHA256 password setter
  cache/thumbs/         ← generated thumbnail cache (mirrored path structure)
  tmp/                  ← Puma pid / state files
  log/                  ← Puma stdout / stderr logs
  config.yml            ← runtime secrets (not in git)

/var/albumen/           ← media root (owned by albumen user)
  album.json            ← root-level sidecar (optional)
  SomeAlbum/
    album.json          ← per-album metadata sidecar (owned by update.rb)
    faces.json          ← per-album face data sidecar (owned by face_daemon.rb)
    photo1.jpg
    photo2.jpg
    SubAlbum/
      album.json
      faces.json
      photo3.jpg
```

---

## Dependencies

### Ruby gems

| Gem | Purpose |
|-----|---------|
| `sinatra ~> 4.0` | HTTP routing and ERB rendering |
| `puma ~> 6.4` | Multi-threaded Rack application server |
| `mini_magick ~> 4.12` | ImageMagick wrapper — thumbnail generation, EXIF-aware auto-orient |
| `mini_exiftool ~> 2.10` | Reads EXIF `DateTimeOriginal` / `CreateDate` for chronological sorting |
| `rack-session ~> 2.0` | Cookie-based session support (required by Sinatra 4 separately) |

Password hashing uses `OpenSSL::PKCS5.pbkdf2_hmac` from Ruby's standard library
(100,000 iterations, SHA-256, 32-byte output). No native gem extension is required.

### System tools

| Tool | Purpose |
|------|---------|
| **ImageMagick** | Backing tool for MiniMagick — must be installed on the server |
| **ExifTool** | Backing tool for MiniExiftool — must be installed on the server |
| **ffmpeg** | Video thumbnail extraction (frame at 2 s) and duration probing via `ffprobe` |

### Optional: facial recognition

| Component | Purpose |
|-----------|---------|
| **Python 3** | Runtime for `scripts/faces.py` |
| **face_recognition** (PyPI) | dlib-backed face detection and 128-D embedding extraction |
| `/opt/albumen/venv/` | Python virtual environment isolating the dependency |

Install (one-time, takes ~30 min to compile dlib on CPU):

```bash
apt install python3-pip python3-dev python3-venv cmake build-essential libopenblas-dev liblapack-dev
python3 -m venv /opt/albumen/venv
/opt/albumen/venv/bin/pip install face_recognition
```

Enable by adding to `config.yml`:

```yaml
faces:
  enabled: true
```

When disabled (or when the venv doesn't exist), `update.rb` simply skips face detection and the
rest of the app is unaffected.

---

## Data Model — `album.json`

Each directory may contain an `album.json`. If none exists, defaults are
used. The file is written atomically (write to a `.tmp` file, then
`File.rename`) so a crash mid-write never corrupts existing data.

```json
{
  "title":        "Hawaii 2004",
  "description":  "Optional free-text shown below the album title.",
  "cover":        "dscn0929.jpg",
  "sort_reverse": false,
  "visible":      true,
  "files": {
    "dscn0929.jpg": {
      "title":    "Arrival at Kona",
      "caption":  "Ken at the airport, exhausted.",
      "visible":  true,
      "taken_at": "2004-06-15T14:23:00",
      "width":    2048,
      "height":   1536
    }
  }
}
```

**Top-level fields:**

| Field | Default | Meaning |
|-------|---------|---------|
| `title` | directory name | Display name for the album |
| `description` | `null` | Optional paragraph shown under the title |
| `cover` | `null` (auto) | Filename of the cover image, or `"__random__"` |
| `sort_reverse` | `false` | Reverses the order of sub-album cards |
| `visible` | `true` | If `false`, hidden from non-admin visitors |

**Per-file fields** (inside `"files"`):

| Field | Default | Meaning |
|-------|---------|---------|
| `title` | filename | Display name used in the lightbox caption bar |
| `caption` | `null` | Optional descriptive text shown under the title |
| `visible` | `true` | If `false`, hidden from non-admin visitors |
| `taken_at` | `null` | ISO 8601 timestamp from EXIF; used for chronological sorting |
| `width` / `height` | `null` | Pixel dimensions recorded by `update.rb` |
| `exif_absent` | `null` | Set to `true` by `update.rb` when exiftool found no metadata; skips re-extraction on future rescans |

When `taken_at` is present on *any* file in an album, the entire album is
sorted chronologically. Albums with no `taken_at` data stay in filename
order.

### Cover image selection

`album_cover(dir, data)` resolves what image to display as a sub-album's
tile:

1. If `cover` is a specific filename and that file exists → use it.
2. If `cover` is `"__random__"` → pick a random file from `cover_candidates`.
3. Otherwise (no cover set, or file missing) → use the first file from
   `cover_candidates`.

`cover_candidates(dir)` walks the entire directory tree recursively, so
albums that contain only sub-albums (no top-level photos) still produce a
cover.

---

## HTTP Routes

### Public

| Method | Path | Action |
|--------|------|--------|
| `GET` | `/` | Redirect → `/browse/` |
| `GET` | `/browse/` | Root album grid |
| `GET` | `/browse/*` | Sub-album grid at that path |
| `GET` | `/thumb/*` | Serve (or generate) a 300×300 JPEG thumbnail |
| `GET` | `/media/*` | Serve the original media file |
| `GET` | `/slideshow/` | Full-screen slideshow for the root |
| `GET` | `/slideshow/*` | Full-screen slideshow for a sub-album |

### Admin

| Method | Path | Action |
|--------|------|--------|
| `GET` | `/admin` | Redirect to edit or login |
| `GET` | `/admin/login` | Login form |
| `POST` | `/admin/login` | Authenticate; set session; redirect |
| `GET` | `/admin/logout` | Clear session; redirect to `/` |
| `GET` | `/admin/edit/` | Edit root album |
| `GET` | `/admin/edit/*` | Edit a specific album |
| `POST` | `/admin/edit/` | Save root album edits |
| `POST` | `/admin/edit/*` | Save album edits |

---

## Request Flows

### Browsing an album (`GET /browse/SomeAlbum`)

1. `resolve_dir("SomeAlbum")` expands the path against `MEDIA_ROOT` and
   verifies it doesn't escape that root (path traversal guard).
2. `load_album(dir)` reads `album.json` (or returns defaults).
3. `halt 403` if the album is marked invisible and the visitor isn't an admin.
4. `child_albums(dir, data)` scans immediate subdirectories, loads each
   sub-album's `album.json`, calls `album_cover` for each, and builds the
   grid data. Hidden sub-albums are excluded for non-admins.
5. `album_files(dir, data)` scans media files, merges per-file metadata,
   filters hidden items, and sorts by `taken_at` if available.
6. The `ENTRIES` array (JSON-serialized) is embedded directly in the HTML
   so `album.js` can operate without any further server round-trips.
7. Sinatra renders `views/album.erb` wrapped in `views/layout.erb`.

### Serving a thumbnail (`GET /thumb/SomeAlbum/photo.jpg`)

1. Path traversal check via `resolve_file`.
2. Audio files return `public/img/audio.svg` immediately (no generation needed).
3. Visibility check: if `album.json` marks the file hidden and visitor isn't
   admin → `403`.
4. Check the thumbnail cache at
   `/opt/albumen/cache/thumbs/SomeAlbum/photo.jpg.th.jpg`.
5. Cache miss → `generate_thumb`:
   - **Image:** MiniMagick auto-orients (reads EXIF rotation), then
     thumbnail-scales to 300×300 with center-crop to guarantee a square.
   - **Video:** `ffmpeg` seeks to 2 seconds, extracts one frame, and
     scales/crops to 300×300.
6. Serve the cached JPEG.

Thumbnails are never regenerated once created. To force regeneration,
delete the cache file (or the entire `cache/thumbs/` tree — it is safe to
wipe at any time).

### Opening a photo in the lightbox (client-side)

The album page embeds the full `ENTRIES` array in a `<script>` block, so
no server call is needed to open or navigate the lightbox.

1. Click on a card → `openLightbox(i)` → `renderLightbox()`.
2. All three media elements (`#lb-img`, `#lb-video`, `#lb-audio`) get
   `.hidden` (i.e. `display:none !important`).
3. The appropriate element for the media type has `.hidden` removed and its
   `src` set. For video and audio, playback starts immediately.
4. The URL is updated to `?photo=filename` so the link is shareable and
   the server can read it. On page load, if that parameter is present,
   the matching photo is opened automatically.
5. Navigation: ← → arrow keys, on-screen buttons, or touch swipe (>50 px).
6. Closing: `Escape`, the ✕ button, or clicking outside the media.
   Video/audio is paused; the `?photo=` param is stripped from the URL.

### Slideshow (`GET /slideshow/SomeAlbum`)

The slideshow page is a separate full-screen layout. `SS_ENTRIES` (images
and videos only — audio is excluded in `slideshow_view`) is embedded in the
page. `slideshow.js`:

- Preloads the next image before cross-fading so transitions are smooth.
  Videos can't be preloaded; they fade out first, then swap.
- Cross-fade is a CSS opacity transition (500 ms); JS adds/removes
  `.fading` and uses a matching `setTimeout`.
- A `<input type="number">` lets the visitor set the interval (default 4 s,
  range 1–60 s); it is read live on each advance so changes take effect
  without restarting.
- Controls: Prev / Pause-Play / Next buttons, ← → arrow keys, spacebar,
  touch swipe.

### Admin authentication

A single PBKDF2-SHA256 password hash is stored in `config.yml`
(`admin_password_hash`) in the format `pbkdf2_sha256$<iterations>$<salt>$<hex>`.
`POST /admin/login` re-derives the key from the submitted password and compares
using `OpenSSL.fixed_length_secure_compare` (constant-time). On success,
`session[:admin] = true` is set in an encrypted cookie. All admin routes
call `require_admin!` which halts with the login form on failure.

The `return_to` parameter on the login form redirects the visitor back to
the page they came from — the "Admin" nav link passes the current album's
edit URL so logging in lands directly in the right edit view.

### Open Graph meta tags

Every album page includes `og:title`, `og:url`, `og:type`, and (when
available) `og:description` and `og:image`. The image is resolved
deterministically in `browse_album`:

- If the request includes `?photo=filename`, `og:image` points to the
  full-resolution `/media/` URL for that specific file — so sharing a
  photo link previews that exact photo.
- Otherwise, the first image from `@entries` (chronological/filename order)
  is used, falling back to `cover_candidates(dir).first` if the album has
  no direct media files.

`request.base_url` is used to build absolute URLs, so the tags are correct
regardless of hostname or scheme.

### Filtered slideshow

When the album search filter is active on the root page, the Slideshow
button href is dynamically updated (via `album.js`) to include
`?dirs=name1,name2,...` — the `data-rel` values of the currently visible
album cards. `slideshow_view` in `app.rb` passes these to
`all_media_entries(top_dirs:)`, which walks only those specific
subdirectories instead of the full media tree.

### Saving album edits (`POST /admin/edit/SomeAlbum`)

1. `load_album(dir)` reads current state.
2. Top-level fields (title, description, cover, sort_reverse, visible) are
   updated from form params. `blank_to_nil` converts empty strings to `nil`
   so omitted optional fields don't get stored as `""`.
3. Per-file fields (caption, visible) are updated by iterating the
   `file_visible[name]` param hash (present for every file via a hidden
   input), merging `file_caption[name]` for each.
4. `atomic_write` writes the updated JSON to a `.tmp` file and renames it
   into place.
5. Redirect back to the same edit page (PRG pattern — prevents double-submit
   on reload).

---

## The `update.rb` Script

Run this after copying new media files onto the server. It is safe to
re-run at any time — all operations are idempotent.

```bash
ruby /opt/albumen/scripts/update.rb            # full tree, skip unchanged dirs
ruby /opt/albumen/scripts/update.rb 2024-Italy # explicit subtree, always runs
ruby /opt/albumen/scripts/update.rb --force    # full tree, ignore all sentinels
```

**Change detection** — each directory gets a `.albumen_scanned` sentinel file
whose mtime is set at the end of a successful scan. On subsequent runs the
script compares `sentinel.mtime >= dir.mtime`: if true the directory is skipped
entirely (no file I/O). A global run with nothing new completes in well under a
second regardless of library size.

Providing an explicit subdirectory argument bypasses the sentinel for that
subtree, so `update.rb some-album` always rescans that album even if the
directory mtime appears unchanged. `--force` bypasses sentinels for the whole
tree.

**What it does, per directory (when not skipped):**

1. Reads the existing `album.json` (or starts from defaults).
2. Removes stale `files` entries for deleted files (and their thumbnails).
3. For each media file:
   - **Images:** reads EXIF `DateTimeOriginal` (or `CreateDate`) and stores
     it as `taken_at`; reads pixel dimensions. Both are skipped if already
     recorded. If exiftool finds no metadata at all, sets `exif_absent: true`
     so the tool is not re-invoked on future rescans of that file.
   - **Videos:** runs `ffprobe` to record duration. Skipped if already
     recorded.
   - **All non-audio:** generates a thumbnail if one doesn't already exist.
4. Re-reads `album.json` immediately before writing (to catch any admin
   saves that happened concurrently) and preserves all admin-controlled
   fields (`title`, `description`, `cover`, `sort_reverse`, `visible`,
   per-file `title`/`caption`/`visible`).
5. Writes the updated JSON atomically.
6. Touches the `.albumen_scanned` sentinel so the next global run skips
   this directory.

**Ownership:** When run as root (the typical case after an rsync), the
script calls `FileUtils.chown_R` to transfer ownership of the media tree
to the `albumen` user so the web app can read the files.

---

## Facial Recognition (opt-in)

Enabled by setting `faces.enabled: true` in `config.yml`. When disabled,
no Python is invoked and no face data is stored or displayed.

### Architecture: separate daemon

Face detection runs in a completely separate process (`scripts/face_daemon.rb`,
managed by `config/face_daemon.service`) and is entirely decoupled from
`update.rb`. This design keeps the two operations from conflicting:

- **`update.rb`** owns `album.json` in each directory. It indexes media,
  extracts EXIF data, and generates thumbnails as fast as possible so
  newly uploaded photos are browseable immediately.
- **`face_daemon.rb`** owns `faces.json` in each directory. It runs
  continuously in the background, processing images that haven't been
  detected yet. There is no file locking or write contention between the
  two processes.

### Data model — `faces.json`

Each directory gets a `faces.json` sidecar written by the daemon:

```json
{
  "photo1.jpg": [
    {"box": [top, right, bottom, left], "encoding": [128 floats]},
    ...
  ],
  "photo2.jpg": [],
  "photo3.jpg": null
}
```

| Value | Meaning |
|-------|---------|
| key absent | not yet processed |
| `null` | error during last detection attempt; will retry |
| `[]` | processed successfully, no faces found |
| `[{box, encoding}, ...]` | one entry per detected face |

`app.rb` reads `faces.json` via `load_faces(dir)` and merges face data
into each entry's `:faces` field. The field is `nil` (absent key in
`faces.json`) when the daemon hasn't processed the image yet.

### Detection pipeline

The daemon shells out to `scripts/faces.py`, which uses the **CNN model**
(`model="cnn"`) for higher accuracy. The CNN model detects:
- Faces at angles up to ~45° profile
- Small faces in group photos
- Faces in non-ideal lighting

Trade-off: CNN is ~10–30× slower than HOG on CPU. The daemon compensates
with `--workers N` (default 20) — dlib releases the Python GIL during
C++ inference, so threads achieve genuine CPU parallelism.

`faces.py` accepts a batch of image paths and returns a JSON dict mapping
each path to its result list. Null for a path means detection failed
(file unreadable or corrupt); the daemon marks that entry `null` in
`faces.json` so it is retried on the next pass.

Encodings are stored in full (128 floats each) to allow re-clustering
without reprocessing all images.

### Daemon operation

```
loop:
  for each directory in MEDIA_ROOT (recursive):
    pending = images whose name is absent from faces.json (or null)
    if pending not empty:
      call faces.py --workers 20 <pending paths>
      merge results into faces.json (atomic write)
  sleep POLL_INTERVAL seconds (default 300, in 1-second increments for prompt shutdown)
```

SIGTERM / SIGINT trigger graceful shutdown between directories.

### Configuration

```yaml
faces:
  enabled: true
  workers: 20         # threads passed to faces.py
  poll_interval: 300  # seconds between full-tree sweeps
```

### Performance notes

- CNN face detection with 20 workers: ~4–6 images/minute on a 64-core CPU.
- A library of ~20,000 photos takes roughly 2.5–3.5 days on initial pass.
- Subsequent daemon passes only process new photos.
- Encodings stored in `faces.json` are ~3.5 KB per face. A library with
  an average of 2 faces per photo adds ~70 MB of JSON across 10,000 photos
  — negligible.

### Clustering and people management (planned)

A second pass (`scripts/cluster_faces.rb`) will:

1. Walk all `faces.json` files and collect every `{encoding, source_file, box}` tuple.
2. Cluster them with a threshold distance (~0.6 in L2 space, empirically good for dlib encodings).
3. Write `/var/albumen/people.json` — a map of stable UUIDs → cluster metadata.

The admin `/admin/people` UI will let you name clusters, merge duplicates,
and remove false positives. Public `/people` routes will allow browsing by
person.

---

## Security

**Path traversal:** `resolve_dir` and `resolve_file` call `File.expand_path`
to canonicalise the path (resolving any `..` components) and then assert
that the result starts with `MEDIA_ROOT + "/"`. Any request that would
escape the media root gets a `404`.

**Visibility enforcement:** The `/thumb/*` and `/media/*` routes check
`album.json` visibility for every request. A file marked `visible: false`
returns `403` unless the session has admin privileges. The browse routes
filter hidden albums and files from the data sent to the browser.

**Admin password:** Stored as a PBKDF2-SHA256 hash in `config.yml` (not in git).
The plaintext password is never persisted. Sessions use an encrypted cookie
with a random secret also stored in `config.yml`.

**HTTPS:** Terminated at the reverse proxy. The app itself only listens on
`127.0.0.1:4567` and is not reachable directly from the network.

---

## Deployment

### After code changes

```bash
scp -r /home/ken/albumen/. root@192.168.10.245:/opt/albumen/
ssh root@192.168.10.245 'chown -R albumen:albumen /opt/albumen && systemctl restart albumen'
```

### After uploading new photos

```bash
# On the server (run as root):
ruby /opt/albumen/scripts/update.rb [optional-subdir]
```

The script fixes ownership automatically when run as root, so it can be
called immediately after an rsync without a separate chown step.

### Thumbnail cache

`/opt/albumen/cache/thumbs/` mirrors the `MEDIA_ROOT` path structure.
The cache is entirely derived data — it can be deleted at any time and will
be rebuilt on demand as visitors browse. To pre-warm the cache after a bulk
upload, run `update.rb` (it generates thumbnails as part of its scan).

### Configuration (`config.yml`)

```yaml
admin_password_hash: "pbkdf2_sha256$100000$<salt>$<hex>"  # set with scripts/set_password.rb
session_secret: "random-hex-string"                        # set once at install time
```

This file is not tracked in git. All three paths (`MEDIA_ROOT`,
`CACHE_ROOT`, `CONFIG_PATH`) can be overridden with environment variables
for local development.