Skip to content

User guide

The web UI is a single-page vanilla-JS application. There are nine top-level views plus the gear-icon admin modal, the "Search by example" modal, and the bottom status bar. On phones it installs as a progressive web app with a bottom navigation bar — see Mobile & PWA.

📷 Photos

The main infinite-scroll grid with date rail, "On this day", and the full-res detail panel.

Zero-shot CLIP text search and "find photos of a person from a photo" face search.

👥 People

Auto-clustered persons, naming, merging, the per-person map, and the people duplicates finder.

🏷️ Face tagging

Clickable face boxes, naming one face auto-tags look-alikes, the unassigned queue.

🗺️ Places

Leaflet world map with clustered city markers and a city list.

🖼️ Albums & tags

Proton albums (read-only) and your free-form lowercase tags.

⭐ Favorites & archive

Star, archive, hide, content-hash duplicates.

📱 Mobile & PWA

Install on iOS/Android/desktop, offline app shell, the phone-first layout.

⚙️ Admin area

Gear-icon modal: server info, health checks, backups, schedule, users.

🔎 Status & diagnostics

Bottom status bar + ? overlay — every view shows live indexer state.

Top-level navigation

The header bar has:

  • App title (clickable, takes you to Photos)
  • View tabs — Photos · ★ Favorites · Archive · People · Places · Albums · Tags · Duplicates · Unassigned
  • Search bar — <input id="q"> + Search button + Search by example button
  • ⚙ gear (admin only) — opens the admin modal

On phones (below 940px) the view tabs move to a fixed bottom bar and Duplicates/Unassigned are hidden — see Mobile & PWA.

The bottom status bar shows:

  • Bridge reachability (Proton: connected / Proton: offline)
  • Indexer stats (X/Y photos indexed · … people · … faces)
  • Last sync timestamp
  • Press ? for details

The account menu

Click your username chip (bottom-left) to open the account menu. Every signed-in user can:

  • Change password — requires the current password; every other session is signed out.
  • Enable / disable 2FA — enroll with an authenticator app (QR code or manual secret), or disable with a 6-digit code.
  • Sign out — revokes the current session.

Admins additionally get the gear icon and the Users tab (see Admin area).

Roles

The login modal signs you in as one of three roles:

Role Browse, search, map, albums, places, memories Per-user ★ favorites Tags, archive, hide, face naming, person rename/merge
read ✅ ✅ ❌
write ✅ ✅ ✅
admin ✅ ✅ ✅ + admin area (users, backups, schedule, health)

Admins are the only ones who see the gear icon and the Users tab inside People.

Keyboard shortcuts

Key Action
Enter (in the search bar) Run the current query
Esc Close any open modal (photo detail, face popover, admin modal, status overlay)
? (clickable in the footer) Open the Status & diagnostics overlay

The UI is otherwise mouse/touch driven.

Pick a view from the cards above to dive in.