7.1 KiB
Plex for Photos — Self-Hosted Photo Library Architecture
A self-built media server for your photo collection, running as another container in your homelab. Follows the same pattern as your existing study app: React/Vite frontend + Express/SQLite backend, files stay on disk, DB just indexes them.
High-Level Flow
┌───────────────────┐ watches ┌──────────────────────┐
│ Photo Library │ ─────────────────────▶ │ Ingestion Engine │
│ (disk / NAS) │ │ (chokidar file watch)│
└───────────────────┘ └───────────┬───────────┘
│ extract EXIF,
│ generate poster,
│ compute pHash
▼
┌──────────────────────┐
│ SQLite metadata DB │
│ (photos, collections,│
│ hashes, artwork) │
└───────────┬───────────┘
│
▼
┌──────────────────────┐
│ Express API server │
└───────────┬───────────┘
│ REST/WS
▼
┌──────────────────────┐
│ React/Vite frontend │
│ (browse, collections,│
│ discover, map) │
└──────────────────────┘
Original files never move or duplicate — the DB just points to paths on disk. Posters (thumbnails) are the only generated/derived asset stored separately (for instant browsing and discovery views).
Components
Ingestion Engine
Stack: Node + chokidar (file watcher) or a scheduled scan job
On new file detected:
- Extract EXIF (date taken, GPS, camera model, orientation) — exifr or exiftool wrapper
- Generate posters (e.g., sharp) at multiple sizes — grid poster + hero/preview size
- Compute a perceptual hash (pHash via sharp + blockhash-core) for smart duplicate detection
- Insert a row into SQLite: path, EXIF fields, poster path, hash, import timestamp
Runs as a background process inside the same container, or a separate lightweight worker container if you want to isolate it from the API.
Database (SQLite)
Core tables to start with:
| Table | Purpose |
|---|---|
photos |
id, filepath, poster_path, date_taken, date_imported, camera_model, gps_lat, gps_lon, phash, width, height, filesize |
collections |
id, name, created_at, description, poster_path |
photo_collections (join) |
photo_id, collection_id |
tags |
id, name |
photo_tags (join) |
photo_id, tag_id |
Matches the SQLite pattern you're already using in the study app — no new infra to stand up.
API Server (Express)
- GET /photos — paginated library query (filter by date range, tag, collection)
- GET /photos/:id — full detail + EXIF metadata
- GET /photos/similar — grouped by similar pHash (within a distance threshold)
- POST /collections, POST /photos/:id/tags — manual organization endpoints
- GET /photos/map — GPS-tagged photos for map view
- Poster serving — directly via endpoint or Nginx for static file efficiency
Frontend (React/Vite)
- Browse view — infinite scroll, grouped by day/month, lazy-loaded posters (like Plex's continuous feed)
- Collection/tag views — same grid, filtered (like Plex collections for photos)
- Detail view — full image, EXIF panel, tag editor, related photos
- Duplicate review — side-by-side similar photos with keep/flag workflow (like Plex's duplicate management)
- Map view — Leaflet/MapLibre pins from GPS EXIF, click to open photo
- Discovery/search — date range, camera, tag filters, full-text search
Smart Duplicate Detection (High Value — Do This Early)
At import time, compute pHash for every photo. On a scheduled job (or on-demand from a "Find Similar" button), compare hashes pairwise within a similarity threshold (Hamming distance) to group near-duplicates — burst shots, slightly different crops, etc.
Surface groups in a review UI rather than auto-deleting — you make the call, app just surfaces the candidates. This is much cheaper computationally than face recognition and gives you the real "cleanup" value people want from a photo manager.
Face Grouping (Optional, Scope Carefully)
If you want this eventually:
Options: face-api.js (runs in Node, ONNX-based, no Python needed) or a Python microservice using face_recognition/dlib if you're OK adding a Python component.
Store face embeddings + bounding boxes in a faces table, cluster embeddings to group "this looks like the same person" without needing named identities upfront — you label clusters after the fact.
This is the single biggest scope jump — worth treating as a v2/v3 feature, not part of the initial build.
Deployment Fit
New container (photo-library), same pattern as your other homelab services:
- Mounts your existing photo backup folder(s) read-only (ingestion engine doesn't need write access to originals) plus a writable volume for posters/DB
- Nginx Proxy Manager route (photos.necloud.us), behind Authelia like your other private services
- No external dependencies — everything runs locally against files already on disk
Suggested Build Order
- Ingestion engine + SQLite schema — watch folder, extract EXIF, generate posters, populate DB (get this solid before touching UI)
- Basic API + browse UI — paginated grid, chronological browsing — this alone is already usable
- Detail view + manual tagging/collections
- Smart duplicate detection + review UI — high value, moderate effort
- Search + filters
- Map view (if your library has meaningful GPS data)
- Face grouping (only if you still want it after living with V1–V6 for a while)