PhotoPrism

Promptfree, for everyone, and the only version there is

Copy the prompt for Claude CodeCopy the prompt for CodexCopy the prompt for Cursor

Copy

Build me the photo library I actually need in the shape PhotoPrism has: my own pictures, searchable, with recognition running on my own machine.

Read this first: PhotoPrism is free to run — the subscription buys support and extras. And be honest about the two halves: browsing and searching your library is one problem, and never losing it is another. This prompt covers both, and the second one is the part that matters in ten years.

STACK
- Node 20+ with Fastify
- SQLite through better-sqlite3, WAL mode, with FTS5
- sharp for thumbnails, ffmpeg for video, exiftool for metadata
- Recognition models running locally through ONNX Runtime — never a cloud vision API
- Caddy in front, on a private network

THE DATA MODEL
- photos: id, path, filename, sha256, bytes, kind, width, height, orientation, taken_at_local, taken_at_offset, timezone, camera_make, camera_model, lens, iso, aperture, shutter, focal_length, latitude, longitude, altitude, is_favourite, is_hidden, is_private, quality_score, deleted_at, indexed_at
- files: id, photo_id, path, role, sha256, bytes — a RAW and its JPEG are one photo with two files, and so are a live photo's halves
- derivatives: id, photo_id, kind, path, width, bytes — thumbnails and transcodes, regenerable and therefore not backed up
- labels: id, photo_id, name, confidence, source — from the local classifier
- faces: id, photo_id, bbox_json, embedding_blob, cluster_id, person_id, confidence
- people: id, name, cover_photo_id, is_hidden
- places: derived from coordinates against an offline gazetteer, never an online lookup
- albums, album_photos, tags, and a search index over everything above
- The original file is never modified. Not to rotate, not to strip, not ever. Edits produce a sidecar or a derivative

INDEXING
- Walk the library, hash every file, read its metadata, generate derivatives, run recognition. All in a worker with a visible queue
- Idempotent: re-indexing must not duplicate, and a file that has not changed is skipped by hash
- RAW files decoded once and cached, because decoding is expensive and will otherwise happen on every view
- Stacking: a RAW with its JPEG, a live photo with its video, a burst — one photo with several files, and one entry in the timeline
- Duplicates found by hash and by perceptual hash, offered for review rather than deleted automatically

TIME AND PLACE, WHICH IS WHERE THESE GO WRONG
- Store the local time the photo was taken and its offset separately. A photo taken at 8pm on holiday was taken at 8pm, and showing it as 3pm because the server is elsewhere is wrong in a way people notice instantly
- Missing metadata falls back to the filename pattern, then the file time, and the source of the date is recorded so a wrong one can be found
- Coordinates resolved against an offline gazetteer to a country, region and place name
- Private by default: a location is personal data, and there must be a switch to strip coordinates from anything shared or exported

RECOGNITION, LOCALLY
- Object and scene labels from a local model, stored with a confidence, and shown as suggestions rather than facts
- Face detection and embedding, clustered into people, named by hand. Never sent anywhere. A face is biometric data, and running it locally is the entire point
- Optional text recognition, so a photo of a sign becomes searchable
- Every model runs on your own machine. If a feature would require sending an image to somebody else's service, it does not get built

SEARCH
- FTS5 and structured filters together: dates, places, people, cameras, lenses, labels, colours, orientation, quality
- Natural queries composed from those parts — 'photos of Anna in Rome in 2019' is three filters, not a language model
- Saved searches as albums that stay live

BROWSING
- A timeline that scrolls years quickly, grouped by day and month, with the scrollbar labelled by date
- Albums, favourites, a map, and people
- A viewer with the metadata visible, keyboard navigation, and instant next and previous
- Hidden and private albums that are genuinely excluded from search results and shared links

SHARING
- A link with a long unguessable token, an optional password and an expiry, revocable, with coordinates stripped by default
- The shared page exposes nothing but what was shared, including in whatever the page calls behind it

STORAGE AND THE THING THAT MATTERS
- Originals in a dated directory structure, usable with no software at all if this application disappears. That property outranks every feature
- The database rebuildable from the files and their sidecars — write that command and test it
- A second copy off the machine, always, with its own verification. RAID is not a backup and a snapshot on the same disk is not a backup
- A scheduled job re-hashing a sample of originals and reporting anything that changed. Silent corruption over a decade is the failure nobody plans for
- A restore rehearsed onto a clean machine, with the time it took written down

OPERATIONS
- .env: DATABASE_PATH, LIBRARY_PATH, DERIVATIVE_PATH, BASE_URL, SESSION_SECRET, MODEL_PATH, GAZETTEER_PATH
- Migrations on boot, each once
- Behind a VPN rather than exposed
- Health endpoint reporting free space, queue depth and the age of the last verified backup

WHAT MATTERS MOST
The index rebuild and the second copy. Make sure the database can be regenerated from the files, then set up and restore from the off-site copy before this becomes the only place your photographs live.

Give me the repository, the indexer, migrations, .env.example, the backup, restore and rebuild scripts, and a README that opens with the restore rehearsal.