fix(notes): page PhotoPrism server-side so /notes shows every captioned photo

Client-side paging of listPhotosWithNotes stopped early for BasePath users:
the sidecar post-filters each page by BasePath, so a full upstream page can
arrive short, tripping the `length < PAGE` end condition before the library
is exhausted — hiding notes past the first slice.

Add GET /api/sidecar/notes: the sidecar pages /api/v1/photos to completion
(keying the loop off the raw upstream page length), filters to non-empty
Caption under the caller's BasePath, dedupes by UID, and returns the set.
listPhotosWithNotes now calls this single endpoint.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env

@@ -1,23 +0,0 @@
-# Environment variables for Mulita
-
-# Photo directories to mount (can be multiple paths separated by colon)
-# Example: /path/to/photos1:/path/to/photos2
-PHOTO_DIRS=./photos
-
-# Redis configuration
-REDIS_URL=redis://localhost:6379
-
-# Database URL
-DATABASE_URL=sqlite+aiosqlite:///data/db/mulita.db
-
-# Celery configuration
-CELERY_BROKER_URL=redis://localhost:6379
-CELERY_RESULT_BACKEND=redis://localhost:6379
-CELERYD_CONCURRENCY=4
-
-# API settings
-API_HOST=0.0.0.0
-API_PORT=8000
-
-# Frontend settings
-VITE_API_URL=http://localhost:8000

.env.example

@@ -0,0 +1,83 @@
+# Example environment file. Copy to `.env` and adjust.
+#
+#   podman-compose --env-file .env \
+#     -f docker-compose.yml -f docker-compose.podman.yml up -d
+
+
+# ── REQUIRED ─────────────────────────────────────────────────────────────────
+
+# Host path to your photo library. PhotoPrism reads this in place and
+# writes EXIF backwrites next to originals (when PP_ORIGINALS_MODE=rw).
+PHOTO_DIRS=/mnt/library/homecloud/admin/files/
+
+# Bootstrap admin password. The first PhotoPrism boot creates an `admin`
+# account with this password. Rotate after first login from the UI.
+PP_ADMIN_PASSWORD=please-change-me
+
+# MariaDB passwords. Generate with `openssl rand -hex 24`.
+PP_DB_PASSWORD=please-change-me
+PP_DB_ROOT_PASSWORD=please-change-me
+
+
+# ── OPTIONAL ─────────────────────────────────────────────────────────────────
+
+# Loopback host port for PhotoPrism's API (and UI, if you tunnel to it).
+# Vite proxies /api/v1/* here and the host-mode sidecar reaches it on
+# localhost. Not published on the public interface.
+PP_PORT=2342
+
+# Site URL — used for share links, OIDC redirect URI, and reverse-proxy aware
+# URL generation. Set to the public hostname once the proxy is in front.
+PP_SITE_URL=http://localhost:2342/
+
+# Auth mode — "password" for username/password (default), "public" for an
+# unauthenticated kiosk mode (don't use this on a multi-user library).
+PP_AUTH_MODE=password
+
+# Library mount mode. "rw" allows rename / folder mutations / EXIF backwrite;
+# "ro" is safe-for-archives but disables those sidecar endpoints. Set in
+# lockstep with PP_READONLY below.
+PP_ORIGINALS_MODE=rw
+PP_READONLY=false
+
+# UID/GID inside the PhotoPrism container. Set these to the host UID/GID that
+# owns ${PHOTO_DIRS}. `id -u` and `id -g`.
+PP_UID=1000
+PP_GID=1000
+
+
+# ── OIDC SSO (Authentik or equivalent) ───────────────────────────────────────
+# Leave blank to keep OIDC dormant. Fill in to enable the "Sign in with OIDC"
+# button on the login page; OIDC_REGISTER=true auto-creates accounts at role
+# `user` (override to `admin` to grant full access on first SSO login).
+#
+# The compose file reads these and maps them to PhotoPrism's actual env-var
+# names (PHOTOPRISM_OIDC_URI / _CLIENT / _SECRET / _PROVIDER) — see the
+# comment in docker-compose.yml. The PhotoPrism callback URI is auto-derived
+# from PP_SITE_URL; do not set it manually.
+
+# OIDC_PROVIDER_NAME=Authentik
+# OIDC_ISSUER_URL=https://auth.example.com/application/o/photoprism/
+# OIDC_CLIENT_ID=...
+# OIDC_CLIENT_SECRET=...
+# OIDC_SCOPES=openid profile email
+# OIDC_REGISTER=true
+# OIDC_ROLE=user
+
+
+# ── USER LIBRARY ISOLATION ───────────────────────────────────────────────────
+# Maps PhotoPrism usernames to originals-relative subdirectories so each
+# user only sees their own photos. Format: comma-separated user:path pairs.
+# The sidecar reconciler applies this to auth_users.base_path on boot and
+# every 60s. Leave empty for single-user deployments.
+#
+# USER_BASEPATHS="alice:alice, bob:bob"
+
+# Sidecar DB password — provisioned by mariadb/init/01-sidecar.sql on first
+# boot. Rotate before any non-local deployment.
+# SIDECAR_DB_PASSWORD=replace-at-m4-bringup
+
+
+# ── LOGGING ──────────────────────────────────────────────────────────────────
+
+PP_LOG_LEVEL=info

.gitignore

@@ -34,6 +34,7 @@ dist-ssr/
 .DS_Store
 
 # Environment
+.env
 .env.local
 .env.*.local
 
@@ -60,9 +61,18 @@ build/
 # Docker
 docker-compose.override.yml
 
+# PhotoPrism state (sidecars, cache, thumbs, db backups) — regenerable.
+/pp/storage/
+/pp/import/
+
+# Sidecar runtime state (per-user marks etc.) — generated, not seed data.
+/sidecar/data/
+
+# Sidecar Go build output.
+/sidecar/mule-sidecar
+
 # Photos (for development)
 /photos/
 
 # Thumbnails
 /thumbs/
-/trash/

.hermes/plans/2026-06-06_120000-photos_users-label-isolation.md

@@ -0,0 +1,247 @@
+# Plan: Populate `photos_users` to fix label isolation in PhotoPrism
+
+**Date:** 2026-06-06  
+**Author:** Hermes Agent  
+**Status:** Draft
+
+---
+
+## 1. Goal
+
+Fix the label isolation leak where a user with `base_path` set (e.g. `muli`) sees photos from other users' directories (e.g. `dtoro`) in PhotoPrism's labels view.
+
+## 2. Current Context
+
+### The problem
+- PhotoPrism's `base_path` feature correctly scopes the main search (`/api/v1/photos`).
+- Label views (`/api/v1/labels`) do **not** respect `base_path` — labels show photo counts and thumbnails from the entire library.
+- User reports: "all photos on the main labels page are a mix of both" muli and dtoro.
+
+### What we know
+- **53 files changed** in the sidecar (Go + GORM, gorm.io/gorm v1.31.1).
+- Sidecar has a working PhotoPrism DB connection via `PpDSN` (user: `photoprism`, schema: `photoprism.*`).
+- The `photos_users` table exists in PhotoPrism's MariaDB schema but is **empty** (0 rows).
+- Schema of `photos_users`:
+
+```
+photos_users:
+  uid        varbinary(42)   NOT NULL  PRI  (composite PK or single?)
+  user_uid   varbinary(42)   NOT NULL  PRI
+  team_uid   varbinary(42)   YES       MUL
+  perm       int(10) unsigned YES
+```
+
+- Known user UIDs: `dtoro=utfetfdk0so2z9zl`, `muli=utg7jjbd8iwaghn6`
+- Known base paths: `dtoro→dtoro`, `muli→muli`
+- The `photo_path` column in `photos` stores paths like `muli/files/Photo Archive...` or `dtoro/Memories/...`
+- Currently: ~88K photos, ~52K files indexed.
+
+### The sidecar's current reconciler (`users.go`)
+- Runs every 60s.
+- Only calls `UPDATE auth_users SET base_path = ? WHERE user_name = ?`.
+- Does **not** touch `photos_users`.
+
+### Unknowns
+1. **Does PhotoPrism use `photos_users` for general label filtering?** The table appears designed for explicit sharing (e.g. share a specific photo with another user), not for base_path ACL. PhotoPrism may ignore `photos_users` in label queries.
+2. **Performance impact**: 88K photos × 2 users = up to 176K rows. Could slow label queries.
+3. **Side effects**: If `photos_users` controls sharing, adding auto-entries might break explicit share workflow.
+4. **`perm` values**: Unclear what `perm` value grants "view" access. Likely a bitmap (bit 0 = view).
+
+## 3. Proposed Approach
+
+### Phase 1: Investigate (prove the approach works before building)
+
+**Step 1.1: Insert test rows into `photos_users` manually**
+
+On the production DB, insert a few `photos_users` entries for muli mapping to some of muli's own photos, plus one entry mapping to a dtoro photo. Use a guessed `perm` value (e.g. `1` = view).
+
+Then check:
+- Does muli see fewer photos now? (If `photos_users` works as an exclusive ACL, yes.)
+- Does the dtoro photo with a `photos_users` entry for muli show up for muli?
+- Does the label view change?
+
+**Step 1.2: Test with `perm` variations**
+
+If `perm=1` does nothing, try `perm=2`, `perm=7`, or `perm=15` (common Unix-ish bitmap patterns).
+
+**Step 1.3: Examine PhotoPrism source**
+
+Check PhotoPrism's search/label code to confirm whether `photos_users` is joined in label queries. This tells us definitively whether the approach is viable.
+
+### Phase 2: Build (if Phase 1 confirms the approach works)
+
+**Step 2.1: Add `photos_users` GORM model**
+
+New struct in `db.go` or a new file `perms.go`:
+
+```go
+type PhotoUser struct {
+    PhotoUID string `gorm:"primaryKey;size:42;column:uid"`
+    UserUID  string `gorm:"primaryKey;size:42;column:user_uid"`
+    TeamUID  string `gorm:"size:42;column:team_uid"`
+    Perm     int    `gorm:"column:perm"`
+}
+
+func (PhotoUser) TableName() string { return "photos_users" }
+```
+
+Note: GORM `AutoMigrate` is called on `mule_sidecar` schema, not `photoprism.*`. The `photos_users` table already exists in the `photoprism` schema — we only query/insert, never migrate.
+
+**Step 2.2: Add `reconcilePhotoUsers` function**
+
+New function in a new file `perms.go` alongside `users.go`. Signature:
+
+```go
+func reconcilePhotoUsers(ppDSN, originalsRoot string, mapping map[string]string) error
+```
+
+Logic:
+1. For each `username:path` pair in `mapping`, look up the user's `user_uid` in `auth_users`.
+2. Query `photos` for all `photo_uid` where `photo_path LIKE 'path/%'`.
+3. Batch-insert entries into `photos_users` with a default `perm` value (to be determined in Phase 1).
+4. Use `INSERT IGNORE` or `ON DUPLICATE KEY UPDATE` for idempotency.
+5. Handle deletions: if a photo's path is changed (via rename), the old `photos_users` entry should be cleaned up.
+
+**Step 2.3: Wire into reconciler loop**
+
+Extend the existing `startUserBasepathReconciler` to call `reconcilePhotoUsers` after `reconcileUserBasepaths`.
+
+```go
+func apply() {
+    reconcileUserBasepaths(...)
+    reconcilePhotoUsers(...)
+}
+```
+
+**Step 2.4: Handle re-index edge cases**
+
+- When new photos are indexed, they won't have `photos_users` entries until the next 60s tick.
+- Could add a webhook or a one-shot trigger after PhotoPrism's index completes.
+- Alternative: accept the 60s lag as a design trade-off (current base_path reconciler already has this lag).
+
+### Phase 3: Validate (if Phase 1 confirms)
+
+1. Build the binary: `cd sidecar && CGO_ENABLED=0 go build -o mule-sidecar .`
+2. Rebuild the Docker image and restart the sidecar.
+3. Check `photos_users` has expected rows.
+4. Log in as `muli` via Authentik SSO, browse labels — verify dtoro photos are gone.
+5. Log in as `dtoro` — verify still sees own photos.
+6. Verify no regression: search, album, folder views still work for both users.
+
+## 4. Files Likely to Change
+
+| File | Change |
+|------|--------|
+| `sidecar/perms.go` | **New file** — `PhotoUser` model, `reconcilePhotoUsers` function |
+| `sidecar/db.go` | Add `photos_users`-related constants/helpers (optional) |
+| `sidecar/users.go` | Extend `reconcileUserBasepaths` or add a phase to the existing reconciler |
+| `sidecar/main.go` | Wire the new reconciler phase (minor — call from existing ticker) |
+| `sidecar/Dockerfile` | Unchanged (Go build picks up new `.go` files automatically) |
+
+## 5. Tests & Validation
+
+1. **Build check**: `go build ./...` from `sidecar/`
+2. **Manual DB test** (Phase 1): Insert test `photos_users` rows via `docker exec pp-mariadb mysql ...`
+3. **Integration test**: After deploy, check `photos_users` row count matches expected photo count per user.
+4. **Label isolation check**: Browse labels as each user — confirm no cross-user leaks.
+
+## 6. Source Code Analysis (Completed)
+
+### How base_path scoping works in PhotoPrism
+
+Found the critical function `ScopePhotosForSession` in `internal/entity/search/photos_scope.go`:
+
+```go
+func ScopePhotosForSession(stmt *gorm.DB, sess *entity.Session) *gorm.DB {
+    // Admin/library role → no scoping needed
+    if sess == nil || acl.Rules.AllowAny(acl.ResourcePhotos, sess.GetUserRole(), acl.Permissions{acl.AccessAll, acl.AccessLibrary}) {
+        return stmt
+    }
+    user := sess.GetUser()
+    if basePath := user.GetBasePath(); basePath == "" {
+        return stmt.Where(sharedAlbums + "photos.created_by = ? OR ...", ...)
+    } else {
+        return stmt.Where(sharedAlbums + "... OR photos.photo_path = ? OR photos.photo_path LIKE ?",
+            ..., basePath, basePath + "/%")
+    }
+}
+```
+
+Key: base_path filtering is done by adding `WHERE photos.photo_path LIKE 'muli/%'` to the SQL query. It is **NOT** done via `photos_users`.
+
+### How endpoints use base_path
+
+| Endpoint | Function | Applies base_path? |
+|----------|----------|-------------------|
+| `GET /api/v1/photos` | `SearchPhotos` → `UserPhotos` → `searchPhotos` → **`ScopePhotosForSession`** | ✅ Yes |
+| `GET /api/v1/labels` | `SearchLabels` → `search.Labels(frm)` — no session passed | ❌ **No** |
+| Review tab | Uses `GET /api/v1/photos?quality=3` → goes through `ScopePhotosForSession` | ✅ Should scope |
+| Archive tab | Uses `GET /api/v1/photos?archived=true` → goes through `ScopePhotosForSession` | ✅ Should scope |
+| Albums | TBD — depends on whether they use `ScopePhotosForSession` | ⚠️ Unknown |
+
+### The `photos_users` table
+
+Found in `internal/entity/photo_user.go`:
+
+```go
+type PhotoUser struct {
+    UID     string  // photo_uid
+    UserUID string  // user_uid
+    TeamUID string  // team_uid
+    Perm    uint    // permission bitmap
+}
+```
+
+This table is **not referenced** in `ScopePhotosForSession`, `searchPhotos`, or any label/album search function. It is only used for **explicit sharing** (via `FirstOrCreatePhotoUser` called when sharing a specific photo with another user).
+
+**Conclusion: Populating `photos_users` will NOT fix the label, review, or archive tab isolation.** PhotoPrism does not consult this table for any of these queries.
+
+### Why review/archive might show cross-user photos
+
+Since review and archive use `GET /api/v1/photos` which goes through `ScopePhotosForSession`, they **should** be scoped. The issue might be:
+1. **Pre-computed counts** in the sidebar tabs show total numbers across all users
+2. **Label thumbnails** and category summaries are computed from the `labels` table which is global
+3. The actual photo list in review/archive should be correctly scoped — the user may be seeing dtoro photos only in the summary/counts
+
+### DB experiment results
+
+Confirmed `photos_users` is empty (0 rows). Inserted 100 muli-photo entries + 1 dtoro-photo entry for muli with `perm=1`. Label API response unchanged — `photo_count` values remained the same (Dog: 733, Cat: 57), confirming labels ignore `photos_users`.
+
+## 7. Updated Recommendation
+
+**Abandon the `photos_users` approach.** It won't fix the problem because PhotoPrism never consults this table for labels, review, or archive queries.
+
+### Real fix options
+
+1. **Sidecar label filter** (recommended) — The sidecar already validates sessions via `resolveSession()` which returns the user's `BasePath`. Extend the sidecar to expose a **proxied `/api/v1/labels`** endpoint that:
+   - Accepts the caller's `X-Auth-Token` (already validated by `requireSession`)
+   - Forwards the request to PhotoPrism's `/api/v1/labels`
+   - **Filters the response** to remove labels whose `Thumb` belongs to a photo outside the user's `base_path`
+   - Recalculates `PhotoCount` for the user's scope (count photos under `base_path/%` for that label)
+   - Also filter `Count` values in the sidebar summary response
+   
+   **Why this works:** The sidecar already has DB access to PhotoPrism's schema (`PpDSN`) and validates sessions. It can query `photos` to count label intersections per base_path.
+
+2. **Same approach for review/archive sidebar counts** — Intercept the relevant metadata/summary endpoints to scope counts by base_path.
+
+3. **Accept the limitation** — Labels show cross-user thumbnails/counts but the actual photo list is scoped.
+
+### Implementation sketch for option 1
+
+```
+sidecar/
+├── proxy.go              # New file
+│   ├── handleLabels(c)   → GET /api/sidecar/labels → proxies to PP, filters by base_path
+│   ├── handleReviewCount(c) → GET /api/sidecar/review → returns scoped count
+│   └── handleArchiveCount(c) → GET /api/sidecar/archive → returns scoped count
+```
+
+The SvelteKit frontend would call `/api/sidecar/labels` instead of `/api/v1/labels`.
+
+### Clean up: remove test rows from photos_users
+
+Since the approach won't work, remove the test rows inserted during Phase 1:
+
+```sql
+DELETE FROM photoprism.photos_users WHERE user_uid = 'utg7jjbd8iwaghn6';
+```

.hermes/plans/2026-06-06_124500-label-review-archive-isolation.md

@@ -0,0 +1,301 @@
+# Plan: Fix user isolation in PhotoPrism — labels, review, and archive views
+
+**Date:** 2026-06-06  
+**Author:** Hermes Agent  
+**Status:** Draft
+
+---
+
+## 1. Goal
+
+Fix the three views where a user with `base_path` set (e.g. `muli`) sees photos from other users (e.g. `dtoro`):
+
+1. **Labels** — labels list + label drill-down show all library photos
+2. **Review** — photos needing review tab shows cross-user photos
+3. **Archive** — archived photos tab shows cross-user photos
+
+## 2. Current Context & Source Analysis
+
+### 2.1 How base_path scoping works
+
+PhotoPrism's `ScopePhotosForSession` (in `internal/entity/search/photos_scope.go`) is the only function that enforces user isolation. It adds `WHERE photos.photo_path = '<basePath>' OR photos.photo_path LIKE '<basePath>/%'` to the SQL query.
+
+This is called by `searchPhotos()` — used by the **`GET /api/v1/photos`** endpoint (search, timeline, folders).
+
+### 2.2 How endpoints use base_path
+
+| View | Endpoint | Function chain | Applies base_path? |
+|------|----------|----------------|-------------------|
+| Main timeline | `GET /api/v1/photos` | `SearchPhotos` → `searchPhotos` → `ScopePhotosForSession` | ✅ Yes |
+| Folders | `GET /api/v1/photos` with path filter | Same chain | ✅ Yes |
+| **Labels** | `GET /api/v1/labels` | `SearchLabels` → `search.Labels(frm)` — **no session** | ❌ **No** — queries `labels` table directly |
+| Label drill-down | `GET /api/v1/photos?label=X` | Uses `searchPhotos` → `ScopePhotosForSession` | ✅ Should scope (if label= param doesn't bypass) |
+| **Review tab** | `GET /api/v1/photos?q=review:true` | `searchPhotos` → `ScopePhotosForSession` | ✅ Should scope, BUT... |
+| **Archive tab** | `GET /api/v1/photos?q=archived:true` | Same | ✅ Should scope, BUT... |
+
+### 2.3 The review/archive problem: ACL overrides
+
+In `searchPhotosForm()` (internal/api/photos_search.go):
+
+```go
+if acl.Rules.Deny(acl.ResourcePhotos, s.GetUserRole(), acl.ActionManage) {
+    frm.Quality = 3
+}
+```
+
+For role=user, `Deny(ActionManage)` → true → sets `frm.Quality = 3` (minimum quality).
+
+Then in `searchPhotos()` (internal/entity/search/photos.go):
+
+```go
+if acl.Rules.Deny(acl.ResourcePhotos, aclRole, acl.ActionDelete) {
+    frm.Archived = false
+    frm.Review = false
+}
+```
+
+For role=user, `Deny(ActionDelete)` → true → **overrides `review:true` and `archived:true` to false**.
+
+So the review and archive filters are **completely ignored** for the `user` role. The frontend sends `review:true` but the server discards it. The result: the review/archive tabs show ALL photos scoped by base_path (no quality/review/archive filter), which means basically the same as the main timeline.
+
+### 2.4 Label problem: no session scoping at all
+
+`search.Labels()` queries the `labels` table directly with a `WHERE photo_count > 0` clause. There is no session parameter, no `ScopePhotosForSession`, and no base_path or user filtering whatsoever. Labels are **library-wide** in PhotoPrism.
+
+The label drill-down (click into a label) uses `GET /api/v1/photos?label=X` which DOES go through `ScopePhotosForSession`, so the photo list itself should be scoped — but the label thumbnails, counts, and covers are global.
+
+### 2.5 ACL GrantDefaults — missing RoleUser entry
+
+```go
+var GrantDefaults = Roles{
+    RoleAdmin:    GrantFullAccess,   // FullAccess = AccessLibrary + everything
+    RoleGuest:    GrantReactShared,  // Only shared content
+    RoleVisitor:  GrantViewShared,   // Only shared content
+    RolePortal:   GrantFullAccess,
+    RoleClient:   GrantFullAccess,
+    // RoleUser and RoleViewer are NOT listed → fallback to RoleDefault (also missing) → denied
+}
+```
+
+Because `RoleUser` is absent from `GrantDefaults`, the `Allow()` function falls back to `RoleDefault` which is also absent → returns `false` for all permissions. This means:
+- `ScopePhotosForSession` correctly enters the `base_path` branch (good — user is isolated)
+- BUT `ActionDelete` is denied → review/archive filters are forced off (bad — can't browse review/archive)
+
+### 2.6 The `photos_users` table — ruled out
+
+`internal/entity/photo_user.go` defines `PhotoUser` but it is **not referenced** in `ScopePhotosForSession`, `searchPhotos`, or any label/album search function. Populating it won't fix any of these issues.
+
+## 3. Proposed Approach
+
+### Phase 1: Sidecar proxy for labels (direct fix)
+
+Extend the sidecar to expose a **scoped labels endpoint**:
+
+```
+GET /api/sidecar/labels → proxies to GET /api/v1/labels → filters by base_path
+```
+
+**How it works:**
+
+1. Sidecar receives the caller's `X-Auth-Token`
+2. `requireSession` middleware resolves the token → returns user's `BasePath`
+3. Sidecar makes the same `/api/v1/labels` request to PhotoPrism (using the caller's token)
+4. **Filter step**: for each label in the response, query the DB to count photos with that label AND `photo_path LIKE '<base_path>/%'`
+5. Return filtered labels with corrected `PhotoCount` and `Thumb`
+
+**Implementation:**
+
+New file `sidecar/handlers_labels.go`:
+
+```go
+// handleLabels proxies to PP's /api/v1/labels, then post-filters
+// counts and thumbnails by the caller's base_path.
+func handleLabels(pp *ppClient, ppDSN string) gin.HandlerFunc {
+    return func(c *gin.Context) {
+        token := ctxToken(c)
+        user := ctxUser(c) // resolved from session, includes BasePath
+        
+        // 1. Get raw labels from PhotoPrism
+        resp, _ := pp.call(c, "GET", "/api/v1/labels?"+c.Request.URL.RawQuery, token, nil)
+        
+        // 2. Decode labels
+        var labels []PpLabel
+        json.Unmarshal(resp.Body, &labels)
+        
+        // 3. For each label, recalculate count for this user's base_path
+        for i, l := range labels {
+            // Count photos with this label AND where photo_path matches base_path
+            var count int
+            db.Raw(`SELECT COUNT(*) FROM photos_labels pl 
+                     JOIN photos p ON pl.photo_uid = p.photo_uid 
+                     WHERE pl.label_uid = ? AND p.photo_path LIKE ?`,
+                l.UID, user.BasePath+"/%").Scan(&count)
+            labels[i].PhotoCount = count
+            
+            // If count is 0, the thumb from the global label doesn't apply
+            // Could also update thumb to a user-scoped one
+        }
+        
+        c.JSON(http.StatusOK, labels)
+    }
+}
+```
+
+**Frontend change:** Update the label query in `web/src/routes/tags/[category]/[[value]]/+page.svelte` to call `/api/sidecar/labels` instead of `/api/v1/labels`.
+
+### Phase 2: Fix review/archive — skip the ACL override
+
+Two options:
+
+**Option A (Recommended): Sidecar proxy for photos search**
+
+Extend the sidecar with:
+```
+GET /api/sidecar/photos → proxies to GET /api/v1/photos → adds path filter
+```
+
+The sidecar intercepts the photos request and adds the `path:<basePath>` query parameter to PhotoPrism's API call. This forces PhotoPrism to add `WHERE photo_path LIKE '<base_path>/%'`.
+
+For review/archive, the sidecar also adds `review:true` or `archived:true` BEFORE the ACL override happens (since the sidecar doesn't hit the ACL code).
+
+**Option B: Custom frontend query**
+
+The frontend explicitly adds `path:muli` to the query string for review/archive tabs:
+```
+GET /api/v1/photos?q=review:true path:muli&count=50
+```
+
+The `path` filter is a standard PhotoPrism search operator that adds `WHERE photos.photo_path = '<path>'`. But this only matches the exact path, not `path/%` (subdirectories). The `path:` operator does `photo_path = ?` (exact match) per the code at line 668.
+
+**Option A is better** because:
+- Works for all users without frontend changes
+- Can add the proper `LIKE` prefix match
+- Centralized logic in the sidecar
+
+### Phase 3: Sidecar proxy for sidebar counts
+
+The session response (or `GET /api/v1/config`) includes library-wide counts:
+```json
+"count": {
+    "review": 248,
+    "archived": 94,
+    "all": 88203,
+    "photos": 88000
+}
+```
+
+These show the TOTAL across all users. The sidecar can proxy this and recalculate counts per base_path.
+
+## 4. Step-by-step Plan
+
+### Step 1: Sidecar — labels proxy
+
+Files: `sidecar/handlers_labels.go` (new), `sidecar/main.go` (route wiring)
+
+1. New types: `PpLabel` (mirrors PhotoPrism's label response shape)
+2. Handler function `handleLabels()` that:
+   - Validates token via `requireSession`
+   - Gets `BasePath` from session
+   - Calls PhotoPrism's `/api/v1/labels`
+   - For each label, queries photos_labels + photos to count user-scoped photos
+   - Returns filtered labels
+3. Wire route: `auth.GET("/labels", handleLabels(...))` in `main.go`
+4. Frontend: change label fetch URL from `/api/v1/labels` to `/api/sidecar/labels`
+
+### Step 2: Sidecar — photos proxy (review/archive fix)
+
+Files: `sidecar/handlers_photos.go` (new), `sidecar/main.go` (route wiring)
+
+1. Handler function `handlePhotos()` that:
+   - Validates token
+   - Gets `BasePath` from session
+   - Parses the query string to detect `review:true` or `archived:true`
+   - Forwards to PhotoPrism's `/api/v1/photos` with `path:<basePath>` added to query
+   - For review/archive, also ensures `review/archived` filter is NOT stripped
+   - Returns PhotoPrism's response
+
+2. Two implementation variants:
+
+   **Variant A** (simpler): add `path:<basePath>` to the forwarded query. This only matches exact path, not subdirs (PhotoPrism's `path:` operator does exact match). Might miss photos in subdirectories.
+
+   **Variant B** (correct): Forward the query without path, then post-filter the response to remove photos whose `photo_path` doesn't match `basePath/%`. This is more robust.
+
+### Step 3: Validation
+
+1. Build sidecar: `cd sidecar && CGO_ENABLED=0 go build -o mule-sidecar .`
+2. Rebuild Docker image: `docker compose build sidecar`
+3. Restart sidecar: `docker compose up -d sidecar`
+4. Test labels as muli — verify only muli's labels appear
+5. Test review tab as muli — verify only muli's photos needing review appear
+6. Test archive tab as muli — verify only muli's archived photos appear
+7. Test same views as admin — verify dtoro still sees all
+
+## 5. Files Likely to Change
+
+| File | Change |
+|------|--------|
+| `sidecar/handlers_labels.go` | **New** — label proxy handler |
+| `sidecar/handlers_photos.go` | **New** — photos proxy handler (or merged into one proxy.go) |
+| `sidecar/handlers_folder.go` | Reference for existing handler patterns |
+| `sidecar/main.go` | Wire new routes under `auth` group |
+| `sidecar/pp.go` | May need new helper methods for label/photo API calls |
+| `sidecar/users.go` | No change |
+| `sidecar/db.go` | May add types for PpLabel, PpPhoto |
+| `web/src/routes/tags/[category]/[[value]]/+page.svelte` | Change label fetch URL |
+| `web/src/lib/stores/filters.svelte.ts` | Possibly change how review/archive queries are built |
+
+## 6. Tests & Validation
+
+**Build**: `cd sidecar && go build ./... && go vet ./...`
+
+**Manual validation on LXC 120:**
+
+```bash
+# Test labels endpoint
+curl -s "http://localhost:8000/api/sidecar/labels?count=5" \
+  -H "X-Auth-Token: <muli-token>" | python3 -c "import sys,json;d=json.load(sys.stdin);[print(l.get('Name','?'),l.get('PhotoCount')) for l in d[:5]]"
+
+# Test photos endpoint with review
+curl -s "http://localhost:8000/api/sidecar/photos?q=review:true&count=5" \
+  -H "X-Auth-Token: <muli-token>" | python3 -c "import sys,json;d=json.load(sys.stdin);print(f'{len(d)} photos')"
+
+# Verify vs. admin token — counts should differ
+```
+
+**Cross-user check:** Log in as `muli` and `dtoro` in separate browser sessions. Verify:
+- Labels show different counts per user
+- Review photos are scoped per user
+- Archive photos are scoped per user
+
+## 7. Risks, Tradeoffs & Open Questions
+
+### Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Sidecar proxying adds latency | Slower page loads | Labels are small payloads; single DB query per label is fast |
+| Frontend needs URL changes | Breaks if not updated | Do frontend change alongside sidecar deploy |
+| Photo count queries on every label request | DB load | Cache results for 30s in the sidecar |
+| PhotoPrism's label `PhotoCount` is stale | Mismatch with actual count | Acceptable — PhotoPrism's count is already cached |
+| Review/archive fix depends on how PhotoPrism handles `path:` operator | Photos in subdirs missed | Use Variant B (post-filter by path prefix) |
+
+### Open Questions
+
+- **Q1**: For review/archive — is the user seeing dtoro's photos in the *grid* or only the *sidebar counts*? Need to verify actual API response vs what the frontend renders.
+- **Q2**: What's the performance impact of running `SELECT COUNT(*) FROM photos_labels ... JOIN photos ...` for every label in the response? (Labels list is typically short, < 100)
+- **Q3**: Does the frontend cache the label response aggressively? Need to invalidate cache on user switch.
+- **Q4**: For the `path:` operator — does it do exact match or LIKE? From source: `WHERE photos.photo_path = ?` — exact match only.
+
+### Tradeoffs
+
+- **Sidecar proxy vs. frontend-only**: Proxy centralizes logic but adds network hop. Frontend-only is faster but more complex (every route needs path filtering).
+- **Label count accuracy**: Recalculated per-user counts will differ from the library-wide counts. This is intentional — labels are scoped now.
+- **Sidecar vs. patching PhotoPrism**: Sidecar approach is non-invasive (no fork/build of PP). PhotoPrism patch would be cleaner but requires maintaining a fork.
+
+## 8. Recommendation
+
+1. **Build the labels proxy** (Phase 1) — it directly solves the label isolation problem and can be done with existing sidecar infrastructure
+2. **Investigate review/archive leak** first — run the actual API query as muli to confirm whether the photos search is actually scoped. The code analysis says it should be, but the user reports otherwise. If confirmed as a real leak, implement the sidecar photos proxy (Phase 2)
+3. **Sidebar counts** (Phase 3) — lower priority, can be done after labels and review/archive are fixed
+
+Before building, confirm with the user whether they see cross-user photos in the actual grid or only in the sidebar counts for review/archive.

.hermes/plans/2026-06-06_210000-remaining-fixes.md

@@ -0,0 +1,227 @@
+# Plan: Fix remaining user isolation issues — 404 errors and folder tree
+
+**Date:** 2026-06-06  
+**Author:** Hermes Agent  
+**Status:** Draft
+
+---
+
+## 1. Goal
+
+Fix the remaining issues after deploying the sidecar scoping proxy:
+
+1. **404 on photo grid** — "Request failed with status code 404" in private window
+2. **Folder tree shows other users** — on first load, the library tree lists other users' folders; a refresh fixes it
+
+## 2. Current Context
+
+### What's deployed
+
+| Component | Status |
+|-----------|--------|
+| Sidecar labels proxy (`/api/sidecar/labels`) | ✅ Working |
+| Sidecar counts proxy (`/api/sidecar/counts`) | ✅ Working |
+| Sidecar timeline proxy (`/api/sidecar/timeline`) | ✅ Working through Caddy |
+| Caddy fallback for `/api/v1/api/sidecar/*` | ✅ Working |
+| Frontend rebuild with `sidecar` axios instance | ✅ Built and deployed |
+
+### Verified working via Caddy
+
+```bash
+# Through public URL with valid admin token
+curl https://photos.hubris.network/api/sidecar/timeline?count=1 → HTTP 200
+curl https://photos.hubris.network/api/v1/photos?count=1     → HTTP 200
+```
+
+Both endpoints return 200 when tested directly through Caddy with a valid token.
+
+### Reported issues
+
+1. **404 on photo grid** — even in private window (no cache interference)
+2. **Folder tree shows other users' folders** on first load, fixed by refresh
+
+## 3. Root Cause Analysis
+
+### Issue 1: 404 on photo grid
+
+The `sidecar` axios instance (`baseURL: ''`) is missing the **response interceptor** that:
+- Handles 401 → clears session → redirects to login
+- Re-throws with meaningful error message
+
+The `http` instance (for `/api/v1` endpoints) has this interceptor. Without it on `sidecar`:
+- If the sidecar returns a non-2xx (401, 502 from upstream PP failure, etc.), axios throws a raw error
+- The TanStack Query error boundary catches it and shows "Request failed with status code <status>"
+- Very likely the sidecar is returning 401 on some calls (token expired / session not yet established) and the error message might show 404 because Caddy's catch-all returns 404 when a matcher doesn't find a route
+
+**Hypothesis:** During OIDC login flow, the frontend may make some sidecar calls BEFORE the session is fully established (token loaded into `session.accessToken`). The `sidecar` interceptor checks `session.accessToken` but it might be null. Then the request to `/api/sidecar/timeline` has no auth header → sidecar returns 401 → no response interceptor → raw error.
+
+**Fix:** Add the same 401 → login redirect interceptor to the `sidecar` instance.
+
+### Issue 2: Folder tree shows other users
+
+`listFolders()` calls `http.get('/folders/originals')` which hits PhotoPrism directly. PhotoPrism returns **all folders across the library** regardless of user. The frontend then filters by `userBasePath()` on the result:
+
+```typescript
+const bp = userBasePath();
+if (bp === '') return folders;  // On first load, bp might be empty!
+return folders.filter((f) => f.Path === bp || f.Path.startsWith(bp + '/'))
+```
+
+On first load, `userBasePath()` returns `""` because:
+1. The session data is loaded asynchronously
+2. `session.user.BasePath` might not yet be populated when `listFolders` fires
+3. The TanStack Query cache from a previous session might still have old data
+
+After a refresh, the session is fully loaded, and `userBasePath()` returns the correct value.
+
+A secondary issue: the `http` interceptor's 401 handler clears the session on 401. If the session expires during the app's lifetime, all subsequent requests fail with 401.
+
+## 4. Proposed Approach
+
+### Phase 1: Fix 404 — add response interceptor to sidecar
+
+**File:** `web/src/lib/services/photoprism.ts`
+
+Add the same 401 → login redirect interceptor to `sidecar` as already exists on `http`:
+
+```typescript
+sidecar.interceptors.response.use(
+    (r) => r,
+    (err: AxiosError) => {
+        if (err.response?.status === 401 && browser) {
+            clearSession();
+            const url = err.config?.url ?? '';
+            if (!url.endsWith('/session')) {
+                void goto('/login', { replaceState: true });
+            }
+        }
+        return Promise.reject(err);
+    }
+);
+```
+
+### Phase 2: Fix folder tree — sidecar folder proxy
+
+**File:** `sidecar/handlers_folders.go` (new)
+
+Add a sidecar endpoint that proxies `/folders/originals` and post-filters by BasePath:
+
+```
+GET /api/sidecar/folders → proxies to GET /api/v1/folders/originals
+                         → removes folders not under user's base_path
+                         → returns filtered list
+```
+
+This avoids the timing issue entirely by filtering on the server side.
+
+**Alternative (simpler):** Fix the frontend timing issue by ensuring `listFolders` doesn't fire until the session is ready.
+
+### Phase 3: Change folder tree in frontend
+
+**File:** `web/src/lib/services/photoprism.ts`
+
+Change `listFolders()` to use `sidecar` instance and call `/api/sidecar/folders`:
+
+```typescript
+export async function listFolders(): Promise<PpFolder[]> {
+    const { data } = await sidecar.get<{ folders?: PpFolder[] }>(
+        '/api/sidecar/folders',
+        { params: { recursive: true, uncached: true, files: false } }
+    );
+    const bp = userBasePath();
+    const folders = data.folders ?? [];
+    if (bp === '') return folders;
+    return folders
+        .filter((f) => f.Path === bp || f.Path.startsWith(bp + '/'))
+        .map((f) => ({ ...f, Path: toUserPath(f.Path) }));
+}
+```
+
+## 5. Step-by-step Plan
+
+### Step 1: Add sidecar response interceptor
+
+1. Edit `web/src/lib/services/photoprism.ts`
+2. Add the 401-handling response interceptor to the `sidecar` instance
+3. The interceptor mirrors the existing `http` response interceptor exactly
+
+### Step 2: Rebuild frontend
+
+```bash
+cd /opt/mule-image/web && npm run build
+```
+
+### Step 3: (Optional) Add sidecar folder proxy
+
+1. New file `sidecar/handlers_folders_proxy.go`
+2. Handler similar to `handlePhotos` — proxies to `/api/v1/folders/originals`, post-filters by `Path` prefix
+3. Wire route in `main.go`: `auth.GET("/folders", handleFoldersProxy(pp))`
+4. Build Docker image, restart sidecar
+
+### Step 4: Update listFolders to use sidecar
+
+1. Change `listFolders()` to use `sidecar` instance
+2. Call `/api/sidecar/folders` instead of `/folders/originals`
+
+### Step 5: Rebuild + validate
+
+```bash
+# Rebuild frontend
+cd /opt/mule-image/web && npm run build
+
+# Test through Caddy
+curl -s "https://photos.hubris.network/api/sidecar/timeline?count=1" \
+  -H "X-Auth-Token: <token>" | head -c 200
+
+# Verify folders
+curl -s "https://photos.hubris.network/api/sidecar/folders" \
+  -H "X-Auth-Token: <token>" | python3 -c "import sys,json;d=json.load(sys.stdin);print(json.dumps(d[:3],indent=2))"
+```
+
+### Step 6: Commit
+
+```bash
+git add -A && git commit -m "fix: add sidecar response interceptor + folder proxy" && git push
+```
+
+## 6. Files Likely to Change
+
+| File | Change |
+|------|--------|
+| `web/src/lib/services/photoprism.ts` | Add response interceptor to sidecar instance; change listFolders URL |
+| `sidecar/handlers_folders_proxy.go` | **New** — folder proxy handler |
+| `sidecar/main.go` | Wire folder proxy route |
+
+## 7. Tests & Validation
+
+**Manual:**
+1. Open private window → navigate to photos.hubris.network
+2. Log in as muli via Authentik OIDC
+3. Verify photo grid loads without 404
+4. Verify folder tree shows only muli's folders
+5. Switch to dtoro account → verify folders/timeline scoped to dtoro
+
+**API tests:**
+```bash
+# Sidecar timeline (no token → 401 redirect)
+curl -s "https://photos.hubris.network/api/sidecar/timeline?count=1"
+
+# Sidecar folders
+curl -s "https://photos.hubris.network/api/sidecar/folders"
+```
+
+## 8. Risks & Open Questions
+
+### Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Sidecar returns 401 during OIDC login flow before session is ready | 404 showing instead of graceful redirect | Add response interceptor in Phase 1 |
+| Folder proxy adds latency | Slower folder tree loading | Minimal — single proxy call, same as PP direct |
+| `userBasePath()` timing issue in listFolders persists even with sidecar | Folder tree still shows wrong folders on first load | Sidecar filter is server-side → no timing dependency |
+
+### Open Questions
+
+- **Q1**: Are there other API calls that bypass the `sidecar` instance and might also be unscoped? (e.g., `listSubjects`, `listGeo`, etc.)
+- **Q2**: Does the sidecar need a folder proxy, or is the timing fix sufficient? The timing fix (delaying `listFolders` until session is ready) is simpler but fragile.
+- **Q3**: Could the 404 be from Caddy's catch-all returning 404 when the sidecar isn't reachable? The Caddy fallback timeout for the sidecar might need tuning.

README.md

@@ -1,153 +1,140 @@
-# Mulita - Self-Hosted Photo Management Application
+# mule-image
 
-A self-hosted, Docker-deployed photo management application inspired by Lightroom's workflow. Mulita provides a fast, keyboard-driven interface to browse, organize, tag, and manage your photo library.
-
-## Features
-
-- **Photo Organization**: Browse photos in a timeline view with virtual scrolling for performance
-- **Thumbnail Generation**: Automatic thumbnail generation for all photo formats including RAW
-- **Metadata Extraction**: Full EXIF/XMP metadata extraction and search
-- **Keyboard Shortcuts**: Lightroom-style keyboard navigation and actions
-- **File Support**: JPEG, PNG, RAW formats (CR2, CR3, NEF, ARW, etc.), HEIC/HEIF, and videos
-- **Heaps**: Temporary collections for organizing photos
-- **Tags & Ratings**: Organize with tags, star ratings, and color labels
-- **Dark Mode**: Photography-optimized dark interface
-
-## Tech Stack
-
-### Backend
-- Python 3.12 with FastAPI
-- SQLite with SQLAlchemy (async)
-- Celery + Redis for background tasks
-- pyvips for fast thumbnail generation
-- ExifTool for metadata extraction
-
-### Frontend
-- React 18 with TypeScript
-- Vite for fast development
-- TanStack Query for data fetching
-- TanStack Virtual for virtualized scrolling
-- Tailwind CSS for styling
-- Zustand for state management
-
-## Quick Start
-
-### Prerequisites
-- Docker and Docker Compose
-- Photo directories to mount
-
-### Setup
-
-1. Clone the repository:
-```bash
-git clone <repository-url>
-cd muleimage
-```
-
-2. Configure your photo directories in `.env`:
-```bash
-# Edit .env file
-PHOTO_DIRS=/path/to/your/photos
-```
-
-3. Start the application:
-```bash
-docker-compose up -d
-```
-
-4. Access the application at `http://localhost:3000`
-
-### Photo directory mounts and permissions
-
-Mulita is a Lightroom-style manager — file operations (rename, move,
-discard, empty discard pile) need to mutate the filesystem under your
-photo mounts. The default `docker-compose.yml` mounts:
-
-- `${PHOTO_DIRS}` → `/photos` (read-write)
-- `~/Pictures` → `/host/Pictures` (**read-write** by default so file
-  operations work on your system Pictures folder out of the box)
-
-If you want a strict read-only library — for example pointing at a
-network share or your authoritative archive — change `:rw` to `:ro`
-on the mount in `docker-compose.yml`. Mulita will keep working for
-browsing, rating, color labels, picks, heaps, and the discard flag,
-but the following endpoints will return an error from the OS
-(`EROFS` / `Read-only file system`):
-
-- `PATCH /photos/{id}` with a new `filename` (rename)
-- `DELETE /discard/empty` (file unlinks)
-- Future move / copy endpoints
-
-**Heads up**: with `:rw`, Mulita has full write access to whatever
-host directory you mount under `~/Pictures`. Treat the same way you
-would Lightroom's catalog folder.
+Self-hosted photo management built on top of [PhotoPrism][pp]. A SvelteKit
+frontend ([`web/`](web/)) plus a small Go service ([`sidecar/`](sidecar/))
+fill in the keyboard-driven UI and the file/folder/mark endpoints
+PhotoPrism's REST API does not expose. PhotoPrism itself handles
+indexing, originals, thumbnails, and the database; we never re-implement
+those.
 
 ## Architecture
 
-The application consists of 5 Docker services:
-
-- **frontend**: React SPA served by Nginx
-- **backend**: FastAPI REST API
-- **worker**: Celery workers for background tasks
-- **redis**: Message broker for Celery
-- **db**: SQLite database (file-based)
-
-## Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| `←` `→` `↑` `↓` | Navigate photos |
-| `Space` | Quick preview |
-| `Enter` | Open loupe view |
-| `P` | Pick photo |
-| `X` | Reject photo |
-| `1-5` | Set star rating |
-| `Tab` | Toggle left sidebar |
-| `I` | Toggle metadata panel |
-| `G` | Grid view |
-| `E` | Loupe view |
-| `Delete` | Move to trash |
-
-## Development
-
-### Backend Development
-```bash
-cd backend
-pip install -r requirements.txt
-uvicorn app.main:app --reload
+```text
+┌──────────────────┐    /api/v1/*      ┌──────────────┐
+│  SvelteKit web/  │ ───────────────▶  │  photoprism  │ ──▶ mariadb
+│  (Vite : 5173)   │    /api/sidecar/* │   :2342      │
+│                  │ ─────────┐        └──────────────┘
+└──────────────────┘          ▼
+                      ┌──────────────┐
+                      │  sidecar     │ ──▶ mariadb (mule_sidecar.*)
+                      │  :8000       │ ──▶ originals FS (rename / folders / dups)
+                      └──────────────┘
 ```
 
-### Frontend Development
+Three compose services — `mariadb`, `photoprism`, `sidecar` — plus the
+SvelteKit `web/` app served separately. PhotoPrism's port `2342` is
+**bound to `127.0.0.1` only**; it isn't a user-facing surface. The
+SvelteKit app is.
+
+What the sidecar adds on top of PhotoPrism (full list in
+[`sidecar/README.md`](sidecar/README.md)):
+
+- Per-photo marks (rating + color) persisted to `mule_sidecar.marks`
+- File rename + folder create/rename/delete with PhotoPrism reindex
+- Heap (album) → folder conversion
+- Perceptual-hash duplicate scan + archive
+
+## Quick start
+
 ```bash
-cd frontend
+cp .env.example .env
+# edit .env: set PHOTO_DIRS to the host path holding your library
+# rotate PP_ADMIN_PASSWORD, PP_DB_PASSWORD, PP_DB_ROOT_PASSWORD
+# before any non-local deployment.
+
+podman-compose --env-file .env \
+  -f docker-compose.yml \
+  -f docker-compose.podman.yml \
+  up -d
+```
+
+Then serve the frontend. For local use the simplest path is the Vite
+dev server:
+
+```bash
+cd web
 npm install
 npm run dev
+# open http://localhost:5173
 ```
 
+For a static deployment, `npm run build` produces a bundle under
+`web/build/` that any static file host (nginx, Caddy, GitHub Pages-style)
+can serve. Reverse-proxy `/api/v1/*` to `http://127.0.0.1:2342` and
+`/api/sidecar/*` to `http://127.0.0.1:8000`.
+
+PhotoPrism's own UI is still reachable from the host at
+`http://127.0.0.1:2342` if you need admin features (user management,
+settings) — set up an SSH tunnel from your laptop if the server is
+remote.
+
 ## Configuration
 
-Edit `mulita.yml` to configure:
-- Source photo directories
-- Thumbnail sizes and quality
-- Scanner settings
-- Performance tuning
+All knobs live in [`.env.example`](.env.example). The required ones:
 
-## Performance
+| Variable             | Notes                                                                                         |
+|----------------------|-----------------------------------------------------------------------------------------------|
+| `PHOTO_DIRS`         | Host path mounted at `/photoprism/originals`. The library.                                    |
+| `PP_ADMIN_PASSWORD`  | First-boot admin password. Rotate.                                                            |
+| `PP_DB_PASSWORD`     | MariaDB password for the `photoprism` user. Rotate.                                           |
+| `PP_DB_ROOT_PASSWORD`| MariaDB root password. Rotate.                                                                |
+| `PP_UID` / `PP_GID`  | Host UID/GID that owns `PHOTO_DIRS`. PhotoPrism + sidecar drop to this user inside.           |
+| `PP_PORT`            | Loopback host port for PhotoPrism (default `2342`).                                           |
+| `PP_ORIGINALS_MODE`  | `rw` (default) or `ro` — see [Read-only libraries](#read-only-libraries).                     |
+| `SIDECAR_PORT`       | Loopback host port for the sidecar (default `8000`).                                          |
 
-- Handles 100,000+ photos efficiently
-- Virtual scrolling for smooth timeline navigation
-- Thumbnail generation at 10+ photos/second
-- SQLite FTS5 for fast full-text search
+Sidecar-specific env (DB DSN, `USER_BASEPATHS`, etc.) is documented in
+[`sidecar/README.md`](sidecar/README.md).
 
-## Future Features (Phase 2)
+## Read-only libraries
 
-- AI-powered scene classification
-- Face detection and clustering
-- Smart albums
-- Duplicate detection
-- Export presets
-- Multi-user support
+The default originals mount is `:rw` because file operations (rename,
+folder mutations, duplicate archive, heap convert) need to mutate the
+filesystem. To run against a read-only archive, set
+`PP_ORIGINALS_MODE=ro` in `.env`. Browsing, marks, ratings, and color
+labels still work; the following sidecar endpoints return an OS error:
 
-## License
+- `POST /api/sidecar/files/:uid/rename`
+- `POST /api/sidecar/folders` / `:rel/rename` / `DELETE /:rel`
+- `POST /api/sidecar/albums/:uid/convert`
+- `POST /api/sidecar/duplicates/archive`
 
-MIT
+PhotoPrism's `PHOTOPRISM_READONLY` is controlled separately by
+`PP_READONLY` and gates its own backwrite / import paths.
+
+## Dev iteration loop
+
+For fast iteration on the sidecar without rebuilding its image on every
+change, run it as a host process — bring up just `mariadb` and
+`photoprism` from compose, then build and run the Go binary locally.
+Full instructions in [`sidecar/README.md`](sidecar/README.md#dev-iteration-loop-host-build).
+
+## Layout
+
+```text
+.
+├── docker-compose.yml         base stack: mariadb + photoprism + sidecar
+├── docker-compose.podman.yml  rootless-podman overlay (keep-id mapping)
+├── docker-compose.gpu.yml     opt-in VA-API GPU passthrough overlay
+├── .env.example               required env vars (copy to .env)
+├── mariadb/init/              first-boot SQL: creates mule_sidecar DB + user
+├── pp/                        PhotoPrism bind-mounted state (storage, import)
+├── sidecar/                   Go service — see sidecar/README.md
+└── web/                       SvelteKit frontend
+```
+
+## GPU video acceleration (optional)
+
+Hosts with a VA-API-capable GPU (Intel iGPU, AMD APU, etc.) can layer
+[`docker-compose.gpu.yml`](docker-compose.gpu.yml) to hand `/dev/dri/*`
+to PhotoPrism and switch ffmpeg to hardware encode/decode — a large
+perf win for video thumbnails and HEVC→H.264 transcodes:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
+```
+
+Set `PP_FFMPEG_ENCODER=vaapi` in `.env` (default for the overlay). Verify
+with `docker exec pp-app photoprism show config | grep -i ffmpeg`.
+
+[pp]: https://photoprism.app/

backend/Dockerfile

@@ -1,39 +0,0 @@
-FROM python:3.12-slim
-
-# Install system dependencies
-RUN apt-get update && apt-get install -y \
-    # Build dependencies
-    gcc \
-    g++ \
-    make \
-    # Image processing libraries
-    libvips42 \
-    libvips-dev \
-    # ExifTool for metadata extraction
-    libimage-exiftool-perl \
-    # FFmpeg for video processing
-    ffmpeg \
-    # Git for some Python packages
-    git \
-    # PostgreSQL client (for potential future use)
-    postgresql-client \
-    # Clean up
-    && rm -rf /var/lib/apt/lists/*
-
-WORKDIR /app
-
-# Copy requirements first for better caching
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Copy application code
-COPY . .
-
-# Create necessary directories
-RUN mkdir -p /data/thumbs /data/db /data/trash /app/config
-
-# Expose port
-EXPOSE 8000
-
-# Run the application
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

backend/app/config.py

@@ -1,130 +0,0 @@
-"""
-Application configuration using Pydantic Settings
-"""
-from pydantic_settings import BaseSettings
-from pydantic import BaseModel, Field
-from typing import List, Optional
-import os
-import yaml
-from pathlib import Path
-
-class ThumbnailSettings(BaseModel):
-    """Thumbnail generation settings"""
-    small: int = 240
-    medium: int = 640
-    large: int = 1280
-    quality: int = 85
-    format: str = "webp"
-
-class ScannerSettings(BaseModel):
-    """File scanner settings"""
-    watch: bool = True
-    initial_scan_on_start: bool = True
-    batch_size: int = 100
-    concurrent_workers: int = 4
-
-class SourceRoot(BaseModel):
-    """Source root directory configuration"""
-    name: str
-    path: str
-
-class TrashSettings(BaseModel):
-    """Trash settings"""
-    path: str = "/data/trash"
-    auto_empty_days: Optional[int] = 30
-
-class PerformanceSettings(BaseModel):
-    """Performance tuning settings"""
-    max_concurrent_thumbnails: int = 10
-    cache_ttl: int = 3600
-    db_pool_size: int = 20
-    db_pool_recycle: int = 3600
-
-class MulitaConfig(BaseModel):
-    """Main configuration from YAML file"""
-    source_roots: List[SourceRoot] = []
-    thumbnails: ThumbnailSettings = ThumbnailSettings()
-    scanner: ScannerSettings = ScannerSettings()
-    trash: TrashSettings = TrashSettings()
-    performance: PerformanceSettings = PerformanceSettings()
-
-class Settings(BaseSettings):
-    """Application settings"""
-    # Database
-    database_url: str = Field(
-        default="sqlite+aiosqlite:///data/db/mulita.db",
-        env="DATABASE_URL"
-    )
-    
-    # Redis
-    redis_url: str = Field(
-        default="redis://localhost:6379",
-        env="REDIS_URL"
-    )
-    
-    # Celery
-    celery_broker_url: str = Field(
-        default="redis://localhost:6379",
-        env="CELERY_BROKER_URL"
-    )
-    celery_result_backend: str = Field(
-        default="redis://localhost:6379",
-        env="CELERY_RESULT_BACKEND"
-    )
-    
-    # Photo directories
-    photo_dirs: str = Field(
-        default="/photos",
-        env="PHOTO_DIRS"
-    )
-    
-    # API settings
-    api_host: str = Field(default="0.0.0.0", env="API_HOST")
-    api_port: int = Field(default=8000, env="API_PORT")
-    
-    # App configuration from YAML
-    _config: Optional[MulitaConfig] = None
-    
-    @property
-    def config(self) -> MulitaConfig:
-        """Load configuration from YAML file"""
-        if self._config is None:
-            config_path = Path("/app/config/mulita.yml")
-            if not config_path.exists():
-                config_path = Path("mulita.yml")
-            
-            if config_path.exists():
-                with open(config_path, "r") as f:
-                    config_data = yaml.safe_load(f)
-                    self._config = MulitaConfig(**config_data)
-            else:
-                self._config = MulitaConfig()
-        
-        return self._config
-    
-    @property
-    def thumbnails(self) -> ThumbnailSettings:
-        return self.config.thumbnails
-    
-    @property
-    def scanner(self) -> ScannerSettings:
-        return self.config.scanner
-    
-    @property
-    def trash(self) -> TrashSettings:
-        return self.config.trash
-    
-    @property
-    def performance(self) -> PerformanceSettings:
-        return self.config.performance
-    
-    @property
-    def source_roots(self) -> List[SourceRoot]:
-        return self.config.source_roots
-    
-    class Config:
-        env_file = ".env"
-        case_sensitive = False
-
-# Global settings instance
-settings = Settings()

backend/app/database.py

@@ -1,89 +0,0 @@
-"""
-Database configuration and session management
-"""
-from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
-from sqlalchemy.orm import declarative_base
-from sqlalchemy import event, text
-import logging
-import os
-from pathlib import Path
-
-from app.config import settings
-
-logger = logging.getLogger(__name__)
-
-# Create database directory if it doesn't exist
-db_path = Path(settings.database_url.replace("sqlite+aiosqlite:///", ""))
-db_path.parent.mkdir(parents=True, exist_ok=True)
-
-# Create async engine
-# SQLite doesn't support pool configuration
-if "sqlite" in settings.database_url:
-    engine = create_async_engine(
-        settings.database_url,
-        echo=False,  # Set to True for SQL debugging
-        connect_args={
-            "check_same_thread": False,  # SQLite specific
-            "timeout": 30
-        }
-    )
-else:
-    engine = create_async_engine(
-        settings.database_url,
-        echo=False,  # Set to True for SQL debugging
-        pool_size=settings.performance.db_pool_size,
-        pool_recycle=settings.performance.db_pool_recycle
-    )
-
-# Create async session factory
-AsyncSessionLocal = async_sessionmaker(
-    engine,
-    class_=AsyncSession,
-    expire_on_commit=False
-)
-
-# Base class for models
-Base = declarative_base()
-
-async def get_db() -> AsyncSession:
-    """Dependency to get database session"""
-    async with AsyncSessionLocal() as session:
-        try:
-            yield session
-        finally:
-            await session.close()
-
-async def init_db():
-    """Initialize database, create tables if they don't exist"""
-    async with engine.begin() as conn:
-        # Import all models to register them with Base
-        from app.models import Photo, Folder, SourceRoot, Tag, PhotoTag, Heap, HeapPhoto, Embedding
-        
-        # Create all tables
-        await conn.run_sync(Base.metadata.create_all)
-        
-        # Enable WAL mode for SQLite (better concurrency)
-        if "sqlite" in settings.database_url:
-            await conn.execute(text("PRAGMA journal_mode=WAL"))
-            await conn.execute(text("PRAGMA synchronous=NORMAL"))
-            await conn.execute(text("PRAGMA cache_size=10000"))
-            await conn.execute(text("PRAGMA temp_store=MEMORY"))
-        
-        logger.info("Database initialized successfully")
-
-async def create_fts_table():
-    """Create Full-Text Search table for SQLite"""
-    if "sqlite" in settings.database_url:
-        async with engine.begin() as conn:
-            # Create FTS5 virtual table for full-text search
-            await conn.execute(text("""
-                CREATE VIRTUAL TABLE IF NOT EXISTS photos_fts USING fts5(
-                    photo_id UNINDEXED,
-                    filename,
-                    user_title,
-                    user_notes,
-                    exif_text,
-                    tokenize='unicode61'
-                )
-            """))
-            logger.info("FTS5 table created successfully")

backend/app/main.py

@@ -1,90 +0,0 @@
-"""
-Mulita - Photo Management Application
-Main FastAPI application entry point
-"""
-from contextlib import asynccontextmanager
-from fastapi import FastAPI
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.staticfiles import StaticFiles
-import logging
-import os
-
-from app.config import settings
-from app.database import init_db
-from app.routers import photos, folders, heaps, tags, discard, library
-from app.services.scanner import start_initial_scan
-from app.services.cleanup import cleanup_data_integrity
-
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
-)
-logger = logging.getLogger(__name__)
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    """Manage application lifecycle"""
-    logger.info("Starting Mulita application...")
-
-    # Initialize database
-    await init_db()
-
-    # One-shot cleanup of duplicate source_roots / folders left over from
-    # earlier scanner versions that didn't normalize paths. Idempotent.
-    try:
-        await cleanup_data_integrity()
-    except Exception as e:
-        logger.error(f"Startup cleanup failed (continuing): {e}")
-
-    # Start initial scan if configured
-    if settings.scanner.initial_scan_on_start:
-        logger.info("Starting initial library scan...")
-        await start_initial_scan()
-
-    yield
-
-    logger.info("Shutting down Mulita application...")
-
-# Create FastAPI app
-app = FastAPI(
-    title="Mulita Photo Management API",
-    description="Self-hosted photo management application inspired by Lightroom",
-    version="1.0.0",
-    lifespan=lifespan
-)
-
-# Configure CORS
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["http://localhost:3000", "http://localhost:5173"],  # Frontend URLs
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-# Mount static files for serving thumbnails (with X-Accel-Redirect support)
-if os.path.exists("/data/thumbs"):
-    app.mount("/thumbs", StaticFiles(directory="/data/thumbs"), name="thumbs")
-
-# Include routers
-app.include_router(photos.router, prefix="/api/v1/photos", tags=["photos"])
-app.include_router(folders.router, prefix="/api/v1/folders", tags=["folders"])
-app.include_router(heaps.router, prefix="/api/v1/heaps", tags=["heaps"])
-app.include_router(tags.router, prefix="/api/v1/tags", tags=["tags"])
-app.include_router(discard.router, prefix="/api/v1/discard", tags=["discard"])
-app.include_router(library.router, prefix="/api/v1/library", tags=["library"])
-
-@app.get("/")
-async def root():
-    """Root endpoint"""
-    return {
-        "name": "Mulita Photo Management API",
-        "version": "1.0.0",
-        "status": "running"
-    }
-
-@app.get("/health")
-async def health_check():
-    """Health check endpoint for Docker"""
-    return {"status": "healthy"}

backend/app/models/__init__.py

@@ -1,19 +0,0 @@
-"""
-Database models for Mulita
-"""
-from app.models.photos import Photo
-from app.models.folders import Folder, SourceRoot
-from app.models.tags import Tag, PhotoTag
-from app.models.heaps import Heap, HeapPhoto
-from app.models.embeddings import Embedding
-
-__all__ = [
-    'Photo',
-    'Folder',
-    'SourceRoot',
-    'Tag',
-    'PhotoTag',
-    'Heap',
-    'HeapPhoto',
-    'Embedding'
-]

backend/app/models/embeddings.py

@@ -1,17 +0,0 @@
-"""
-Embedding model definition (placeholder for AI features)
-"""
-from sqlalchemy import Column, String, ForeignKey, LargeBinary
-import uuid
-
-from app.database import Base
-
-class Embedding(Base):
-    """
-    Placeholder table for future AI embeddings (CLIP, face recognition, etc.)
-    """
-    __tablename__ = 'embeddings'
-    
-    photo_id = Column(String, ForeignKey('photos.id', ondelete='CASCADE'), primary_key=True)
-    model = Column(String)  # e.g., 'clip-vit-b32', 'face-recognition', etc.
-    vector = Column(LargeBinary)  # raw float32 bytes for embedding vector

backend/app/models/folders.py

@@ -1,43 +0,0 @@
-"""
-Folder and SourceRoot model definitions
-"""
-from sqlalchemy import Column, String, Integer, Boolean, DateTime, ForeignKey, Index
-from sqlalchemy.sql import func
-from sqlalchemy.orm import relationship
-import uuid
-
-from app.database import Base
-
-class SourceRoot(Base):
-    __tablename__ = 'source_roots'
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, nullable=False)
-    path = Column(String, unique=True, nullable=False)
-    is_active = Column(Boolean, default=True)
-    added_at = Column(DateTime, server_default=func.now())
-    
-    # Relationships
-    folders = relationship("Folder", back_populates="source_root")
-
-class Folder(Base):
-    __tablename__ = 'folders'
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, nullable=False)
-    path = Column(String, unique=True, nullable=False)
-    parent_id = Column(String, ForeignKey('folders.id'))
-    source_root_id = Column(String, ForeignKey('source_roots.id'))
-    photo_count = Column(Integer, default=0)
-    last_scanned = Column(DateTime)
-    
-    # Relationships
-    source_root = relationship("SourceRoot", back_populates="folders")
-    photos = relationship("Photo", backref="folder")
-    
-    # Indexes
-    __table_args__ = (
-        Index('ix_folders_path', 'path'),
-        Index('ix_folders_parent_id', 'parent_id'),
-        Index('ix_folders_source_root_id', 'source_root_id'),
-    )

backend/app/models/heaps.py

@@ -1,37 +0,0 @@
-"""
-Heap model definitions
-"""
-from sqlalchemy import Column, String, Integer, Boolean, DateTime, ForeignKey, Table, Index
-from sqlalchemy.sql import func
-from sqlalchemy.orm import relationship
-import uuid
-
-from app.database import Base
-
-# Association table for many-to-many relationship with additional fields
-heap_photos = Table(
-    'heap_photos',
-    Base.metadata,
-    Column('heap_id', String, ForeignKey('heaps.id', ondelete='CASCADE'), primary_key=True),
-    Column('photo_id', String, ForeignKey('photos.id', ondelete='CASCADE'), primary_key=True),
-    Column('added_at', DateTime, server_default=func.now()),
-    Column('sort_order', Integer, default=0),
-    Index('ix_heap_photos_heap_id', 'heap_id'),
-    Index('ix_heap_photos_photo_id', 'photo_id'),
-)
-
-class Heap(Base):
-    __tablename__ = 'heaps'
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, nullable=False)
-    created_at = Column(DateTime, server_default=func.now())
-    updated_at = Column(DateTime, onupdate=func.now())
-    is_active = Column(Boolean, default=False)  # For active heap feature
-    
-    # Relationships
-    photos = relationship("Photo", secondary=heap_photos, backref="heaps")
-
-class HeapPhoto:
-    """Helper class for heap-photo associations (not a table model)"""
-    pass

backend/app/models/photos.py

@@ -1,78 +0,0 @@
-"""
-Photo model definition
-"""
-from sqlalchemy import Column, String, Integer, Boolean, DateTime, ForeignKey, Text, Index
-from sqlalchemy.sql import func
-from datetime import datetime
-import uuid
-
-from app.database import Base
-
-class Photo(Base):
-    __tablename__ = 'photos'
-    
-    # Primary key
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    
-    # File information
-    filepath = Column(String, unique=True, nullable=False)
-    filename = Column(String, nullable=False)
-    folder_id = Column(String, ForeignKey('folders.id'))
-    file_hash = Column(String, index=True)  # SHA-256 hash for duplicate detection
-    
-    # Media information
-    media_type = Column(String, nullable=False)  # 'photo' | 'video' | 'raw' | 'heic'
-    original_format = Column(String)  # 'CR3', 'NEF', 'HEIC', 'MP4', 'JPEG', etc.
-    width = Column(Integer)
-    height = Column(Integer)
-    file_size = Column(Integer)
-    
-    # Timestamps
-    taken_at = Column(DateTime)  # from EXIF DateTimeOriginal, fallback to file mtime
-    taken_at_source = Column(String)  # 'exif' | 'filesystem' | 'manual'
-    added_at = Column(DateTime, server_default=func.now())
-    updated_at = Column(DateTime, onupdate=func.now())
-    
-    # Discard status. The DB column names stay is_trashed/trashed_at to avoid
-    # a migration; only the Python attribute name reflects the rename.
-    is_discarded = Column('is_trashed', Boolean, default=False)
-    discarded_at = Column('trashed_at', DateTime)
-    
-    # Thumbnail paths
-    thumb_small = Column(String)  # path to 240px thumb
-    thumb_medium = Column(String)  # path to 640px thumb
-    thumb_large = Column(String)  # path to 1280px thumb
-    
-    # Processing status
-    processing_status = Column(String, default='pending')  # 'pending' | 'processing' | 'completed' | 'failed'
-    processing_error = Column(Text)
-    
-    # Metadata
-    exif_json = Column(Text)  # full EXIF/XMP blob as JSON
-    
-    # User-editable fields
-    user_title = Column(String)
-    user_notes = Column(Text)
-    rating = Column(Integer, default=0)  # 0-5 stars
-    color_label = Column(String)  # 'red'|'orange'|'yellow'|'green'|'blue'|'purple'|NULL
-    # Note: is_rejected was merged into is_discarded (a single soft "discarded"
-    # concept). is_picked was unified with active-heap membership — picking a
-    # photo just means adding it to the active heap. Both DB columns may still
-    # exist on legacy installs but are no longer read or written.
-    
-    # Duplicate detection
-    is_duplicate = Column(Boolean, default=False)
-    
-    # Live photo support
-    live_photo_video_id = Column(String, ForeignKey('photos.id'))
-    
-    # Indexes for performance
-    __table_args__ = (
-        Index('ix_photos_taken_at', 'taken_at'),
-        Index('ix_photos_folder_id', 'folder_id'),
-        Index('ix_photos_is_trashed', 'is_trashed'),
-        Index('ix_photos_rating', 'rating'),
-        Index('ix_photos_color_label', 'color_label'),
-        Index('ix_photos_media_type', 'media_type'),
-        Index('ix_photos_processing_status', 'processing_status'),
-    )

backend/app/models/tags.py

@@ -1,32 +0,0 @@
-"""
-Tag model definitions
-"""
-from sqlalchemy import Column, String, ForeignKey, Table, Index
-from sqlalchemy.orm import relationship
-import uuid
-
-from app.database import Base
-
-# Association table for many-to-many relationship
-photo_tags = Table(
-    'photo_tags',
-    Base.metadata,
-    Column('photo_id', String, ForeignKey('photos.id', ondelete='CASCADE'), primary_key=True),
-    Column('tag_id', String, ForeignKey('tags.id', ondelete='CASCADE'), primary_key=True),
-    Index('ix_photo_tags_photo_id', 'photo_id'),
-    Index('ix_photo_tags_tag_id', 'tag_id'),
-)
-
-class Tag(Base):
-    __tablename__ = 'tags'
-    
-    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
-    name = Column(String, unique=True, nullable=False, index=True)
-    color = Column(String)  # Hex color code for UI display
-    
-    # Relationships
-    photos = relationship("Photo", secondary=photo_tags, backref="tags")
-
-class PhotoTag:
-    """Helper class for photo-tag associations (not a table model)"""
-    pass

backend/app/routers/discard.py

@@ -1,68 +0,0 @@
-"""
-Discard API router
-"""
-import os
-import logging
-from fastapi import APIRouter, Depends, HTTPException
-from sqlalchemy import select, and_
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.models import Photo
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter()
-
-@router.get("")
-async def list_discarded(db: AsyncSession = Depends(get_db)):
-    """List discarded photos"""
-    result = await db.execute(
-        select(Photo).where(Photo.is_discarded == True)
-    )
-    photos = result.scalars().all()
-    return photos
-
-@router.post("/restore")
-async def restore_photos(photo_ids: list[str], db: AsyncSession = Depends(get_db)):
-    """Restore photos from the discard pile"""
-    result = await db.execute(
-        select(Photo).where(and_(Photo.id.in_(photo_ids), Photo.is_discarded == True))
-    )
-    photos = result.scalars().all()
-
-    for photo in photos:
-        photo.is_discarded = False
-        photo.discarded_at = None
-
-    await db.commit()
-    return {"status": "success", "restored": len(photos)}
-
-@router.delete("/empty")
-async def empty_discard(db: AsyncSession = Depends(get_db)):
-    """Permanently delete all discarded photos and unlink their files from
-    disk. Failures on individual files are logged but don't abort the batch.
-    """
-    result = await db.execute(
-        select(Photo).where(Photo.is_discarded == True)
-    )
-    photos = result.scalars().all()
-
-    deleted = 0
-    file_errors = 0
-    for photo in photos:
-        try:
-            if photo.filepath and os.path.exists(photo.filepath):
-                os.unlink(photo.filepath)
-        except OSError as e:
-            file_errors += 1
-            logger.error(f"Failed to unlink {photo.filepath}: {e}")
-        await db.delete(photo)
-        deleted += 1
-
-    await db.commit()
-    return {
-        "status": "success",
-        "deleted": deleted,
-        "file_errors": file_errors,
-    }

backend/app/routers/folders.py

@@ -1,99 +0,0 @@
-"""
-Folders API router
-"""
-from fastapi import APIRouter, Depends, HTTPException
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-from typing import List, Optional
-from pydantic import BaseModel
-import os
-import uuid
-
-from app.database import get_db
-from app.models import Folder, SourceRoot
-
-router = APIRouter()
-
-class FolderCreate(BaseModel):
-    path: str
-    recursive: bool = True
-    watch: bool = False
-
-class FolderResponse(BaseModel):
-    id: str
-    name: str
-    path: str
-    photo_count: int
-
-@router.get("")
-async def get_folders(db: AsyncSession = Depends(get_db)):
-    """Get all source folders"""
-    # Get source roots instead of regular folders
-    result = await db.execute(select(SourceRoot).where(SourceRoot.is_active == True))
-    source_roots = result.scalars().all()
-    
-    folders_list = []
-    for root in source_roots:
-        # Get photo count for this source root
-        folder_result = await db.execute(
-            select(Folder).where(Folder.source_root_id == root.id)
-        )
-        folders = folder_result.scalars().all()
-        photo_count = sum(f.photo_count for f in folders)
-        
-        folders_list.append({
-            "id": root.id,
-            "name": root.name or os.path.basename(root.path),
-            "path": root.path,
-            "photo_count": photo_count
-        })
-    
-    return {"folders": folders_list}
-
-@router.post("")
-async def create_folder(folder: FolderCreate, db: AsyncSession = Depends(get_db)):
-    """Add a new source folder"""
-    # Check if path exists
-    if not os.path.exists(folder.path):
-        raise HTTPException(status_code=400, detail=f"Path does not exist: {folder.path}")
-    
-    # Check if path is already added
-    result = await db.execute(select(SourceRoot).where(SourceRoot.path == folder.path))
-    existing = result.scalar_one_or_none()
-    if existing:
-        raise HTTPException(status_code=400, detail="Path already added as source folder")
-    
-    # Create source root
-    source_root = SourceRoot(
-        id=str(uuid.uuid4()),
-        name=os.path.basename(folder.path),
-        path=folder.path
-    )
-    db.add(source_root)
-    await db.commit()
-    
-    # Automatically trigger a scan for the new folder
-    from app.tasks.celery import celery_app
-    celery_app.send_task('scan_folder', args=[source_root.path, source_root.id])
-    
-    return {
-        "id": source_root.id,
-        "name": source_root.name,
-        "path": source_root.path,
-        "photo_count": 0
-    }
-
-@router.post("/{folder_id}/scan")
-async def scan_folder(folder_id: str, db: AsyncSession = Depends(get_db)):
-    """Trigger manual re-scan of source root folder"""
-    from app.tasks.celery import celery_app
-    
-    result = await db.execute(select(SourceRoot).where(SourceRoot.id == folder_id))
-    source_root = result.scalar_one_or_none()
-    
-    if not source_root:
-        raise HTTPException(status_code=404, detail="Source folder not found")
-    
-    # Queue scan task using the task name defined in the decorator
-    task = celery_app.send_task('scan_folder', args=[source_root.path, source_root.id])
-    return {"status": "success", "message": f"Scan queued for {source_root.path}", "task_id": task.id}

backend/app/routers/heaps.py

@@ -1,203 +0,0 @@
-"""
-Heaps API router
-"""
-from typing import Optional
-from fastapi import APIRouter, Depends, HTTPException
-from pydantic import BaseModel
-from sqlalchemy import select, func, update, insert, delete
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.models import Heap
-from app.models.heaps import heap_photos
-
-router = APIRouter()
-
-
-# ── Schemas ───────────────────────────────────────────────────────────────
-
-class HeapCreate(BaseModel):
-    name: str
-
-
-class HeapUpdate(BaseModel):
-    name: Optional[str] = None
-    is_active: Optional[bool] = None
-
-
-class HeapPhotosBody(BaseModel):
-    photo_ids: list[str]
-
-
-# ── Endpoints ─────────────────────────────────────────────────────────────
-
-@router.get("")
-async def list_heaps(db: AsyncSession = Depends(get_db)):
-    """List all heaps with photo counts."""
-    # LEFT JOIN heap_photos and group so we can return counts in one query.
-    count_subq = (
-        select(
-            heap_photos.c.heap_id,
-            func.count(heap_photos.c.photo_id).label("photo_count"),
-        )
-        .group_by(heap_photos.c.heap_id)
-        .subquery()
-    )
-
-    stmt = (
-        select(Heap, count_subq.c.photo_count)
-        .outerjoin(count_subq, Heap.id == count_subq.c.heap_id)
-        .order_by(Heap.created_at.asc())
-    )
-    result = await db.execute(stmt)
-    rows = result.all()
-
-    return [
-        {
-            "id": h.id,
-            "name": h.name,
-            "is_active": bool(h.is_active),
-            "created_at": h.created_at,
-            "updated_at": h.updated_at,
-            "photo_count": int(count or 0),
-        }
-        for h, count in rows
-    ]
-
-
-@router.post("", status_code=201)
-async def create_heap(body: HeapCreate, db: AsyncSession = Depends(get_db)):
-    """Create a new heap."""
-    name = (body.name or "").strip()
-    if not name:
-        raise HTTPException(status_code=400, detail="Heap name is required")
-    heap = Heap(name=name)
-    db.add(heap)
-    await db.commit()
-    await db.refresh(heap)
-    return {
-        "id": heap.id,
-        "name": heap.name,
-        "is_active": bool(heap.is_active),
-        "created_at": heap.created_at,
-        "updated_at": heap.updated_at,
-        "photo_count": 0,
-    }
-
-
-@router.patch("/{heap_id}")
-async def update_heap(
-    heap_id: str, body: HeapUpdate, db: AsyncSession = Depends(get_db)
-):
-    """Rename a heap and/or toggle active state. Setting is_active=true on
-    one heap deactivates all others (single-active invariant)."""
-    result = await db.execute(select(Heap).where(Heap.id == heap_id))
-    heap = result.scalar_one_or_none()
-    if not heap:
-        raise HTTPException(status_code=404, detail="Heap not found")
-
-    if body.name is not None:
-        name = body.name.strip()
-        if not name:
-            raise HTTPException(status_code=400, detail="Heap name is required")
-        heap.name = name
-
-    if body.is_active is not None:
-        if body.is_active:
-            # Clear active flag on all other heaps in one statement
-            await db.execute(update(Heap).values(is_active=False))
-            heap.is_active = True
-        else:
-            heap.is_active = False
-
-    await db.commit()
-    await db.refresh(heap)
-    return {
-        "id": heap.id,
-        "name": heap.name,
-        "is_active": bool(heap.is_active),
-        "created_at": heap.created_at,
-        "updated_at": heap.updated_at,
-    }
-
-
-@router.delete("/{heap_id}", status_code=204)
-async def delete_heap(heap_id: str, db: AsyncSession = Depends(get_db)):
-    """Delete a heap. Photos themselves are unaffected — only the membership
-    rows in heap_photos cascade-delete."""
-    result = await db.execute(select(Heap).where(Heap.id == heap_id))
-    heap = result.scalar_one_or_none()
-    if not heap:
-        raise HTTPException(status_code=404, detail="Heap not found")
-    await db.delete(heap)
-    await db.commit()
-    return None
-
-
-@router.get("/{heap_id}/photo_ids")
-async def get_heap_photo_ids(heap_id: str, db: AsyncSession = Depends(get_db)):
-    """Return just the photo ids belonging to a heap. Used by the frontend
-    to maintain a fast client-side membership lookup for the active heap
-    (for the basket affordance on thumbnails) without fetching full photo
-    records."""
-    result = await db.execute(
-        select(heap_photos.c.photo_id).where(heap_photos.c.heap_id == heap_id)
-    )
-    return [row[0] for row in result.all()]
-
-
-@router.post("/{heap_id}/photos")
-async def add_photos_to_heap(
-    heap_id: str, body: HeapPhotosBody, db: AsyncSession = Depends(get_db)
-):
-    """Add photos to a heap. Idempotent: re-adding existing members is a
-    no-op (handled by an INSERT OR IGNORE-style filter on duplicates)."""
-    result = await db.execute(select(Heap).where(Heap.id == heap_id))
-    heap = result.scalar_one_or_none()
-    if not heap:
-        raise HTTPException(status_code=404, detail="Heap not found")
-
-    if not body.photo_ids:
-        return {"status": "success", "added": 0}
-
-    # Find which ids are already members so we don't violate the PK.
-    existing = await db.execute(
-        select(heap_photos.c.photo_id).where(
-            heap_photos.c.heap_id == heap_id,
-            heap_photos.c.photo_id.in_(body.photo_ids),
-        )
-    )
-    existing_ids = {row[0] for row in existing.all()}
-    new_ids = [pid for pid in body.photo_ids if pid not in existing_ids]
-
-    if new_ids:
-        await db.execute(
-            insert(heap_photos),
-            [{"heap_id": heap_id, "photo_id": pid} for pid in new_ids],
-        )
-        await db.commit()
-
-    return {"status": "success", "added": len(new_ids), "already_present": len(existing_ids)}
-
-
-@router.delete("/{heap_id}/photos")
-async def remove_photos_from_heap(
-    heap_id: str, body: HeapPhotosBody, db: AsyncSession = Depends(get_db)
-):
-    """Remove photos from a heap. Removing a non-member is a no-op."""
-    result = await db.execute(select(Heap).where(Heap.id == heap_id))
-    heap = result.scalar_one_or_none()
-    if not heap:
-        raise HTTPException(status_code=404, detail="Heap not found")
-
-    if not body.photo_ids:
-        return {"status": "success", "removed": 0}
-
-    res = await db.execute(
-        delete(heap_photos).where(
-            heap_photos.c.heap_id == heap_id,
-            heap_photos.c.photo_id.in_(body.photo_ids),
-        )
-    )
-    await db.commit()
-    return {"status": "success", "removed": res.rowcount or 0}

backend/app/routers/library.py

@@ -1,72 +0,0 @@
-"""
-Library API router for stats and scanning
-"""
-from fastapi import APIRouter, Depends
-from sqlalchemy import select, func
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.models import Photo
-
-router = APIRouter()
-
-@router.get("/stats")
-async def get_library_stats(db: AsyncSession = Depends(get_db)):
-    """Get library statistics"""
-    # Count total photos
-    total_photos = await db.execute(
-        select(func.count(Photo.id)).where(Photo.media_type.in_(['photo', 'heic', 'raw']))
-    )
-    photo_count = total_photos.scalar()
-    
-    # Count total videos
-    total_videos = await db.execute(
-        select(func.count(Photo.id)).where(Photo.media_type == 'video')
-    )
-    video_count = total_videos.scalar()
-    
-    # Calculate total size
-    total_size = await db.execute(
-        select(func.sum(Photo.file_size))
-    )
-    size = total_size.scalar() or 0
-    
-    return {
-        "total_photos": photo_count,
-        "total_videos": video_count,
-        "total_size": size,
-        "total_size_gb": round(size / (1024**3), 2) if size else 0
-    }
-
-@router.post("/scan")
-async def trigger_scan():
-    """Trigger full library re-scan"""
-    from app.tasks.scan import scan_all_source_roots
-    
-    scan_all_source_roots.delay()
-    
-    return {"status": "success", "message": "Library scan started"}
-
-@router.get("/scan/status")
-async def get_scan_status(db: AsyncSession = Depends(get_db)):
-    """Get current scan status"""
-    import redis
-    from app.config import settings
-    
-    # Connect to Redis to get scan status
-    r = redis.Redis.from_url(settings.redis_url)
-    
-    # Get scan status from Redis (set by worker tasks)
-    is_scanning = r.get('scan:active') == b'true'
-    current_folder = r.get('scan:current_folder')
-    processed_files = int(r.get('scan:processed_files') or 0)
-    total_files = int(r.get('scan:total_files') or 0)
-    errors = r.lrange('scan:errors', 0, -1)
-    
-    return {
-        "is_scanning": is_scanning,
-        "current_folder": current_folder.decode() if current_folder else None,
-        "processed_files": processed_files,
-        "total_files": total_files,
-        "errors": [e.decode() for e in errors] if errors else []
-    }

backend/app/routers/photos.py

@@ -1,526 +0,0 @@
-"""
-Photos API router
-"""
-from typing import List, Optional, Dict, Any
-from datetime import datetime
-from pathlib import Path
-from fastapi import APIRouter, Depends, HTTPException, Query, Response
-from fastapi.responses import FileResponse
-from sqlalchemy import select, and_, or_, func
-from sqlalchemy.ext.asyncio import AsyncSession
-import json
-import os
-import logging
-
-logger = logging.getLogger(__name__)
-
-from app.database import get_db
-from app.models import Photo, Folder, Tag, PhotoTag
-from app.models.folders import SourceRoot
-from app.models.heaps import heap_photos
-from app.schemas.photos import PhotoResponse, PhotoUpdate, PhotoListResponse, BulkAction
-from app.config import settings
-
-router = APIRouter()
-
-@router.get("", response_model=PhotoListResponse)
-async def list_photos(
-    q: Optional[str] = None,
-    date_from: Optional[datetime] = None,
-    date_to: Optional[datetime] = None,
-    folder_id: Optional[str] = None,
-    tag_ids: Optional[str] = None,
-    media_type: Optional[str] = None,
-    rating_min: Optional[int] = Query(None, ge=0, le=5),
-    rating_max: Optional[int] = Query(None, ge=0, le=5),
-    color_label: Optional[str] = None,
-    is_discarded: Optional[bool] = False,
-    heap_id: Optional[str] = None,
-    sort: str = "taken_at",
-    order: str = "desc",
-    page: int = Query(1, ge=1),
-    per_page: int = Query(100, ge=1, le=500),
-    db: AsyncSession = Depends(get_db)
-):
-    """List photos with filters and pagination"""
-    
-    # Build query
-    query = select(Photo)
-    
-    # Apply filters
-    filters = []
-    
-    # Text search (would use FTS5 in production)
-    if q:
-        search_pattern = f"%{q}%"
-        filters.append(
-            or_(
-                Photo.filename.ilike(search_pattern),
-                Photo.user_title.ilike(search_pattern),
-                Photo.user_notes.ilike(search_pattern),
-                Photo.exif_json.ilike(search_pattern)
-            )
-        )
-    
-    # Date range
-    if date_from:
-        filters.append(Photo.taken_at >= date_from)
-    if date_to:
-        filters.append(Photo.taken_at <= date_to)
-    
-    # Folder filter — the sidebar exposes "source roots" (top-level scan
-    # paths) under the same UI affordance as folders, so the same param has
-    # to accept either a folder id or a source root id. If the value matches
-    # a source root, expand to every folder under that root and use IN.
-    if folder_id:
-        sr_check = await db.execute(
-            select(SourceRoot.id).where(SourceRoot.id == folder_id)
-        )
-        if sr_check.scalar_one_or_none() is not None:
-            child_folders = await db.execute(
-                select(Folder.id).where(Folder.source_root_id == folder_id)
-            )
-            child_ids = [row[0] for row in child_folders.all()]
-            if child_ids:
-                filters.append(Photo.folder_id.in_(child_ids))
-            else:
-                # Source root with no folder rows yet — match nothing rather
-                # than returning the entire library.
-                filters.append(Photo.id == '__no_match__')
-        else:
-            filters.append(Photo.folder_id == folder_id)
-    
-    # Media type filter
-    if media_type:
-        types = media_type.split(',')
-        filters.append(Photo.media_type.in_(types))
-    
-    # Rating filter
-    if rating_min is not None:
-        filters.append(Photo.rating >= rating_min)
-    if rating_max is not None:
-        filters.append(Photo.rating <= rating_max)
-    
-    # Color label filter
-    if color_label:
-        if color_label == 'none':
-            filters.append(Photo.color_label.is_(None))
-        else:
-            filters.append(Photo.color_label == color_label)
-    
-    # Discard filter — defaults to hiding discarded photos
-    filters.append(Photo.is_discarded == is_discarded)
-
-    # Heap membership filter — restrict to photos that belong to the heap.
-    if heap_id:
-        filters.append(
-            Photo.id.in_(
-                select(heap_photos.c.photo_id).where(heap_photos.c.heap_id == heap_id)
-            )
-        )
-
-    # Apply all filters
-    if filters:
-        query = query.where(and_(*filters))
-    
-    # Apply sorting
-    sort_column = getattr(Photo, sort, Photo.taken_at)
-    if order == "desc":
-        query = query.order_by(sort_column.desc())
-    else:
-        query = query.order_by(sort_column.asc())
-    
-    # Count total results
-    count_query = select(func.count()).select_from(query.subquery())
-    total_result = await db.execute(count_query)
-    total = total_result.scalar()
-    
-    # Apply pagination
-    offset = (page - 1) * per_page
-    query = query.offset(offset).limit(per_page)
-    
-    # Execute query
-    result = await db.execute(query)
-    photos = result.scalars().all()
-    
-    # Convert to response
-    return PhotoListResponse(
-        photos=[PhotoResponse.from_orm(photo) for photo in photos],
-        total=total,
-        page=page,
-        per_page=per_page,
-        pages=(total + per_page - 1) // per_page
-    )
-
-@router.get("/{photo_id}", response_model=PhotoResponse)
-async def get_photo(
-    photo_id: str,
-    db: AsyncSession = Depends(get_db)
-):
-    """Get single photo with full EXIF and tags"""
-    result = await db.execute(
-        select(Photo).where(Photo.id == photo_id)
-    )
-    photo = result.scalar_one_or_none()
-    
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-    
-    return PhotoResponse.from_orm(photo)
-
-@router.get("/{photo_id}/thumb/{size}")
-async def get_thumbnail(
-    photo_id: str,
-    size: str,
-    response: Response,
-    db: AsyncSession = Depends(get_db)
-):
-    """Serve thumbnail (with Nginx X-Accel-Redirect support)"""
-    if size not in ['small', 'medium', 'large']:
-        raise HTTPException(status_code=400, detail="Invalid thumbnail size")
-    
-    result = await db.execute(
-        select(Photo).where(Photo.id == photo_id)
-    )
-    photo = result.scalar_one_or_none()
-    
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-    
-    # Check if thumbnail exists, generate if not
-    thumb_dir = f"/data/thumbs/{photo_id}"
-    thumb_path = f"{thumb_dir}/{size}.webp"
-    
-    if not os.path.exists(thumb_path):
-        # Generate thumbnail on demand
-        from app.tasks.thumbs import generate_thumbnails
-        generate_thumbnails.delay(photo_id)
-        
-        # For now, return a placeholder or the original with reduced quality
-        if os.path.exists(photo.filepath):
-            from PIL import Image
-            try:
-                os.makedirs(thumb_dir, exist_ok=True)
-                img = Image.open(photo.filepath)
-                
-                # Auto-rotate based on EXIF
-                from PIL import ExifTags
-                try:
-                    for orientation in ExifTags.TAGS.keys():
-                        if ExifTags.TAGS[orientation] == 'Orientation':
-                            break
-                    exif = img._getexif()
-                    if exif is not None:
-                        orient = exif.get(orientation)
-                        if orient == 3:
-                            img = img.rotate(180, expand=True)
-                        elif orient == 6:
-                            img = img.rotate(270, expand=True)
-                        elif orient == 8:
-                            img = img.rotate(90, expand=True)
-                except:
-                    pass
-                
-                # Generate thumbnail size
-                sizes = {'small': 150, 'medium': 400, 'large': 800}
-                target_size = sizes.get(size, 400)
-                img.thumbnail((target_size, target_size), Image.Resampling.LANCZOS)
-                
-                # Save as WebP
-                img.save(thumb_path, 'WEBP', quality=85, optimize=True)
-                
-            except Exception as e:
-                logger.error(f"Error generating thumbnail: {e}")
-                raise HTTPException(status_code=404, detail="Could not generate thumbnail")
-    
-    # Check if we're behind Nginx
-    if os.environ.get('USE_X_ACCEL_REDIRECT'):
-        # Use Nginx X-Accel-Redirect for better performance
-        response.headers['X-Accel-Redirect'] = f'/internal_thumbs/{photo_id}/{size}.webp'
-        response.headers['Content-Type'] = 'image/webp'
-        return Response()
-    else:
-        # Direct file serving for development
-        return FileResponse(thumb_path, media_type='image/webp')
-
-@router.get("/{photo_id}/original")
-async def get_original(
-    photo_id: str,
-    db: AsyncSession = Depends(get_db)
-):
-    """Serve original file (download for RAW, inline for web-safe formats)"""
-    result = await db.execute(
-        select(Photo).where(Photo.id == photo_id)
-    )
-    photo = result.scalar_one_or_none()
-
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-
-    if not os.path.exists(photo.filepath):
-        raise HTTPException(status_code=404, detail="File not found")
-
-    # Pick a media type the browser can render inline for web-safe formats
-    # so the loupe view and <video> tags work without forcing a download.
-    ext = Path(photo.filepath).suffix.lower()
-    inline_types = {
-        '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
-        '.png': 'image/png', '.webp': 'image/webp', '.gif': 'image/gif',
-        '.mp4': 'video/mp4', '.mov': 'video/quicktime',
-        '.webm': 'video/webm', '.mkv': 'video/x-matroska',
-    }
-    media_type = inline_types.get(ext, 'application/octet-stream')
-
-    return FileResponse(
-        photo.filepath,
-        filename=photo.filename if media_type == 'application/octet-stream' else None,
-        media_type=media_type,
-    )
-
-
-# Extensions that the browser can decode natively. Anything else (RAW, HEIC,
-# TIFF) needs the /proxy endpoint to convert to WebP for display.
-_WEB_SAFE_DISPLAY_EXTS = {'.jpg', '.jpeg', '.png', '.webp', '.gif'}
-
-
-def _generate_proxy_webp(src_path: str, dst_path: str) -> None:
-    """Decode src_path with the appropriate backend and write a full-res WebP
-    to dst_path. Used by GET /photos/{id}/proxy for RAW/HEIC/TIFF display.
-
-    Conservative: catches per-format failures and falls back to extracting an
-    embedded preview where possible (RAW), so a single broken file never
-    crashes the request.
-    """
-    from PIL import Image
-    ext = Path(src_path).suffix.lower()
-
-    img = None
-
-    # RAW formats — decode via rawpy at full size
-    raw_exts = {'.cr2', '.cr3', '.nef', '.nrw', '.arw', '.srf',
-                '.raf', '.rw2', '.orf', '.srw', '.pef', '.rwl', '.dng'}
-    if ext in raw_exts:
-        try:
-            import rawpy
-            with rawpy.imread(src_path) as raw:
-                rgb = raw.postprocess(use_camera_wb=True, no_auto_bright=False)
-            img = Image.fromarray(rgb, 'RGB')
-        except Exception as e:
-            logger.warning(f"rawpy decode failed for {src_path}: {e}; trying embedded preview")
-            try:
-                import rawpy
-                with rawpy.imread(src_path) as raw:
-                    thumb = raw.extract_thumb()
-                    if thumb.format == rawpy.ThumbFormat.JPEG:
-                        from io import BytesIO
-                        img = Image.open(BytesIO(thumb.data))
-            except Exception as e2:
-                logger.error(f"RAW preview extraction also failed for {src_path}: {e2}")
-                raise HTTPException(status_code=415, detail="Unable to decode RAW file")
-
-    # HEIC/HEIF — pillow-heif registers a PIL plugin
-    elif ext in {'.heic', '.heif'}:
-        try:
-            from pillow_heif import register_heif_opener
-            register_heif_opener()
-            img = Image.open(src_path)
-        except Exception as e:
-            logger.error(f"HEIC decode failed for {src_path}: {e}")
-            raise HTTPException(status_code=415, detail="Unable to decode HEIC file")
-
-    # TIFF and any other PIL-supported format
-    else:
-        try:
-            img = Image.open(src_path)
-        except Exception as e:
-            logger.error(f"PIL open failed for {src_path}: {e}")
-            raise HTTPException(status_code=415, detail="Unable to decode image")
-
-    # Auto-rotate via EXIF
-    try:
-        from PIL import ImageOps
-        img = ImageOps.exif_transpose(img)
-    except Exception:
-        pass
-
-    if img.mode not in ('RGB', 'RGBA'):
-        img = img.convert('RGB')
-
-    os.makedirs(os.path.dirname(dst_path), exist_ok=True)
-    img.save(dst_path, 'WEBP', quality=90, method=4)
-
-
-@router.get("/{photo_id}/proxy")
-async def get_proxy(
-    photo_id: str,
-    response: Response,
-    db: AsyncSession = Depends(get_db),
-):
-    """Serve a full-resolution WebP proxy for non-web-safe formats (RAW, HEIC,
-    TIFF) so the loupe view can display them inline. Web-safe formats are
-    redirected to /original to avoid pointless transcoding.
-
-    Cached at /data/proxies/{photo_id}.webp; subsequent requests serve the
-    cached file (with optional X-Accel-Redirect for production).
-    """
-    result = await db.execute(select(Photo).where(Photo.id == photo_id))
-    photo = result.scalar_one_or_none()
-
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-
-    if not os.path.exists(photo.filepath):
-        raise HTTPException(status_code=404, detail="File not found")
-
-    ext = Path(photo.filepath).suffix.lower()
-
-    # Web-safe formats don't need a proxy — serve the original directly so the
-    # browser uses its native decoder. Saves disk and CPU.
-    if ext in _WEB_SAFE_DISPLAY_EXTS:
-        return FileResponse(
-            photo.filepath,
-            media_type={
-                '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
-                '.png': 'image/png', '.webp': 'image/webp', '.gif': 'image/gif',
-            }[ext],
-        )
-
-    proxy_dir = "/data/proxies"
-    proxy_path = f"{proxy_dir}/{photo_id}.webp"
-
-    if not os.path.exists(proxy_path):
-        try:
-            _generate_proxy_webp(photo.filepath, proxy_path)
-        except HTTPException:
-            raise
-        except Exception as e:
-            logger.error(f"Proxy generation failed for {photo_id}: {e}")
-            raise HTTPException(status_code=500, detail="Proxy generation failed")
-
-    if os.environ.get('USE_X_ACCEL_REDIRECT'):
-        response.headers['X-Accel-Redirect'] = f'/internal_proxies/{photo_id}.webp'
-        response.headers['Content-Type'] = 'image/webp'
-        return Response()
-
-    return FileResponse(proxy_path, media_type='image/webp')
-
-@router.patch("/{photo_id}", response_model=PhotoResponse)
-async def update_photo(
-    photo_id: str,
-    update: PhotoUpdate,
-    db: AsyncSession = Depends(get_db)
-):
-    """Update photo metadata. If `filename` is included, also rename the
-    file on disk in its current directory (no cross-folder moves through
-    this endpoint).
-    """
-    result = await db.execute(
-        select(Photo).where(Photo.id == photo_id)
-    )
-    photo = result.scalar_one_or_none()
-
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-
-    update_data = update.dict(exclude_unset=True)
-
-    # Filename rename: validate, rename on disk, then update both filename
-    # and filepath atomically. Done before any other field changes so a
-    # filesystem failure leaves the rest of the row untouched.
-    if 'filename' in update_data:
-        new_name = (update_data.pop('filename') or '').strip()
-        if not new_name:
-            raise HTTPException(status_code=400, detail="Filename cannot be empty")
-        # Reject path separators and parent traversal — same-directory only.
-        if '/' in new_name or '\\' in new_name or new_name in ('.', '..'):
-            raise HTTPException(status_code=400, detail="Invalid filename")
-
-        if new_name != photo.filename:
-            current_dir = os.path.dirname(photo.filepath)
-            new_path = os.path.join(current_dir, new_name)
-
-            if not os.path.exists(photo.filepath):
-                raise HTTPException(status_code=404, detail="Source file missing on disk")
-            if os.path.exists(new_path):
-                raise HTTPException(status_code=409, detail="A file with that name already exists")
-
-            try:
-                os.rename(photo.filepath, new_path)
-            except OSError as e:
-                logger.error(f"Failed to rename {photo.filepath} -> {new_path}: {e}")
-                raise HTTPException(status_code=500, detail=f"Rename failed: {e}")
-
-            photo.filename = new_name
-            photo.filepath = new_path
-
-    # Apply remaining updates
-    for field, value in update_data.items():
-        setattr(photo, field, value)
-
-    await db.commit()
-    await db.refresh(photo)
-    
-    return PhotoResponse.from_orm(photo)
-
-@router.delete("/{photo_id}")
-async def discard_photo(
-    photo_id: str,
-    db: AsyncSession = Depends(get_db)
-):
-    """Soft-discard a photo: sets is_discarded=true. The file stays on disk so
-    restore is just a flag flip. Permanent deletion happens via DELETE
-    /discard/{id} or DELETE /discard/empty.
-    """
-    result = await db.execute(
-        select(Photo).where(Photo.id == photo_id)
-    )
-    photo = result.scalar_one_or_none()
-
-    if not photo:
-        raise HTTPException(status_code=404, detail="Photo not found")
-
-    photo.is_discarded = True
-    photo.discarded_at = datetime.utcnow()
-    await db.commit()
-
-    return {"status": "success", "message": "Photo discarded"}
-
-@router.post("/bulk")
-async def bulk_action(
-    action: BulkAction,
-    db: AsyncSession = Depends(get_db)
-):
-    """Perform bulk actions on multiple photos"""
-    # Get photos
-    result = await db.execute(
-        select(Photo).where(Photo.id.in_(action.ids))
-    )
-    photos = result.scalars().all()
-    
-    if not photos:
-        raise HTTPException(status_code=404, detail="No photos found")
-    
-    # Perform action based on type
-    if action.action == 'discard':
-        for photo in photos:
-            photo.is_discarded = True
-            photo.discarded_at = datetime.utcnow()
-    elif action.action == 'restore':
-        for photo in photos:
-            photo.is_discarded = False
-            photo.discarded_at = None
-    elif action.action == 'set_rating':
-        for photo in photos:
-            photo.rating = action.value
-    elif action.action == 'set_color':
-        for photo in photos:
-            photo.color_label = action.value
-    else:
-        raise HTTPException(status_code=400, detail="Invalid action")
-    
-    await db.commit()
-    
-    return {
-        "status": "success",
-        "message": f"{action.action} applied to {len(photos)} photos"
-    }

backend/app/routers/tags.py

@@ -1,27 +0,0 @@
-"""
-Tags API router
-"""
-from fastapi import APIRouter, Depends, HTTPException
-from sqlalchemy import select, func
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.models import Tag
-
-router = APIRouter()
-
-@router.get("")
-async def list_tags(db: AsyncSession = Depends(get_db)):
-    """List all tags with usage counts"""
-    result = await db.execute(select(Tag))
-    tags = result.scalars().all()
-    return tags
-
-@router.post("")
-async def create_tag(name: str, color: str = None, db: AsyncSession = Depends(get_db)):
-    """Create a new tag"""
-    tag = Tag(name=name, color=color)
-    db.add(tag)
-    await db.commit()
-    await db.refresh(tag)
-    return tag

backend/app/schemas/photos.py

@@ -1,69 +0,0 @@
-"""
-Pydantic schemas for photos
-"""
-from pydantic import BaseModel, Field
-from typing import Optional, List, Dict, Any
-from datetime import datetime
-
-class PhotoBase(BaseModel):
-    """Base photo schema"""
-    filename: str
-    media_type: str
-    original_format: Optional[str] = None
-    width: Optional[int] = None
-    height: Optional[int] = None
-    file_size: Optional[int] = None
-    taken_at: Optional[datetime] = None
-    taken_at_source: Optional[str] = None
-    user_title: Optional[str] = None
-    user_notes: Optional[str] = None
-    rating: int = 0
-    color_label: Optional[str] = None
-
-class PhotoResponse(PhotoBase):
-    """Photo response schema"""
-    id: str
-    filepath: str
-    folder_id: Optional[str] = None
-    file_hash: Optional[str] = None
-    added_at: datetime
-    updated_at: Optional[datetime] = None
-    is_discarded: bool = False
-    discarded_at: Optional[datetime] = None
-    thumb_small: Optional[str] = None
-    thumb_medium: Optional[str] = None
-    thumb_large: Optional[str] = None
-    processing_status: str = 'pending'
-    processing_error: Optional[str] = None
-    exif_json: Optional[str] = None
-    is_duplicate: bool = False
-    live_photo_video_id: Optional[str] = None
-    # tags: List[Dict[str, Any]] = []  # TODO: Enable when using eager loading
-    
-    class Config:
-        orm_mode = True
-        from_attributes = True
-
-class PhotoUpdate(BaseModel):
-    """Photo update schema"""
-    filename: Optional[str] = None
-    user_title: Optional[str] = None
-    user_notes: Optional[str] = None
-    rating: Optional[int] = Field(None, ge=0, le=5)
-    color_label: Optional[str] = None
-    is_discarded: Optional[bool] = None
-    taken_at: Optional[datetime] = None
-
-class PhotoListResponse(BaseModel):
-    """Photo list response with pagination"""
-    photos: List[PhotoResponse]
-    total: int
-    page: int
-    per_page: int
-    pages: int
-
-class BulkAction(BaseModel):
-    """Bulk action on photos"""
-    ids: List[str]
-    action: str  # 'discard', 'restore', 'delete_permanent', 'move', 'copy', 'add_tag', 'remove_tag', 'set_rating', 'set_color'
-    value: Optional[Any] = None  # For actions that need a value (rating, color, tag_id, folder_id)

backend/app/services/cleanup.py

@@ -1,141 +0,0 @@
-"""
-One-shot data integrity cleanup for source_roots / folders / photos.
-
-Earlier versions of the scanner stored paths verbatim, so trailing slashes
-and redundant separators produced duplicate SourceRoot and Folder rows for
-the same physical directory. The watcher also auto-created source roots
-when fired with a parent dir. This module merges the duplicates and
-re-points photos to the canonical folder so the data lines up with the
-post-fix scanner.
-
-Idempotent: safe to run on every backend startup.
-"""
-import os
-import logging
-from datetime import datetime
-from sqlalchemy import select, update, func
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import AsyncSessionLocal
-from app.models import Photo, Folder, SourceRoot
-
-logger = logging.getLogger(__name__)
-
-
-def _normalize_path(path: str) -> str:
-    return os.path.normpath(path)
-
-
-async def _dedupe_source_roots(session: AsyncSession) -> int:
-    """Group source roots by normalized path and merge duplicates. Returns
-    the number of rows deleted."""
-    result = await session.execute(select(SourceRoot))
-    rows = result.scalars().all()
-
-    groups: dict[str, list[SourceRoot]] = {}
-    for sr in rows:
-        norm = _normalize_path(sr.path)
-        groups.setdefault(norm, []).append(sr)
-
-    deleted = 0
-    for norm, srs in groups.items():
-        if len(srs) == 1:
-            # Make sure the canonical row's path is normalized too.
-            if srs[0].path != norm:
-                srs[0].path = norm
-            continue
-        # Pick the canonical row: prefer one with a non-empty name and the
-        # earliest added_at (most likely the original).
-        canonical = sorted(
-            srs,
-            key=lambda s: (not bool(s.name), s.added_at or datetime.max),
-        )[0]
-        canonical.path = norm
-        for sr in srs:
-            if sr.id == canonical.id:
-                continue
-            # Re-point folders that referenced the duplicate root.
-            await session.execute(
-                update(Folder)
-                .where(Folder.source_root_id == sr.id)
-                .values(source_root_id=canonical.id)
-            )
-            await session.delete(sr)
-            deleted += 1
-
-    return deleted
-
-
-async def _dedupe_folders(session: AsyncSession) -> int:
-    """Group folders by normalized path and merge duplicates. Returns the
-    number of rows deleted."""
-    result = await session.execute(select(Folder))
-    rows = result.scalars().all()
-
-    groups: dict[str, list[Folder]] = {}
-    for f in rows:
-        norm = _normalize_path(f.path)
-        groups.setdefault(norm, []).append(f)
-
-    deleted = 0
-    for norm, folders in groups.items():
-        if len(folders) == 1:
-            if folders[0].path != norm:
-                folders[0].path = norm
-            continue
-        # Canonical = the one with the most photos already attached, then
-        # the lowest-id (deterministic tiebreaker).
-        canonical = sorted(
-            folders,
-            key=lambda f: (-(f.photo_count or 0), f.id),
-        )[0]
-        canonical.path = norm
-        for f in folders:
-            if f.id == canonical.id:
-                continue
-            # Re-point photos to the canonical folder.
-            await session.execute(
-                update(Photo)
-                .where(Photo.folder_id == f.id)
-                .values(folder_id=canonical.id)
-            )
-            await session.delete(f)
-            deleted += 1
-
-    return deleted
-
-
-async def _recompute_folder_counts(session: AsyncSession) -> None:
-    """Set folder.photo_count to the actual non-discarded photo count."""
-    result = await session.execute(select(Folder))
-    folders = result.scalars().all()
-    for f in folders:
-        count_result = await session.execute(
-            select(func.count(Photo.id)).where(
-                Photo.folder_id == f.id,
-                Photo.is_discarded == False,  # noqa: E712
-            )
-        )
-        f.photo_count = int(count_result.scalar() or 0)
-
-
-async def cleanup_data_integrity() -> dict:
-    """Top-level entry point. Runs the dedupe + count refresh in a single
-    transaction. Returns a small summary dict for logging."""
-    async with AsyncSessionLocal() as session:
-        try:
-            sr_deleted = await _dedupe_source_roots(session)
-            f_deleted = await _dedupe_folders(session)
-            await _recompute_folder_counts(session)
-            await session.commit()
-            summary = {
-                "source_roots_merged": sr_deleted,
-                "folders_merged": f_deleted,
-            }
-            if sr_deleted or f_deleted:
-                logger.info(f"Cleanup merged duplicates: {summary}")
-            return summary
-        except Exception as e:
-            logger.error(f"Cleanup failed: {e}")
-            await session.rollback()
-            raise

backend/app/services/metadata.py

@@ -1,183 +0,0 @@
-"""
-Metadata extraction service using ExifTool
-"""
-import json
-import logging
-import asyncio
-from datetime import datetime
-from typing import Dict, Optional
-import subprocess
-from pathlib import Path
-
-from celery import shared_task
-from sqlalchemy import select
-
-from app.database import AsyncSessionLocal
-from app.models import Photo
-
-logger = logging.getLogger(__name__)
-
-def parse_exif_datetime(date_str: str) -> Optional[datetime]:
-    """Parse EXIF datetime string to Python datetime"""
-    if not date_str:
-        return None
-    
-    # Common EXIF datetime formats
-    formats = [
-        "%Y:%m:%d %H:%M:%S",
-        "%Y-%m-%d %H:%M:%S",
-        "%Y:%m:%d %H:%M:%S.%f",
-        "%Y-%m-%dT%H:%M:%S",
-        "%Y-%m-%dT%H:%M:%S.%f",
-        "%Y-%m-%dT%H:%M:%S%z"
-    ]
-    
-    for fmt in formats:
-        try:
-            return datetime.strptime(date_str, fmt)
-        except ValueError:
-            continue
-    
-    return None
-
-def extract_key_metadata(exif_data: Dict) -> Dict:
-    """Extract key metadata fields for FTS indexing"""
-    key_fields = []
-    
-    # Camera information
-    if 'Make' in exif_data:
-        key_fields.append(exif_data['Make'])
-    if 'Model' in exif_data:
-        key_fields.append(exif_data['Model'])
-    if 'LensModel' in exif_data:
-        key_fields.append(exif_data['LensModel'])
-    
-    # Location information
-    if 'GPSLatitude' in exif_data and 'GPSLongitude' in exif_data:
-        key_fields.append(f"GPS: {exif_data['GPSLatitude']}, {exif_data['GPSLongitude']}")
-    
-    # IPTC/XMP keywords
-    if 'Keywords' in exif_data:
-        if isinstance(exif_data['Keywords'], list):
-            key_fields.extend(exif_data['Keywords'])
-        else:
-            key_fields.append(exif_data['Keywords'])
-    
-    # Copyright and creator
-    if 'Copyright' in exif_data:
-        key_fields.append(exif_data['Copyright'])
-    if 'Creator' in exif_data:
-        key_fields.append(exif_data['Creator'])
-    if 'Artist' in exif_data:
-        key_fields.append(exif_data['Artist'])
-    
-    return {
-        'exif_text': ' '.join(key_fields),
-        'camera_make': exif_data.get('Make'),
-        'camera_model': exif_data.get('Model'),
-        'lens_model': exif_data.get('LensModel'),
-        'gps_latitude': exif_data.get('GPSLatitude'),
-        'gps_longitude': exif_data.get('GPSLongitude'),
-    }
-
-@shared_task(name='extract_metadata')
-def extract_metadata(photo_id: str):
-    """Extract metadata from a photo using ExifTool"""
-    return asyncio.run(_extract_metadata_async(photo_id))
-
-async def _extract_metadata_async(photo_id: str):
-    """Async implementation of metadata extraction"""
-    async with AsyncSessionLocal() as session:
-        try:
-            # Get photo from database
-            result = await session.execute(
-                select(Photo).where(Photo.id == photo_id)
-            )
-            photo = result.scalar_one_or_none()
-            
-            if not photo:
-                logger.error(f"Photo not found: {photo_id}")
-                return {'status': 'error', 'message': 'Photo not found'}
-            
-            # Check if file exists
-            if not Path(photo.filepath).exists():
-                logger.error(f"File not found: {photo.filepath}")
-                return {'status': 'error', 'message': 'File not found'}
-            
-            # Run ExifTool to extract metadata
-            cmd = [
-                'exiftool',
-                '-j',  # JSON output
-                '-G',  # Group names
-                '-s',  # Short output format
-                '-All',  # All metadata
-                photo.filepath
-            ]
-            
-            try:
-                result = subprocess.run(
-                    cmd,
-                    capture_output=True,
-                    text=True,
-                    timeout=30
-                )
-                
-                if result.returncode != 0:
-                    logger.error(f"ExifTool error: {result.stderr}")
-                    return {'status': 'error', 'message': result.stderr}
-                
-                # Parse JSON output
-                metadata = json.loads(result.stdout)
-                if metadata and len(metadata) > 0:
-                    exif_data = metadata[0]
-                    
-                    # Store full metadata as JSON
-                    photo.exif_json = json.dumps(exif_data)
-                    
-                    # Extract taken_at date
-                    date_fields = [
-                        'EXIF:DateTimeOriginal',
-                        'EXIF:CreateDate',
-                        'QuickTime:MediaCreateDate',
-                        'EXIF:ModifyDate'
-                    ]
-                    
-                    for field in date_fields:
-                        if field in exif_data:
-                            taken_at = parse_exif_datetime(exif_data[field])
-                            if taken_at:
-                                photo.taken_at = taken_at
-                                photo.taken_at_source = 'exif'
-                                break
-                    
-                    # Extract dimensions if not already set
-                    if not photo.width:
-                        photo.width = exif_data.get('EXIF:ImageWidth') or exif_data.get('File:ImageWidth')
-                    if not photo.height:
-                        photo.height = exif_data.get('EXIF:ImageHeight') or exif_data.get('File:ImageHeight')
-                    
-                    # Extract and store key metadata for search
-                    key_metadata = extract_key_metadata(exif_data)
-                    
-                    # Update FTS table (would be done via trigger in production)
-                    # For now, we'll store it in a comment
-                    
-                    await session.commit()
-                    
-                    logger.info(f"Metadata extracted for photo {photo_id}")
-                    return {
-                        'status': 'success',
-                        'photo_id': photo_id,
-                        'taken_at': photo.taken_at.isoformat() if photo.taken_at else None
-                    }
-                
-            except subprocess.TimeoutExpired:
-                logger.error(f"ExifTool timeout for {photo.filepath}")
-                return {'status': 'error', 'message': 'ExifTool timeout'}
-            except json.JSONDecodeError as e:
-                logger.error(f"Failed to parse ExifTool output: {e}")
-                return {'status': 'error', 'message': 'Invalid ExifTool output'}
-            
-        except Exception as e:
-            logger.error(f"Error extracting metadata for {photo_id}: {e}")
-            return {'status': 'error', 'message': str(e)}

backend/app/services/scanner.py

@@ -1,22 +0,0 @@
-"""
-Scanner service for initial library scan
-"""
-import logging
-from app.tasks.scan import scan_all_source_roots, watch_folders
-from app.config import settings
-
-logger = logging.getLogger(__name__)
-
-async def start_initial_scan():
-    """Start the initial library scan"""
-    try:
-        # Queue scan of all source roots
-        scan_all_source_roots.delay()
-        
-        # Start folder watcher if configured
-        if settings.scanner.watch:
-            watch_folders.delay()
-        
-        logger.info("Initial scan queued successfully")
-    except Exception as e:
-        logger.error(f"Failed to start initial scan: {e}")

backend/app/tasks/__init__.py

@@ -1,15 +0,0 @@
-"""
-Celery tasks module
-"""
-from app.tasks.celery import celery_app
-from app.tasks.scan import scan_folder, scan_all_source_roots, watch_folders
-from app.tasks.thumbs import generate_thumbnails, regenerate_all_thumbnails
-
-__all__ = [
-    'celery_app',
-    'scan_folder',
-    'scan_all_source_roots',
-    'watch_folders',
-    'generate_thumbnails',
-    'regenerate_all_thumbnails'
-]

backend/app/tasks/celery.py

@@ -1,31 +0,0 @@
-"""
-Celery configuration and app initialization
-"""
-from celery import Celery
-from app.config import settings
-
-# Create Celery app
-celery_app = Celery(
-    'mulita',
-    broker=settings.celery_broker_url,
-    backend=settings.celery_result_backend,
-    include=['app.tasks.scan', 'app.tasks.thumbs']
-)
-
-# Configure Celery
-celery_app.conf.update(
-    task_serializer='json',
-    accept_content=['json'],
-    result_serializer='json',
-    timezone='UTC',
-    enable_utc=True,
-    task_routes={
-        'app.tasks.thumbs.*': {'queue': 'high'},
-        'app.tasks.scan.*': {'queue': 'low'},
-    },
-    task_default_queue='default',
-    task_default_exchange='default',
-    task_default_exchange_type='direct',
-    task_default_routing_key='default',
-    broker_connection_retry_on_startup=True,
-)

backend/app/tasks/scan.py

@@ -1,308 +0,0 @@
-"""
-Celery tasks for scanning folders and indexing photos
-"""
-import os
-import hashlib
-import asyncio
-from pathlib import Path
-from datetime import datetime
-import logging
-import json
-from typing import List, Dict, Optional
-
-from celery import shared_task
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-import aiofiles
-
-from app.database import AsyncSessionLocal
-from app.models import Photo, Folder, SourceRoot
-from app.config import settings
-from app.tasks.thumbs import generate_thumbnails
-from app.services.metadata import extract_metadata
-
-logger = logging.getLogger(__name__)
-
-# Supported file extensions
-PHOTO_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.tiff', '.tif', '.webp', '.bmp'}
-RAW_EXTENSIONS = {'.cr2', '.cr3', '.nef', '.arw', '.raf', '.dng', '.orf', '.rw2', '.pef', '.srw'}
-HEIC_EXTENSIONS = {'.heic', '.heif'}
-VIDEO_EXTENSIONS = {'.mp4', '.mov', '.avi', '.mkv', '.mts', '.m2ts', '.3gp', '.wmv', '.flv'}
-
-SUPPORTED_EXTENSIONS = PHOTO_EXTENSIONS | RAW_EXTENSIONS | HEIC_EXTENSIONS | VIDEO_EXTENSIONS
-
-def get_media_type(filepath: str) -> str:
-    """Determine media type from file extension"""
-    ext = Path(filepath).suffix.lower()
-    if ext in PHOTO_EXTENSIONS:
-        return 'photo'
-    elif ext in RAW_EXTENSIONS:
-        return 'raw'
-    elif ext in HEIC_EXTENSIONS:
-        return 'heic'
-    elif ext in VIDEO_EXTENSIONS:
-        return 'video'
-    return 'unknown'
-
-async def calculate_file_hash(filepath: str) -> str:
-    """Calculate SHA-256 hash of a file"""
-    hash_sha256 = hashlib.sha256()
-    try:
-        async with aiofiles.open(filepath, 'rb') as f:
-            while chunk := await f.read(8192):
-                hash_sha256.update(chunk)
-        return hash_sha256.hexdigest()
-    except Exception as e:
-        logger.error(f"Error calculating hash for {filepath}: {e}")
-        return ""
-
-@shared_task(bind=True, name='scan_folder')
-def scan_folder(self, folder_path: str, source_root_id: Optional[str] = None):
-    """
-    Scan a folder and index all photos/videos
-    """
-    # Run async function in sync context
-    return asyncio.run(_scan_folder_async(folder_path, source_root_id, self))
-
-async def _scan_folder_async(folder_path: str, source_root_id: Optional[str], task):
-    """Async implementation of folder scanning"""
-    logger.info(f"Starting scan of folder: {folder_path}")
-    
-    async with AsyncSessionLocal() as session:
-        try:
-            # Get or create source root
-            if not source_root_id:
-                source_root = await get_or_create_source_root(session, folder_path)
-                source_root_id = source_root.id
-            
-            # Walk the directory tree
-            total_files = 0
-            processed_files = 0
-            errors = []
-            
-            for root, dirs, files in os.walk(folder_path):
-                # Get or create folder entry
-                folder = await get_or_create_folder(session, root, source_root_id)
-                
-                # Filter supported files
-                supported_files = [f for f in files if Path(f).suffix.lower() in SUPPORTED_EXTENSIONS]
-                total_files += len(supported_files)
-                
-                # Process files in batches
-                batch_size = settings.scanner.batch_size
-                for i in range(0, len(supported_files), batch_size):
-                    batch = supported_files[i:i + batch_size]
-                    
-                    for filename in batch:
-                        filepath = os.path.join(root, filename)
-                        
-                        try:
-                            # Check if file already exists in database
-                            existing = await session.execute(
-                                select(Photo).where(Photo.filepath == filepath)
-                            )
-                            if existing.scalar_one_or_none():
-                                logger.debug(f"File already indexed: {filepath}")
-                                processed_files += 1
-                                continue
-                            
-                            # Get file stats
-                            stat = os.stat(filepath)
-                            
-                            # Calculate file hash for duplicate detection
-                            file_hash = await calculate_file_hash(filepath)
-                            
-                            # Check for duplicate by hash
-                            duplicate = await session.execute(
-                                select(Photo).where(Photo.file_hash == file_hash)
-                            ) if file_hash else None
-                            
-                            # Create photo entry
-                            photo = Photo(
-                                filepath=filepath,
-                                filename=filename,
-                                folder_id=folder.id,
-                                file_hash=file_hash,
-                                media_type=get_media_type(filepath),
-                                original_format=Path(filepath).suffix.upper()[1:],
-                                file_size=stat.st_size,
-                                taken_at=datetime.fromtimestamp(stat.st_mtime),
-                                taken_at_source='filesystem',
-                                is_duplicate=bool(duplicate.scalar_one_or_none() if duplicate else False),
-                                processing_status='pending'
-                            )
-                            
-                            session.add(photo)
-                            await session.flush()  # Get the photo ID
-                            
-                            # Queue thumbnail generation
-                            generate_thumbnails.delay(photo.id)
-                            
-                            # Queue metadata extraction
-                            extract_metadata.delay(photo.id)
-                            
-                            processed_files += 1
-                            
-                            # Update progress
-                            if processed_files % 10 == 0:
-                                task.update_state(
-                                    state='PROGRESS',
-                                    meta={
-                                        'current': processed_files,
-                                        'total': total_files,
-                                        'folder': root
-                                    }
-                                )
-                            
-                        except Exception as e:
-                            logger.error(f"Error processing file {filepath}: {e}")
-                            errors.append({'file': filepath, 'error': str(e)})
-                            continue
-                    
-                    # Commit batch
-                    await session.commit()
-            
-            # Update folder scan timestamp
-            folder.last_scanned = datetime.utcnow()
-            folder.photo_count = processed_files
-            await session.commit()
-            
-            logger.info(f"Scan complete. Processed {processed_files}/{total_files} files. Errors: {len(errors)}")
-            
-            return {
-                'status': 'completed',
-                'processed': processed_files,
-                'total': total_files,
-                'errors': errors
-            }
-            
-        except Exception as e:
-            logger.error(f"Scan failed: {e}")
-            await session.rollback()
-            raise
-
-def _normalize_path(path: str) -> str:
-    """Canonicalise a filesystem path so we don't get duplicate DB rows for
-    the same physical directory due to trailing slashes, redundant separators,
-    or `.` segments. Symlinks are NOT resolved (we want to keep mount paths
-    intact for cross-machine portability)."""
-    return os.path.normpath(path)
-
-
-async def get_or_create_source_root(session: AsyncSession, path: str) -> SourceRoot:
-    """Get or create a source root entry, matching by normalized path."""
-    from sqlalchemy import select
-
-    norm = _normalize_path(path)
-    result = await session.execute(
-        select(SourceRoot).where(SourceRoot.path == norm)
-    )
-    source_root = result.scalar_one_or_none()
-
-    if not source_root:
-        source_root = SourceRoot(
-            name=Path(norm).name,
-            path=norm,
-        )
-        session.add(source_root)
-        await session.flush()
-
-    return source_root
-
-
-async def get_or_create_folder(session: AsyncSession, path: str, source_root_id: str) -> Folder:
-    """Get or create a folder entry, matching by normalized path."""
-    from sqlalchemy import select
-
-    norm = _normalize_path(path)
-    result = await session.execute(
-        select(Folder).where(Folder.path == norm)
-    )
-    folder = result.scalar_one_or_none()
-
-    if not folder:
-        parent_path = _normalize_path(str(Path(norm).parent))
-
-        if parent_path != norm:  # Not the filesystem root
-            parent_result = await session.execute(
-                select(Folder).where(Folder.path == parent_path)
-            )
-            parent = parent_result.scalar_one_or_none()
-            if parent:
-                parent_id = parent.id
-            else:
-                # Recursively create parent
-                parent = await get_or_create_folder(session, parent_path, source_root_id)
-                parent_id = parent.id
-        else:
-            parent_id = None
-
-        folder = Folder(
-            name=Path(norm).name,
-            path=norm,
-            parent_id=parent_id,
-            source_root_id=source_root_id,
-        )
-        session.add(folder)
-        await session.flush()
-
-    return folder
-
-@shared_task(name='scan_all_source_roots')
-def scan_all_source_roots():
-    """Scan all configured source roots"""
-    for source_root in settings.source_roots:
-        if os.path.exists(source_root.path):
-            scan_folder.delay(source_root.path)
-        else:
-            logger.warning(f"Source root path does not exist: {source_root.path}")
-
-@shared_task(name='watch_folders')
-def watch_folders():
-    """
-    Watch folders for changes using watchfiles
-    This is a long-running task that monitors file system events
-    """
-    from watchfiles import watch
-    
-    paths = [sr.path for sr in settings.source_roots if os.path.exists(sr.path)]
-    
-    if not paths:
-        logger.warning("No valid source roots to watch")
-        return
-    
-    logger.info(f"Starting folder watcher for: {paths}")
-    
-    for changes in watch(*paths):
-        for change_type, filepath in changes:
-            filepath = str(filepath)
-            
-            # Check if it's a supported file type
-            if Path(filepath).suffix.lower() not in SUPPORTED_EXTENSIONS:
-                continue
-            
-            if change_type == 'added' or change_type == 'modified':
-                # Queue scan for the parent folder
-                parent_dir = str(Path(filepath).parent)
-                scan_folder.delay(parent_dir)
-                logger.info(f"File {change_type}: {filepath}, queued scan for {parent_dir}")
-            elif change_type == 'deleted':
-                # Handle file deletion
-                asyncio.run(handle_file_deletion(filepath))
-
-async def handle_file_deletion(filepath: str):
-    """Handle deletion of a file from the filesystem"""
-    from sqlalchemy import select
-    
-    async with AsyncSessionLocal() as session:
-        result = await session.execute(
-            select(Photo).where(Photo.filepath == filepath)
-        )
-        photo = result.scalar_one_or_none()
-        
-        if photo:
-            # Mark as missing or delete from database
-            photo.is_discarded = True
-            photo.discarded_at = datetime.utcnow()
-            await session.commit()
-            logger.info(f"Marked photo as discarded: {filepath}")

backend/app/tasks/thumbs.py

@@ -1,283 +0,0 @@
-"""
-Celery tasks for thumbnail generation
-"""
-import os
-import asyncio
-from pathlib import Path
-import logging
-from typing import Tuple, Optional
-import json
-
-from celery import shared_task
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-from PIL import Image
-import imageio
-from pillow_heif import register_heif_opener
-import ffmpeg
-
-# Try to import optional libraries
-try:
-    import pyvips
-    PYVIPS_AVAILABLE = True
-except ImportError:
-    PYVIPS_AVAILABLE = False
-    print("pyvips not available, using Pillow for image processing")
-
-try:
-    import rawpy
-    RAWPY_AVAILABLE = True
-except ImportError:
-    RAWPY_AVAILABLE = False
-    print("rawpy not available, using exiftool for RAW preview extraction")
-
-from app.database import AsyncSessionLocal
-from app.models import Photo
-from app.config import settings
-
-# Register HEIF opener with Pillow
-register_heif_opener()
-
-logger = logging.getLogger(__name__)
-
-# Thumbnail sizes configuration
-THUMB_SIZES = {
-    'small': settings.thumbnails.small,
-    'medium': settings.thumbnails.medium,
-    'large': settings.thumbnails.large
-}
-
-def get_thumb_path(photo_id: str, size: str) -> str:
-    """Get the path for a thumbnail file"""
-    thumb_dir = f"/data/thumbs/{photo_id}"
-    os.makedirs(thumb_dir, exist_ok=True)
-    return f"{thumb_dir}/{size}.{settings.thumbnails.format}"
-
-def process_standard_image(filepath: str) -> Image.Image:
-    """Process standard image formats (JPEG, PNG, etc.)"""
-    return Image.open(filepath)
-
-def process_raw_image(filepath: str) -> Image.Image:
-    """Process RAW image formats"""
-    if RAWPY_AVAILABLE:
-        try:
-            with rawpy.imread(filepath) as raw:
-                # Use half_size for faster processing
-                rgb = raw.postprocess(use_camera_wb=True, half_size=True)
-                # Convert numpy array to PIL Image
-                return Image.fromarray(rgb, 'RGB')
-        except Exception as e:
-            logger.error(f"Error processing RAW file {filepath}: {e}")
-            # Try to extract embedded JPEG preview
-            return extract_raw_preview(filepath)
-    else:
-        # Use exiftool to extract embedded preview
-        return extract_raw_preview(filepath)
-
-def extract_raw_preview(filepath: str) -> Optional[Image.Image]:
-    """Extract embedded JPEG preview from RAW file"""
-    try:
-        # Use exiftool to extract preview
-        import subprocess
-        import tempfile
-        
-        with tempfile.NamedTemporaryFile(suffix='.jpg', delete=False) as tmp:
-            cmd = ['exiftool', '-b', '-PreviewImage', filepath]
-            result = subprocess.run(cmd, capture_output=True)
-            
-            if result.returncode == 0 and result.stdout:
-                tmp.write(result.stdout)
-                tmp.flush()
-                return Image.open(tmp.name)
-    except Exception as e:
-        logger.error(f"Error extracting RAW preview from {filepath}: {e}")
-    
-    return None
-
-def process_heic_image(filepath: str) -> Image.Image:
-    """Process HEIC/HEIF image formats"""
-    try:
-        # Use pillow-heif to open the image
-        img = Image.open(filepath)
-        # Convert to RGB if needed
-        if img.mode != 'RGB':
-            img = img.convert('RGB')
-        return img
-    except Exception as e:
-        logger.error(f"Error processing HEIC file {filepath}: {e}")
-        raise
-
-def process_video_thumbnail(filepath: str) -> Image.Image:
-    """Extract thumbnail from video file"""
-    try:
-        # Get video duration
-        probe = ffmpeg.probe(filepath)
-        duration = float(probe['streams'][0]['duration'])
-        
-        # Extract frame at 10% of duration
-        timestamp = duration * 0.1
-        
-        # Extract frame using ffmpeg
-        import tempfile
-        with tempfile.NamedTemporaryFile(suffix='.jpg', delete=False) as tmp:
-            stream = ffmpeg.input(filepath, ss=timestamp)
-            stream = ffmpeg.output(stream, tmp.name, vframes=1, format='image2', vcodec='mjpeg')
-            ffmpeg.run(stream, capture_stdout=True, capture_stderr=True)
-            
-            return Image.open(tmp.name)
-    except Exception as e:
-        logger.error(f"Error extracting video thumbnail from {filepath}: {e}")
-        # Create a placeholder thumbnail
-        return create_placeholder_thumbnail('video')
-
-def create_placeholder_thumbnail(media_type: str) -> Image.Image:
-    """Create a placeholder thumbnail for failed processing"""
-    # Create a simple gray placeholder
-    img = Image.new('RGB', (640, 480), color=(128, 128, 128))
-    return img
-
-def auto_rotate_image(image: Image.Image) -> Image.Image:
-    """Auto-rotate image based on EXIF orientation"""
-    try:
-        # Get EXIF data
-        exif = image._getexif()
-        if exif:
-            orientation = exif.get(274)  # Orientation tag
-            
-            rotation_map = {
-                3: 180,
-                6: 270,  # Note: PIL uses different rotation values than vips
-                8: 90
-            }
-            
-            if orientation in rotation_map:
-                image = image.rotate(rotation_map[orientation], expand=True)
-    except:
-        pass  # No orientation data available
-    
-    return image
-
-def generate_thumbnail(image: Image.Image, size: int, output_path: str):
-    """Generate a thumbnail of the specified size"""
-    # Maintain aspect ratio
-    image.thumbnail((size, size), Image.Resampling.LANCZOS)
-    
-    # Save as WebP with specified quality
-    image.save(
-        output_path,
-        'WEBP',
-        quality=settings.thumbnails.quality,
-        method=4  # Balance between speed and compression
-    )
-
-@shared_task(bind=True, name='generate_thumbnails')
-def generate_thumbnails(self, photo_id: str):
-    """Generate thumbnails for a photo"""
-    return asyncio.run(_generate_thumbnails_async(photo_id, self))
-
-async def _generate_thumbnails_async(photo_id: str, task):
-    """Async implementation of thumbnail generation"""
-    async with AsyncSessionLocal() as session:
-        try:
-            # Get photo from database
-            result = await session.execute(
-                select(Photo).where(Photo.id == photo_id)
-            )
-            photo = result.scalar_one_or_none()
-            
-            if not photo:
-                logger.error(f"Photo not found: {photo_id}")
-                return {'status': 'error', 'message': 'Photo not found'}
-            
-            # Check if file exists
-            if not os.path.exists(photo.filepath):
-                logger.error(f"File not found: {photo.filepath}")
-                photo.processing_status = 'failed'
-                photo.processing_error = 'File not found'
-                await session.commit()
-                return {'status': 'error', 'message': 'File not found'}
-            
-            # Update processing status
-            photo.processing_status = 'processing'
-            await session.commit()
-            
-            # Load and process the image based on type
-            image = None
-            
-            if photo.media_type == 'photo':
-                image = process_standard_image(photo.filepath)
-            elif photo.media_type == 'raw':
-                image = process_raw_image(photo.filepath)
-            elif photo.media_type == 'heic':
-                image = process_heic_image(photo.filepath)
-            elif photo.media_type == 'video':
-                image = process_video_thumbnail(photo.filepath)
-            else:
-                logger.error(f"Unsupported media type: {photo.media_type}")
-                image = create_placeholder_thumbnail(photo.media_type)
-            
-            if not image:
-                raise Exception("Failed to process image")
-            
-            # Auto-rotate based on EXIF
-            image = auto_rotate_image(image)
-            
-            # Store original dimensions
-            photo.width = image.width
-            photo.height = image.height
-            
-            # Generate thumbnails for each size
-            for size_name, size_value in THUMB_SIZES.items():
-                thumb_path = get_thumb_path(photo_id, size_name)
-                generate_thumbnail(image, size_value, thumb_path)
-                
-                # Update database with thumbnail path
-                setattr(photo, f'thumb_{size_name}', thumb_path)
-                
-                # Update progress
-                task.update_state(
-                    state='PROGRESS',
-                    meta={'current_size': size_name, 'photo_id': photo_id}
-                )
-            
-            # Update processing status
-            photo.processing_status = 'completed'
-            photo.processing_error = None
-            await session.commit()
-            
-            logger.info(f"Thumbnails generated for photo {photo_id}")
-            return {'status': 'success', 'photo_id': photo_id}
-            
-        except Exception as e:
-            logger.error(f"Error generating thumbnails for {photo_id}: {e}")
-            
-            # Update error status
-            if photo:
-                photo.processing_status = 'failed'
-                photo.processing_error = str(e)
-                await session.commit()
-            
-            return {'status': 'error', 'message': str(e)}
-
-@shared_task(name='regenerate_all_thumbnails')
-def regenerate_all_thumbnails():
-    """Regenerate thumbnails for all photos"""
-    return asyncio.run(_regenerate_all_thumbnails_async())
-
-async def _regenerate_all_thumbnails_async():
-    """Async implementation of regenerating all thumbnails"""
-    async with AsyncSessionLocal() as session:
-        # Get all photos that need thumbnails
-        result = await session.execute(
-            select(Photo).where(
-                Photo.processing_status.in_(['pending', 'failed'])
-            )
-        )
-        photos = result.scalars().all()
-        
-        logger.info(f"Regenerating thumbnails for {len(photos)} photos")
-        
-        for photo in photos:
-            generate_thumbnails.delay(photo.id)
-        
-        return {'status': 'queued', 'count': len(photos)}

backend/requirements.txt

@@ -1,49 +0,0 @@
-# Core dependencies
-fastapi==0.109.0
-uvicorn[standard]==0.27.0
-python-multipart==0.0.6
-
-# Database
-sqlalchemy[asyncio]==2.0.25
-aiosqlite==0.19.0
-alembic==1.13.1
-
-# Redis and Celery
-redis==5.0.1
-celery==5.3.6
-flower==2.0.1
-
-# Image processing
-# pyvips==2.2.1  # Optional - having compatibility issues, using Pillow as fallback
-# rawpy==0.19.0  # Optional - numpy compatibility issues, using Pillow as fallback
-pillow==10.2.0
-pillow-heif==0.15.0
-imageio==2.33.1
-imageio-ffmpeg==0.4.9
-
-# Video processing
-ffmpeg-python==0.2.0
-
-# Metadata extraction
-pyexiftool==0.5.6
-
-# File watching
-watchfiles==0.21.0
-
-# Utilities
-pyyaml==6.0.1
-pydantic==2.5.3
-pydantic-settings==2.1.0
-python-dotenv==1.0.0
-httpx==0.26.0
-aiofiles==23.2.1
-
-# Security and authentication
-python-jose[cryptography]==3.3.0
-passlib[bcrypt]==1.7.4
-
-# Development
-pytest==7.4.4
-pytest-asyncio==0.23.3
-black==23.12.1
-ruff==0.1.11

docker-compose.gpu.yml

@@ -0,0 +1,24 @@
+# Overlay for hosts with a VA-API-capable GPU passed through (Intel
+# QSV, AMD VCN/VCE, any VA-API driver). PhotoPrism's :latest image
+# ships VA-API-enabled ffmpeg; this file just wires the device + group
+# membership + encoder selection. Layered in by the deploy script on
+# hosts where /dev/dri/renderD128 exists.
+#
+# Usage:
+#   docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
+
+services:
+  photoprism:
+    devices:
+      - /dev/dri/renderD128:/dev/dri/renderD128
+      - /dev/dri/card0:/dev/dri/card0
+    # Match host GIDs (render=992, video=44 on Debian). PhotoPrism's
+    # container user (PP_UID:PP_GID, typically 33:10000) is not in
+    # these groups by default; group_add grants access to the device
+    # nodes without changing the primary user.
+    group_add:
+      - "992"
+      - "44"
+    environment:
+      PHOTOPRISM_FFMPEG_ENCODER: ${PP_FFMPEG_ENCODER:-vaapi}
+      PHOTOPRISM_FFMPEG_BITRATE: ${PP_FFMPEG_BITRATE:-32}

docker-compose.podman.yml

@@ -0,0 +1,34 @@
+# Podman-rootless overlay for the PhotoPrism stack.
+#
+# Apply alongside the base compose file:
+#   podman-compose --env-file .env \
+#     -f docker-compose.yml \
+#     -f docker-compose.podman.yml \
+#     up -d
+#
+# Adds the podman-specific bits that would break a vanilla docker compose run:
+#   - userns_mode: keep-id maps container UID to the invoking host UID, so
+#     PhotoPrism (running as PP_UID:PP_GID inside) can actually read the
+#     bind-mounted originals volume on the host (which is owned by the host
+#     user, not by uid 1000-in-the-container-namespace).
+#   - the explicit security_opt entries on the base file work in podman as-is.
+
+services:
+  # MariaDB writes to a named volume managed by podman; its in-container
+  # `mysql` user expects to own that volume. keep-id breaks this by mapping
+  # in-container UID 999 to a podman-subuid that doesn't own the volume,
+  # so let mariadb use the default userns mapping (root-in-namespace).
+  mariadb:
+    # No userns_mode override — use podman defaults.
+    init: true
+
+  # PhotoPrism does need keep-id, so its container UID maps back to the
+  # host UID that owns the bind-mounted originals/.
+  photoprism:
+    userns_mode: keep-id
+
+  # Sidecar mutates the originals tree (rename / folder ops / heap
+  # convert / .duplicates archive) — same keep-id mapping so its writes
+  # land as the host user, not as a podman-subuid the host doesn't own.
+  sidecar:
+    userns_mode: keep-id

docker-compose.yml

@@ -1,98 +1,209 @@
-version: '3.8'
+# Compose stack for the PhotoPrism-backed photo app: mariadb + photoprism +
+# Go sidecar. The SvelteKit web/ frontend runs separately (Vite in dev,
+# static build in prod) and proxies /api/v1/* to photoprism and
+# /api/sidecar/* to the sidecar.
+#
+#   podman-compose --env-file .env \
+#     -f docker-compose.yml -f docker-compose.podman.yml up -d
 
 services:
-  frontend:
-    build: 
-      context: ./frontend
-      dockerfile: Dockerfile
-    container_name: mulita-frontend
-    ports:
-      - "3000:80"
-    depends_on:
-      - backend
-    networks:
-      - mulita-network
+  mariadb:
+    # Fully-qualified for podman (which refuses short names by default).
+    # Docker resolves the same digest.
+    image: docker.io/library/mariadb:11
+    container_name: pp-mariadb
     restart: unless-stopped
-
-  backend:
-    build:
-      context: ./backend
-      dockerfile: Dockerfile
-    container_name: mulita-backend
-    ports:
-      - "8001:8000"
-    volumes:
-      - ./mulita.yml:/app/config/mulita.yml:ro
-      - ${PHOTO_DIRS:-./photos}:/photos:rw
-      # NOTE: read-write — file operations (rename, move, discard,
-      # empty discard pile) need to mutate the filesystem. Flip to :ro
-      # if you want a strict read-only library; the rename / move /
-      # delete endpoints will then return EROFS.
-      - ~/Pictures:/host/Pictures:rw
-      - thumbs_data:/data/thumbs
-      - proxies_data:/data/proxies
-      - db_data:/data/db
-      - trash_data:/data/trash
+    command:
+      - --innodb-buffer-pool-size=512M
+      - --transaction-isolation=READ-COMMITTED
+      - --character-set-server=utf8mb4
+      - --collation-server=utf8mb4_unicode_ci
+      - --max-connections=512
+      - --innodb-rollback-on-timeout=OFF
+      - --innodb-lock-wait-timeout=120
     environment:
-      - DATABASE_URL=sqlite+aiosqlite:////data/db/mulita.db
-      - REDIS_URL=redis://redis:6379
-      - CELERY_BROKER_URL=redis://redis:6379
-      - CELERY_RESULT_BACKEND=redis://redis:6379
-      - PHOTO_DIRS=${PHOTO_DIRS:-/photos}
-    depends_on:
-      - redis
-    networks:
-      - mulita-network
-    restart: unless-stopped
-
-  worker:
-    build:
-      context: ./backend
-      dockerfile: Dockerfile
-    container_name: mulita-worker
-    command: celery -A app.tasks.celery worker --loglevel=info --concurrency=4
-    volumes:
-      - ./mulita.yml:/app/config/mulita.yml:ro
-      - ${PHOTO_DIRS:-./photos}:/photos:rw
-      # See backend service for the rationale on :rw.
-      - ~/Pictures:/host/Pictures:rw
-      - thumbs_data:/data/thumbs
-      - proxies_data:/data/proxies
-      - db_data:/data/db
-      - trash_data:/data/trash
-    environment:
-      - DATABASE_URL=sqlite+aiosqlite:////data/db/mulita.db
-      - REDIS_URL=redis://redis:6379
-      - CELERY_BROKER_URL=redis://redis:6379
-      - CELERY_RESULT_BACKEND=redis://redis:6379
-      - PHOTO_DIRS=${PHOTO_DIRS:-/photos}
-      - CELERYD_CONCURRENCY=4
-    depends_on:
-      - redis
-      - backend
-    networks:
-      - mulita-network
-    restart: unless-stopped
-
-  redis:
-    image: redis:7-alpine
-    container_name: mulita-redis
+      MARIADB_AUTO_UPGRADE: "1"
+      MARIADB_INITDB_SKIP_TZINFO: "1"
+      MARIADB_DATABASE: ${PP_DB_NAME:-photoprism}
+      MARIADB_USER: ${PP_DB_USER:-photoprism}
+      MARIADB_PASSWORD: ${PP_DB_PASSWORD:?set PP_DB_PASSWORD in .env}
+      MARIADB_ROOT_PASSWORD: ${PP_DB_ROOT_PASSWORD:?set PP_DB_ROOT_PASSWORD in .env}
+    # Loopback-only host port so the mule-sidecar (running as a host process
+    # in M4) can reach `mule_sidecar.*` over TCP. Not exposed beyond
+    # 127.0.0.1; the photoprism container still resolves mariadb by service
+    # name on the photoprism-network bridge.
     ports:
-      - "6379:6379"
+      - "127.0.0.1:${PP_DB_PORT:-3306}:3306"
     volumes:
-      - redis_data:/data
-    networks:
-      - mulita-network
+      - pp_mariadb_data:/var/lib/mysql
+      # The init script creates the mule_sidecar database + user that the Go
+      # sidecar service will use in M4. Idempotent; no-op on subsequent boots.
+      # ":Z" is the SELinux private-relabel flag — needed on Fedora/RHEL hosts,
+      # silently no-op on Debian/Ubuntu and macOS Docker Desktop.
+      - ./mariadb/init:/docker-entrypoint-initdb.d:ro,Z
+    healthcheck:
+      test: ["CMD", "/usr/bin/mariadb-admin", "ping", "-h", "127.0.0.1", "--silent"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 60s
+    networks: [photoprism-network]
+
+  photoprism:
+    image: docker.io/photoprism/photoprism:latest
+    container_name: pp-app
     restart: unless-stopped
-    command: redis-server --appendonly yes
+    depends_on:
+      mariadb:
+        condition: service_healthy
+    # PhotoPrism's container drops to a non-root user via PHOTOPRISM_UID /
+    # PHOTOPRISM_GID. Match the host user that owns ${PHOTO_DIRS} so the
+    # process can read originals (and later write sidecars).
+    user: "${PP_UID:-1000}:${PP_GID:-1000}"
+    security_opt:
+      - seccomp:unconfined
+      - apparmor:unconfined
+    ports:
+      # Loopback only — the SvelteKit web/ app (Vite dev or built bundle)
+      # is the user-facing surface; PhotoPrism's own UI stays off the
+      # public interface. Vite proxies /api/v1/* here, and the host-mode
+      # sidecar reaches PHOTOPRISM_BASE_URL=http://localhost:2342. Admin
+      # access to PP's UI is via SSH tunnel only.
+      - "127.0.0.1:${PP_PORT:-2342}:2342"
+    environment:
+      PHOTOPRISM_ADMIN_USER: ${PP_ADMIN_USER:-admin}
+      PHOTOPRISM_ADMIN_PASSWORD: ${PP_ADMIN_PASSWORD:?set PP_ADMIN_PASSWORD in .env}
+      PHOTOPRISM_AUTH_MODE: ${PP_AUTH_MODE:-password}
+      PHOTOPRISM_SITE_URL: ${PP_SITE_URL:-http://localhost:2342/}
+      PHOTOPRISM_ORIGINALS_LIMIT: ${PP_ORIGINALS_LIMIT:-50000}
+      PHOTOPRISM_HTTP_COMPRESSION: gzip
+      PHOTOPRISM_LOG_LEVEL: ${PP_LOG_LEVEL:-info}
+      # Indexer concurrency. Defaults to NumCPU/2 (= 3 on a 6-core LXC),
+      # but each worker forks TF + ffmpeg + libvips so effective load is
+      # much higher — a fresh index of 1.2k photos on M0 pushed the LXC
+      # load to 50+ and starved sibling containers. Pin to a low value
+      # for shared hosts; raise on dedicated machines.
+      PHOTOPRISM_WORKERS: ${PP_WORKERS:-2}
+      # podman-compose doesn't expand nested ${A:-${B:-…}}, so keep this
+      # one-level. Override both PP_WORKERS and PP_INDEX_WORKERS if you
+      # want them to differ.
+      PHOTOPRISM_INDEX_WORKERS: ${PP_INDEX_WORKERS:-2}
+      # M0 safety: keep originals read-only. Flip to "false" in M2 when the
+      # right-sidebar enables metadata edits and we want EXIF backwrite.
+      PHOTOPRISM_READONLY: ${PP_READONLY:-true}
+      PHOTOPRISM_EXPERIMENTAL: "false"
+      PHOTOPRISM_DISABLE_CHOWN: "true"
+      PHOTOPRISM_DISABLE_WEBDAV: ${PP_DISABLE_WEBDAV:-false}
+      PHOTOPRISM_DISABLE_SETTINGS: "false"
+      PHOTOPRISM_DISABLE_TLS: "true"
+      PHOTOPRISM_DEFAULT_TLS: "false"
+      # AI/vision pipeline back on — per plan we re-introduce TF labels + faces.
+      PHOTOPRISM_TENSORFLOW_OFF: "false"
+      PHOTOPRISM_DETECT_NSFW: "true"
+      PHOTOPRISM_UPLOAD_NSFW: "true"
+      # Database
+      PHOTOPRISM_DATABASE_DRIVER: mysql
+      PHOTOPRISM_DATABASE_SERVER: mariadb:3306
+      PHOTOPRISM_DATABASE_NAME: ${PP_DB_NAME:-photoprism}
+      PHOTOPRISM_DATABASE_USER: ${PP_DB_USER:-photoprism}
+      PHOTOPRISM_DATABASE_PASSWORD: ${PP_DB_PASSWORD}
+      # Sidecars next to originals — read by the migrator at M5.
+      PHOTOPRISM_SIDECAR_PATH: ""
+      PHOTOPRISM_SIDECAR_YAML: "true"
+      # EXIF backwrite — disabled in M0 (READONLY blocks writes anyway).
+      # Override in .env: PP_BACKUP_DATABASE=true.
+      PHOTOPRISM_DISABLE_BACKUPS: "false"
+      PHOTOPRISM_BACKUP_DATABASE: ${PP_BACKUP_DATABASE:-true}
+      PHOTOPRISM_DISABLE_EXIFTOOL: "false"
+      # OIDC — set in .env when the IdP (Authentik) is wired up.
+      # Empty values keep OIDC dormant; the username/password login still works.
+      # PhotoPrism's CLI flags are --oidc-uri / --oidc-client / --oidc-secret
+      # / --oidc-provider, so the env-var names it actually reads are
+      # PHOTOPRISM_OIDC_URI / _CLIENT / _SECRET / _PROVIDER (NOT _ISSUER_URL
+      # / _CLIENT_ID / _CLIENT_SECRET / _PROVIDER_NAME — those are silently
+      # ignored, OIDC stays dormant, and `photoprism show config` reports
+      # blank oidc-uri / oidc-client). PHOTOPRISM_OIDC_REDIRECT is a bool
+      # (auto-redirect-from-/library/login), not a URL — PhotoPrism builds
+      # the callback from PHOTOPRISM_SITE_URL.
+      PHOTOPRISM_OIDC_PROVIDER: ${OIDC_PROVIDER_NAME:-${OIDC_PROVIDER:-}}
+      PHOTOPRISM_OIDC_URI: ${OIDC_ISSUER_URL:-${OIDC_URI:-}}
+      PHOTOPRISM_OIDC_CLIENT: ${OIDC_CLIENT_ID:-${OIDC_CLIENT:-}}
+      PHOTOPRISM_OIDC_SECRET: ${OIDC_CLIENT_SECRET:-${OIDC_SECRET:-}}
+      PHOTOPRISM_OIDC_SCOPES: ${OIDC_SCOPES:-openid profile email}
+      PHOTOPRISM_OIDC_REGISTER: ${OIDC_REGISTER:-true}
+      PHOTOPRISM_OIDC_ROLE: ${OIDC_ROLE:-user}
+      PHOTOPRISM_OIDC_REDIRECT: ${OIDC_REDIRECT:-false}
+    working_dir: /photoprism
+    volumes:
+      # Existing photo library — mounted read-only in M0; flip to :rw in M2
+      # when the right-sidebar starts saving edits. ",Z" relabels for SELinux
+      # on Fedora/RHEL; silent no-op elsewhere.
+      - "${PHOTO_DIRS:?set PHOTO_DIRS in .env}:/photoprism/originals:${PP_ORIGINALS_MODE:-ro},Z"
+      - "./pp/storage:/photoprism/storage:Z"
+      - "./pp/import:/photoprism/import:Z"
+    networks: [photoprism-network]
+
+  # mule-sidecar — Go + Gin + GORM service for endpoints PhotoPrism's API
+  # does not expose (file rename, folder mutations, heap convert, duplicate
+  # scan, per-photo marks). Same wire contract as the M3 Node prototype;
+  # the SvelteKit dev server proxies /api/sidecar/* here.
+  sidecar:
+    build:
+      context: ./sidecar
+    container_name: pp-sidecar
+    restart: unless-stopped
+    depends_on:
+      mariadb:
+        condition: service_healthy
+      photoprism:
+        condition: service_started
+    # Match PhotoPrism's UID/GID so renames/folder mutations preserve the
+    # ownership the indexer expects on the bind-mounted originals.
+    user: "${PP_UID:-1000}:${PP_GID:-1000}"
+    ports:
+      # Loopback only — Vite (host) proxies /api/sidecar/* to this port.
+      # Behind a reverse proxy in production; never published beyond the
+      # host.
+      - "127.0.0.1:${SIDECAR_PORT:-8000}:8000"
+    environment:
+      ORIGINALS_ROOT: /photoprism/originals
+      PHOTOPRISM_BASE_URL: http://photoprism:2342
+      # Bind on all interfaces inside the container so the host-side
+      # 127.0.0.1:8000 port mapping can reach the listener. The Go
+      # binary defaults to 127.0.0.1 for the host-mode dev loop.
+      SIDECAR_LISTEN_ADDR: 0.0.0.0
+      SIDECAR_PORT: "8000"
+      SIDECAR_DB_HOST: mariadb
+      SIDECAR_DB_PORT: "3306"
+      SIDECAR_DB_USER: sidecar
+      # Rotate before any non-local deployment. Provisioned by
+      # mariadb/init/01-sidecar.sql on first boot of the mariadb volume.
+      SIDECAR_DB_PASSWORD: ${SIDECAR_DB_PASSWORD:-replace-at-m4-bringup}
+      SIDECAR_DB_NAME: mule_sidecar
+      # Second DB connection for poking PhotoPrism's own schema (only
+      # used by the user-basepath reconciler today). Stays inert if
+      # PP_DB_PASSWORD is empty — the reconciler then silently no-ops.
+      PP_DB_HOST: mariadb
+      PP_DB_PORT: "3306"
+      PP_DB_USER: ${PP_DB_USER:-photoprism}
+      PP_DB_PASSWORD: ${PP_DB_PASSWORD:-}
+      PP_DB_NAME: ${PP_DB_NAME:-photoprism}
+      # Declarative username → originals-relative BasePath mapping.
+      # Format: comma-separated `user:path` pairs. Sidecar applies it
+      # to auth_users on boot and every 60s, and `mkdir -p`s each
+      # target subdirectory so PhotoPrism's ACL filter has somewhere to
+      # point. Leave empty to disable.
+      #   USER_BASEPATHS="test:test, alice:family/alice"
+      USER_BASEPATHS: ${USER_BASEPATHS:-}
+    volumes:
+      # Sidecar mutates originals (rename, folder mutations, heap
+      # convert) — always rw regardless of PhotoPrism's mount mode.
+      - "${PHOTO_DIRS:?set PHOTO_DIRS in .env}:/photoprism/originals:rw,Z"
+    networks: [photoprism-network]
 
 networks:
-  mulita-network:
+  photoprism-network:
     driver: bridge
 
 volumes:
-  thumbs_data:
-  proxies_data:
-  db_data:
-  trash_data:
-  redis_data:
+  pp_mariadb_data:

frontend/Dockerfile

@@ -1,31 +0,0 @@
-# Build stage
-FROM node:18-alpine as build
-
-WORKDIR /app
-
-# Copy package files
-COPY package*.json ./
-
-# Install dependencies
-RUN npm ci
-
-# Copy source code
-COPY . .
-
-# Build the application
-RUN npm run build
-
-# Production stage
-FROM nginx:alpine
-
-# Copy built assets from build stage
-COPY --from=build /app/dist /usr/share/nginx/html
-
-# Copy nginx configuration
-COPY nginx.conf /etc/nginx/conf.d/default.conf
-
-# Expose port
-EXPOSE 80
-
-# Start nginx
-CMD ["nginx", "-g", "daemon off;"]

frontend/index.html

@@ -1,13 +0,0 @@
-<!doctype html>
-<html lang="en" class="dark">
-  <head>
-    <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Mulita - Photo Management</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>

frontend/nginx.conf

@@ -1,43 +0,0 @@
-server {
-    listen 80;
-    server_name localhost;
-    root /usr/share/nginx/html;
-    index index.html;
-
-    # Enable gzip
-    gzip on;
-    gzip_vary on;
-    gzip_min_length 1024;
-    gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;
-
-    # API proxy
-    location /api/ {
-        proxy_pass http://backend:8000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        
-        # WebSocket support for real-time updates
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-    }
-
-    # Thumbnail serving with X-Accel-Redirect
-    location /internal_thumbs/ {
-        internal;
-        alias /data/thumbs/;
-    }
-
-    # SPA routing - serve index.html for all routes
-    location / {
-        try_files $uri $uri/ /index.html;
-    }
-
-    # Cache static assets
-    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
-        expires 1y;
-        add_header Cache-Control "public, immutable";
-    }
-}

frontend/package.json

@@ -1,62 +0,0 @@
-{
-  "name": "mulita-frontend",
-  "private": true,
-  "version": "1.0.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build",
-    "preview": "vite preview",
-    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0"
-  },
-  "dependencies": {
-    "@radix-ui/react-accordion": "^1.1.2",
-    "@radix-ui/react-alert-dialog": "^1.0.5",
-    "@radix-ui/react-checkbox": "^1.0.4",
-    "@radix-ui/react-context-menu": "^2.1.5",
-    "@radix-ui/react-dialog": "^1.0.5",
-    "@radix-ui/react-dropdown-menu": "^2.0.6",
-    "@radix-ui/react-label": "^2.0.2",
-    "@radix-ui/react-popover": "^1.0.7",
-    "@radix-ui/react-scroll-area": "^1.0.5",
-    "@radix-ui/react-select": "^2.0.0",
-    "@radix-ui/react-separator": "^1.0.3",
-    "@radix-ui/react-slider": "^1.1.2",
-    "@radix-ui/react-switch": "^1.0.3",
-    "@radix-ui/react-tabs": "^1.0.4",
-    "@radix-ui/react-toast": "^1.1.5",
-    "@radix-ui/react-tooltip": "^1.0.7",
-    "@tanstack/react-query": "^5.17.0",
-    "@tanstack/react-virtual": "^3.0.1",
-    "axios": "^1.6.5",
-    "clsx": "^2.1.0",
-    "date-fns": "^3.2.0",
-    "framer-motion": "^10.18.0",
-    "leaflet": "^1.9.4",
-    "lucide-react": "^0.303.0",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "react-hotkeys-hook": "^4.4.3",
-    "react-intersection-observer": "^9.5.3",
-    "react-leaflet": "^4.2.1",
-    "tailwind-merge": "^2.2.0",
-    "zustand": "^4.4.7"
-  },
-  "devDependencies": {
-    "@tanstack/react-query-devtools": "^5.96.2",
-    "@types/leaflet": "^1.9.8",
-    "@types/react": "^18.2.46",
-    "@types/react-dom": "^18.2.18",
-    "@typescript-eslint/eslint-plugin": "^6.17.0",
-    "@typescript-eslint/parser": "^6.17.0",
-    "@vitejs/plugin-react": "^4.2.1",
-    "autoprefixer": "^10.4.16",
-    "eslint": "^8.56.0",
-    "eslint-plugin-react-hooks": "^4.6.0",
-    "eslint-plugin-react-refresh": "^0.4.5",
-    "postcss": "^8.4.33",
-    "tailwindcss": "^3.4.0",
-    "typescript": "^5.3.3",
-    "vite": "^5.0.10"
-  }
-}

frontend/postcss.config.js

@@ -1,6 +0,0 @@
-export default {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-}

frontend/src/App.tsx

@@ -1,96 +0,0 @@
-import { useState } from 'react'
-import { Timeline } from './components/timeline/Timeline'
-import { LeftSidebar } from './components/layout/LeftSidebar'
-import { RightSidebar } from './components/layout/RightSidebar'
-import { TopBar } from './components/layout/TopBar'
-import { ScanProgress } from './components/ScanProgress'
-import { ToastContainer } from './components/ToastContainer'
-import { KeyboardHints } from './components/KeyboardHints'
-import { PreviewView } from './components/preview/PreviewView'
-import { FilterBar } from './components/filter/FilterBar'
-import { ActiveFilterChips } from './components/filter/ActiveFilterChips'
-import { DiscardActionBar } from './components/discard/DiscardActionBar'
-import { usePhotoStore } from './store/photoStore'
-import { useKeyboardShortcuts } from './hooks/useKeyboardShortcuts'
-import { useFilterUrlSync } from './hooks/useFilterUrlSync'
-import { usePhotosQuery } from './hooks/usePhotosQuery'
-
-function App() {
-  const [leftSidebarOpen, setLeftSidebarOpen] = useState(true)
-  const [rightSidebarOpen, setRightSidebarOpen] = useState(false)
-  const selectedPhotos = usePhotoStore((state) => state.selectedPhotos)
-  const viewMode = usePhotoStore((state) => state.viewMode)
-
-  // Bidirectional sync of filter store with URL query params.
-  useFilterUrlSync()
-
-  // Subscribe to the same photos query the Timeline uses, so the keyboard
-  // "open preview on first photo" path can read from the live cache regardless
-  // of what filter key it's stored under.
-  const { data: allPhotos } = usePhotosQuery()
-
-  // Set up global keyboard shortcuts
-  useKeyboardShortcuts({
-    onToggleLeftSidebar: () => setLeftSidebarOpen(!leftSidebarOpen),
-    onToggleRightSidebar: () => setRightSidebarOpen(!rightSidebarOpen),
-    getFirstPhotoId: () => allPhotos?.[0]?.id ?? null,
-  })
-
-  // Auto-show right sidebar when photos are selected — but only in grid mode,
-  // so leaving the preview doesn't fight the user's prior sidebar state.
-  if (viewMode === 'grid') {
-    if (selectedPhotos.length > 0 && !rightSidebarOpen) {
-      setRightSidebarOpen(true)
-    } else if (selectedPhotos.length === 0 && rightSidebarOpen) {
-      setRightSidebarOpen(false)
-    }
-  }
-
-  const showRightSidebar = rightSidebarOpen && viewMode === 'grid'
-
-  return (
-    <div className="flex flex-col h-screen bg-bg text-text">
-      <TopBar />
-      <FilterBar />
-      <ActiveFilterChips />
-      <DiscardActionBar />
-      <KeyboardHints />
-
-      <div className="flex flex-1 overflow-hidden">
-        {/* Left Sidebar */}
-        <div
-          className={`transition-all duration-200 ${
-            leftSidebarOpen ? 'w-64' : 'w-0'
-          } overflow-hidden border-r border-border bg-surface`}
-        >
-          <LeftSidebar />
-        </div>
-
-        {/* Main Content - Timeline */}
-        <div className="flex-1 overflow-auto">
-          <Timeline />
-        </div>
-
-        {/* Right Sidebar */}
-        <div
-          className={`transition-all duration-200 ${
-            showRightSidebar ? 'w-80' : 'w-0'
-          } overflow-hidden border-l border-border bg-surface`}
-        >
-          <RightSidebar />
-        </div>
-      </div>
-
-      {/* Scan Progress Indicator */}
-      <ScanProgress />
-
-      {/* Toast Notifications */}
-      <ToastContainer />
-
-      {/* Preview overlay — covers TopBar when active */}
-      {viewMode === 'preview' && <PreviewView />}
-    </div>
-  )
-}
-
-export default App

frontend/src/components/KeyboardHints.tsx

@@ -1,53 +0,0 @@
-import { usePhotoStore } from '../store/photoStore'
-
-export function KeyboardHints() {
-  const selectedCount = usePhotoStore((state) => state.selectedPhotos.length)
-  const viewMode = usePhotoStore((state) => state.viewMode)
-
-  // In preview mode the viewer has its own context, so the grid hints
-  // would just be confusing. Hide them.
-  if (viewMode === 'preview') return null
-
-  const hints = selectedCount > 0
-    ? [
-        { key: '1-5', action: 'Rate' },
-        { key: 'P', action: 'Pick → heap' },
-        { key: 'X', action: 'Discard' },
-        { key: 'Space', action: 'Preview' },
-        { key: 'Esc', action: 'Deselect' },
-      ]
-    : [
-        { key: '↑↓←→', action: 'Navigate' },
-        { key: 'Click', action: 'Select' },
-        { key: 'Shift+Click', action: 'Range' },
-        { key: 'Space', action: 'Preview' },
-        { key: '\\', action: 'Filters' },
-        { key: '/', action: 'Search' },
-      ]
-
-  return (
-    <div className="flex justify-center border-b border-border bg-surface/60 px-4 py-1.5">
-      <div className="flex items-center gap-3">
-        {hints.map((hint, i) => (
-          <div key={i} className="flex items-center gap-1.5">
-            <kbd className="rounded bg-surface-offset px-2 py-0.5 text-[11px] font-medium text-text">
-              {hint.key}
-            </kbd>
-            <span className="text-xs text-text-muted">{hint.action}</span>
-            {i < hints.length - 1 && (
-              <span className="ml-2 text-text-faint">•</span>
-            )}
-          </div>
-        ))}
-        {selectedCount > 0 && (
-          <>
-            <span className="ml-2 text-text-faint">•</span>
-            <span className="text-xs font-medium text-primary">
-              {selectedCount} selected
-            </span>
-          </>
-        )}
-      </div>
-    </div>
-  )
-}

frontend/src/components/ScanProgress.tsx

@@ -1,166 +0,0 @@
-import { useEffect, useState } from 'react'
-import { FolderOpen, Loader2, Check, AlertCircle, X } from 'lucide-react'
-import { useQuery } from '@tanstack/react-query'
-import { library } from '../services/api'
-import clsx from 'clsx'
-
-interface ScanStatus {
-  is_scanning: boolean
-  current_folder?: string
-  processed_files: number
-  total_files: number
-  errors: string[]
-}
-
-export function ScanProgress() {
-  const [isVisible, setIsVisible] = useState(false)
-  const [isMinimized, setIsMinimized] = useState(false)
-
-  // Poll scan status every 2 seconds when scanning
-  const { data: scanStatus } = useQuery<ScanStatus>({
-    queryKey: ['scan-status'],
-    queryFn: async () => {
-      const response = await library.scanStatus()
-      return response
-    },
-    refetchInterval: (query) => {
-      // Poll every 2 seconds if scanning, otherwise every 10 seconds
-      return query.state.data?.is_scanning ? 2000 : 10000
-    },
-    enabled: true,
-  })
-
-  useEffect(() => {
-    if (scanStatus?.is_scanning) {
-      setIsVisible(true)
-      setIsMinimized(false)
-    } else if (isVisible && !scanStatus?.is_scanning && (scanStatus?.processed_files ?? 0) > 0) {
-      // Keep showing for 3 seconds after scan completes
-      setTimeout(() => {
-        if (!scanStatus?.is_scanning) {
-          setIsVisible(false)
-        }
-      }, 3000)
-    }
-  }, [scanStatus?.is_scanning, scanStatus?.processed_files, isVisible])
-
-  if (!isVisible || !scanStatus) return null
-
-  const progress = scanStatus.total_files > 0
-    ? (scanStatus.processed_files / scanStatus.total_files) * 100
-    : 0
-
-  const isComplete = !scanStatus.is_scanning && scanStatus.processed_files > 0
-  const hasErrors = scanStatus.errors && scanStatus.errors.length > 0
-
-  return (
-    <div
-      className={clsx(
-        'fixed bottom-4 right-4 z-40 overflow-hidden rounded-lg border border-border bg-surface shadow-xl transition-all duration-300',
-        isMinimized ? 'w-12' : 'w-80'
-      )}
-    >
-      {/* Header */}
-      <div
-        className="flex cursor-pointer items-center justify-between bg-surface-2 px-3 py-2"
-        onClick={() => setIsMinimized(!isMinimized)}
-      >
-        <div className="flex items-center gap-2">
-          {scanStatus.is_scanning ? (
-            <Loader2 className="h-4 w-4 animate-spin text-primary" />
-          ) : isComplete && !hasErrors ? (
-            <Check className="h-4 w-4 text-pick" />
-          ) : hasErrors ? (
-            <AlertCircle className="h-4 w-4 text-reject" />
-          ) : (
-            <FolderOpen className="h-4 w-4 text-text-muted" />
-          )}
-          {!isMinimized && (
-            <span className="text-sm font-medium text-text">
-              {scanStatus.is_scanning
-                ? 'Scanning Folders'
-                : isComplete
-                ? 'Scan Complete'
-                : 'Scan Status'}
-            </span>
-          )}
-        </div>
-        {!isMinimized && (
-          <button
-            onClick={(e) => {
-              e.stopPropagation()
-              setIsVisible(false)
-            }}
-            className="rounded p-0.5 text-text-muted hover:bg-surface-offset hover:text-text"
-          >
-            <X className="h-3 w-3" />
-          </button>
-        )}
-      </div>
-
-      {/* Content */}
-      {!isMinimized && (
-        <div className="p-3">
-          {/* Current folder */}
-          {scanStatus.current_folder && (
-            <div className="mb-2 text-xs text-text-muted">
-              <span className="font-mono">{scanStatus.current_folder}</span>
-            </div>
-          )}
-
-          {/* Progress bar */}
-          <div className="mb-2">
-            <div className="h-1.5 overflow-hidden rounded-full bg-surface-offset">
-              <div
-                className={clsx(
-                  'h-full transition-all duration-300',
-                  scanStatus.is_scanning
-                    ? 'bg-primary'
-                    : hasErrors
-                    ? 'bg-reject'
-                    : 'bg-pick'
-                )}
-                style={{ width: `${progress}%` }}
-              />
-            </div>
-          </div>
-
-          {/* Stats */}
-          <div className="flex items-center justify-between text-xs">
-            <span className="text-text-muted">
-              {scanStatus.processed_files} / {scanStatus.total_files || '?'} files
-            </span>
-            <span className={clsx(
-              'font-medium',
-              scanStatus.is_scanning ? 'text-primary' : hasErrors ? 'text-reject' : 'text-pick'
-            )}>
-              {scanStatus.is_scanning
-                ? `${Math.round(progress)}%`
-                : isComplete
-                ? 'Done'
-                : 'Idle'}
-            </span>
-          </div>
-
-          {/* Errors */}
-          {hasErrors && (
-            <div className="mt-2 max-h-20 overflow-y-auto rounded bg-reject/10 p-2">
-              <div className="text-xs text-reject">
-                {scanStatus.errors.slice(0, 3).map((error, i) => (
-                  <div key={i} className="truncate">
-                    • {error}
-                  </div>
-                ))}
-                {scanStatus.errors.length > 3 && (
-                  <div className="mt-1 text-text-muted">
-                    +{scanStatus.errors.length - 3} more errors
-                  </div>
-                )}
-              </div>
-            </div>
-          )}
-        </div>
-      )}
-    </div>
-  )
-}

frontend/src/components/ToastContainer.tsx

@@ -1,95 +0,0 @@
-import { useEffect, useState } from 'react'
-import { CheckCircle, XCircle, Info, AlertCircle, X } from 'lucide-react'
-import clsx from 'clsx'
-
-export interface Toast {
-  id: string
-  type: 'success' | 'error' | 'info' | 'warning'
-  title: string
-  message?: string
-  duration?: number
-}
-
-// Global toast state (in production, use Zustand or Context)
-let toastListeners: ((toasts: Toast[]) => void)[] = []
-let toastList: Toast[] = []
-
-export const toast = {
-  success: (title: string, message?: string) => addToast('success', title, message),
-  error: (title: string, message?: string) => addToast('error', title, message),
-  info: (title: string, message?: string) => addToast('info', title, message),
-  warning: (title: string, message?: string) => addToast('warning', title, message),
-}
-
-function addToast(type: Toast['type'], title: string, message?: string, duration = 5000) {
-  const id = Date.now().toString()
-  const newToast: Toast = { id, type, title, message, duration }
-  toastList = [...toastList, newToast]
-  toastListeners.forEach(listener => listener(toastList))
-  
-  // Auto-remove after duration
-  setTimeout(() => {
-    removeToast(id)
-  }, duration)
-}
-
-function removeToast(id: string) {
-  toastList = toastList.filter(t => t.id !== id)
-  toastListeners.forEach(listener => listener(toastList))
-}
-
-export function ToastContainer() {
-  const [toasts, setToasts] = useState<Toast[]>([])
-
-  useEffect(() => {
-    const listener = (newToasts: Toast[]) => setToasts(newToasts)
-    toastListeners.push(listener)
-    return () => {
-      toastListeners = toastListeners.filter(l => l !== listener)
-    }
-  }, [])
-
-  const icons = {
-    success: <CheckCircle className="h-5 w-5 text-pick" />,
-    error: <XCircle className="h-5 w-5 text-reject" />,
-    info: <Info className="h-5 w-5 text-primary" />,
-    warning: <AlertCircle className="h-5 w-5 text-star" />,
-  }
-
-  const colors = {
-    success: 'border-pick bg-pick/10',
-    error: 'border-reject bg-reject/10',
-    info: 'border-primary bg-primary/10',
-    warning: 'border-star bg-star/10',
-  }
-
-  return (
-    <div className="pointer-events-none fixed bottom-4 left-4 z-50 flex flex-col gap-2">
-      {toasts.map((toast) => (
-        <div
-          key={toast.id}
-          className={clsx(
-            'pointer-events-auto flex items-start gap-3 rounded-lg border p-3 shadow-lg backdrop-blur-sm transition-all duration-300',
-            'animate-slide-up',
-            colors[toast.type]
-          )}
-          style={{ minWidth: '300px', maxWidth: '400px' }}
-        >
-          {icons[toast.type]}
-          <div className="flex-1">
-            <div className="font-medium text-text">{toast.title}</div>
-            {toast.message && (
-              <div className="mt-0.5 text-sm text-text-muted">{toast.message}</div>
-            )}
-          </div>
-          <button
-            onClick={() => removeToast(toast.id)}
-            className="pointer-events-auto rounded p-0.5 text-text-muted hover:bg-surface-offset hover:text-text"
-          >
-            <X className="h-4 w-4" />
-          </button>
-        </div>
-      ))}
-    </div>
-  )
-}

frontend/src/components/dialogs/AddSourceFolderDialog.tsx

@@ -1,154 +0,0 @@
-import { useState } from 'react'
-import { X, FolderPlus, AlertCircle } from 'lucide-react'
-import clsx from 'clsx'
-
-interface AddSourceFolderDialogProps {
-  isOpen: boolean
-  onClose: () => void
-  onAdd: (path: string, recursive: boolean) => Promise<void>
-}
-
-export function AddSourceFolderDialog({ isOpen, onClose, onAdd }: AddSourceFolderDialogProps) {
-  const [folderPath, setFolderPath] = useState('')
-  const [recursive, setRecursive] = useState(true)
-  const [isLoading, setIsLoading] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault()
-    
-    if (!folderPath.trim()) {
-      setError('Please enter a folder path')
-      return
-    }
-
-    setIsLoading(true)
-    setError(null)
-
-    try {
-      await onAdd(folderPath.trim(), recursive)
-      setFolderPath('')
-      setRecursive(true)
-      onClose()
-    } catch (err: any) {
-      setError(err.message || 'Failed to add source folder')
-    } finally {
-      setIsLoading(false)
-    }
-  }
-
-  const handleClose = () => {
-    if (!isLoading) {
-      setFolderPath('')
-      setError(null)
-      onClose()
-    }
-  }
-
-  if (!isOpen) return null
-
-  return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center">
-      {/* Backdrop */}
-      <div 
-        className="absolute inset-0 bg-black/60 backdrop-blur-sm"
-        onClick={handleClose}
-      />
-      
-      {/* Dialog */}
-      <div className="relative z-10 w-full max-w-md rounded-lg bg-surface border border-border p-6 shadow-xl">
-        {/* Header */}
-        <div className="mb-4 flex items-center justify-between">
-          <div className="flex items-center gap-2">
-            <FolderPlus className="h-5 w-5 text-primary" />
-            <h2 className="text-lg font-semibold text-text">Add Source Folder</h2>
-          </div>
-          <button
-            onClick={handleClose}
-            disabled={isLoading}
-            className="rounded p-1 text-text-muted hover:bg-surface-2 hover:text-text disabled:opacity-50"
-          >
-            <X className="h-5 w-5" />
-          </button>
-        </div>
-
-        {/* Form */}
-        <form onSubmit={handleSubmit} className="space-y-4">
-          {/* Path Input */}
-          <div>
-            <label htmlFor="folderPath" className="mb-1 block text-sm text-text-muted">
-              Folder Path
-            </label>
-            <input
-              id="folderPath"
-              type="text"
-              value={folderPath}
-              onChange={(e) => setFolderPath(e.target.value)}
-              placeholder="/host/Pictures/your-folder"
-              disabled={isLoading}
-              className={clsx(
-                'w-full rounded border bg-bg px-3 py-2 text-sm text-text placeholder-text-faint',
-                'focus:border-primary focus:outline-none focus:ring-1 focus:ring-primary',
-                'disabled:opacity-50',
-                error ? 'border-reject' : 'border-border'
-              )}
-            />
-            <div className="mt-1 space-y-1">
-              <p className="text-xs text-text-muted">
-                Use container paths. Your Pictures folder is available at:
-              </p>
-              <code className="block text-xs bg-surface-2 px-2 py-1 rounded text-primary">
-                /host/Pictures/
-              </code>
-              <p className="text-xs text-text-faint">
-                Example: /host/Pictures/MulitaTest
-              </p>
-            </div>
-          </div>
-
-          {/* Recursive Checkbox */}
-          <div className="flex items-center gap-2">
-            <input
-              id="recursive"
-              type="checkbox"
-              checked={recursive}
-              onChange={(e) => setRecursive(e.target.checked)}
-              disabled={isLoading}
-              className="h-4 w-4 rounded border-border bg-bg text-primary focus:ring-2 focus:ring-primary focus:ring-offset-0"
-            />
-            <label htmlFor="recursive" className="text-sm text-text">
-              Include subfolders
-            </label>
-          </div>
-
-          {/* Error Message */}
-          {error && (
-            <div className="flex items-center gap-2 rounded bg-reject/10 p-3 text-sm text-reject">
-              <AlertCircle className="h-4 w-4 flex-shrink-0" />
-              <span>{error}</span>
-            </div>
-          )}
-
-          {/* Actions */}
-          <div className="flex justify-end gap-2">
-            <button
-              type="button"
-              onClick={handleClose}
-              disabled={isLoading}
-              className="rounded bg-surface-2 px-4 py-2 text-sm text-text hover:bg-surface-offset disabled:opacity-50"
-            >
-              Cancel
-            </button>
-            <button
-              type="submit"
-              disabled={isLoading || !folderPath.trim()}
-              className="rounded bg-primary px-4 py-2 text-sm text-white hover:bg-primary/90 disabled:opacity-50"
-            >
-              {isLoading ? 'Adding...' : 'Add Folder'}
-            </button>
-          </div>
-        </form>
-      </div>
-    </div>
-  )
-}

frontend/src/components/dialogs/ConfirmDialog.tsx

@@ -1,75 +0,0 @@
-import { useEffect } from 'react'
-import clsx from 'clsx'
-
-interface ConfirmDialogProps {
-  isOpen: boolean
-  title: string
-  message: React.ReactNode
-  confirmLabel?: string
-  cancelLabel?: string
-  /** When true, the confirm button uses the destructive accent. */
-  destructive?: boolean
-  onConfirm: () => void
-  onClose: () => void
-}
-
-/**
- * Tiny modal-confirmation dialog. Mirrors the AddSourceFolderDialog overlay
- * pattern (custom fixed inset-0 backdrop, no shadcn Dialog dep). Esc closes.
- */
-export function ConfirmDialog({
-  isOpen,
-  title,
-  message,
-  confirmLabel = 'Confirm',
-  cancelLabel = 'Cancel',
-  destructive = false,
-  onConfirm,
-  onClose,
-}: ConfirmDialogProps) {
-  // Esc to close.
-  useEffect(() => {
-    if (!isOpen) return
-    const handler = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') onClose()
-    }
-    window.addEventListener('keydown', handler)
-    return () => window.removeEventListener('keydown', handler)
-  }, [isOpen, onClose])
-
-  if (!isOpen) return null
-
-  return (
-    <div className="fixed inset-0 z-50">
-      <div
-        className="absolute inset-0 bg-black/60 backdrop-blur-sm"
-        onClick={onClose}
-      />
-      <div className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2">
-        <div className="relative z-10 w-96 rounded-lg border border-border bg-surface p-5 shadow-2xl">
-          <h2 className="mb-2 text-base font-semibold text-text">{title}</h2>
-          <div className="mb-4 text-sm text-text-muted">{message}</div>
-          <div className="flex justify-end gap-2">
-            <button
-              onClick={onClose}
-              className="rounded border border-border px-3 py-1.5 text-sm text-text hover:bg-surface-2"
-            >
-              {cancelLabel}
-            </button>
-            <button
-              onClick={onConfirm}
-              className={clsx(
-                'rounded px-3 py-1.5 text-sm font-medium text-white',
-                destructive
-                  ? 'bg-reject hover:bg-reject/80'
-                  : 'bg-primary hover:bg-primary/80'
-              )}
-            >
-              {confirmLabel}
-            </button>
-          </div>
-        </div>
-      </div>
-    </div>
-  )
-}

frontend/src/components/discard/DiscardActionBar.tsx

@@ -1,112 +0,0 @@
-import { useState } from 'react'
-import { RotateCcw, Trash2 } from 'lucide-react'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { usePhotoStore } from '../../store/photoStore'
-import { useFilterStore } from '../../store/filterStore'
-import { usePhotosQuery } from '../../hooks/usePhotosQuery'
-import { discard as discardApi } from '../../services/api'
-import { toast } from '../ToastContainer'
-import { ConfirmDialog } from '../dialogs/ConfirmDialog'
-
-/**
- * Top-of-timeline bar visible only when the discarded filter is active.
- * Shows a count, lets the user restore the current selection, and lets them
- * permanently empty the discard pile (with confirmation).
- */
-export function DiscardActionBar() {
-  const flag = useFilterStore((s) => s.flag)
-  const selectedPhotos = usePhotoStore((s) => s.selectedPhotos)
-  const clearSelection = usePhotoStore((s) => s.clearSelection)
-  const queryClient = useQueryClient()
-  const { data: photos = [] } = usePhotosQuery()
-
-  const [confirmOpen, setConfirmOpen] = useState(false)
-
-  const restoreMutation = useMutation({
-    mutationFn: (ids: string[]) => discardApi.restore(ids),
-    onSuccess: (_, ids) => {
-      toast.success('Restored', `${ids.length} photo${ids.length > 1 ? 's' : ''} restored`)
-      clearSelection()
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-    },
-    onError: (e: any) => toast.error('Restore failed', e.message || 'Unknown error'),
-  })
-
-  const emptyMutation = useMutation({
-    mutationFn: () => discardApi.empty(),
-    onSuccess: (data: any) => {
-      const count = data?.deleted ?? 0
-      const errors = data?.file_errors ?? 0
-      if (errors > 0) {
-        toast.error(
-          `Emptied with ${errors} error${errors > 1 ? 's' : ''}`,
-          `${count} record${count > 1 ? 's' : ''} deleted; some files could not be removed`
-        )
-      } else {
-        toast.success('Discard pile emptied', `${count} photo${count > 1 ? 's' : ''} permanently deleted`)
-      }
-      clearSelection()
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      setConfirmOpen(false)
-    },
-    onError: (e: any) => toast.error('Empty failed', e.message || 'Unknown error'),
-  })
-
-  if (flag !== 'discarded') return null
-
-  const total = photos.length
-  const selected = selectedPhotos.length
-
-  return (
-    <>
-      <div className="flex items-center justify-between gap-3 border-b border-border bg-reject/10 px-4 py-2 text-sm">
-        <div className="flex items-center gap-2 text-text">
-          <Trash2 className="h-4 w-4 text-reject" />
-          <span className="font-medium">Discarded</span>
-          <span className="text-text-muted">
-            {total} photo{total === 1 ? '' : 's'}
-          </span>
-        </div>
-
-        <div className="flex items-center gap-2">
-          {selected > 0 && (
-            <button
-              onClick={() => restoreMutation.mutate(selectedPhotos)}
-              disabled={restoreMutation.isPending}
-              className="flex items-center gap-1.5 rounded bg-surface-2 px-3 py-1 text-text hover:bg-surface-offset disabled:opacity-50"
-              title="Restore selected (U)"
-            >
-              <RotateCcw className="h-3.5 w-3.5" />
-              Restore {selected}
-            </button>
-          )}
-          <button
-            onClick={() => setConfirmOpen(true)}
-            disabled={total === 0 || emptyMutation.isPending}
-            className="flex items-center gap-1.5 rounded bg-reject/20 px-3 py-1 text-reject hover:bg-reject/30 disabled:opacity-50"
-            title="Permanently delete all discarded photos and files"
-          >
-            <Trash2 className="h-3.5 w-3.5" />
-            Empty discard pile
-          </button>
-        </div>
-      </div>
-
-      <ConfirmDialog
-        isOpen={confirmOpen}
-        title="Empty discard pile?"
-        message={
-          <>
-            This will <strong className="text-text">permanently delete</strong>{' '}
-            {total} photo{total === 1 ? '' : 's'} and remove the file
-            {total === 1 ? '' : 's'} from disk. This cannot be undone.
-          </>
-        }
-        confirmLabel="Empty pile"
-        destructive
-        onConfirm={() => emptyMutation.mutate()}
-        onClose={() => setConfirmOpen(false)}
-      />
-    </>
-  )
-}

frontend/src/components/filter/ActiveFilterChips.tsx

@@ -1,115 +0,0 @@
-import { X } from 'lucide-react'
-import { useQuery } from '@tanstack/react-query'
-import { useFilterStore, hasActiveFilters } from '../../store/filterStore'
-import { sourceFolders, heaps as heapsApi } from '../../services/api'
-
-export function ActiveFilterChips() {
-  const f = useFilterStore()
-
-  // Look up names for id-based filters so the chips show something
-  // human-readable instead of opaque uuids.
-  const { data: foldersData } = useQuery({
-    queryKey: ['folders'],
-    queryFn: sourceFolders.list,
-    enabled: f.folderId !== null,
-  })
-  const folder = f.folderId
-    ? (foldersData?.folders ?? []).find((x: any) => x.id === f.folderId)
-    : null
-
-  const { data: heaps = [] } = useQuery({
-    queryKey: ['heaps'],
-    queryFn: heapsApi.list,
-    enabled: f.heapId !== null,
-  })
-  const heap = f.heapId ? heaps.find((h) => h.id === f.heapId) : null
-
-  if (!hasActiveFilters(f)) return null
-
-  const chips: { key: string; label: string; onRemove: () => void }[] = []
-
-  if (f.q.trim()) {
-    chips.push({
-      key: 'q',
-      label: `Search: "${f.q.trim()}"`,
-      onRemove: () => f.setQ(''),
-    })
-  }
-  if (f.dateFrom) {
-    chips.push({
-      key: 'dateFrom',
-      label: `From: ${f.dateFrom}`,
-      onRemove: () => f.setDateFrom(null),
-    })
-  }
-  if (f.dateTo) {
-    chips.push({
-      key: 'dateTo',
-      label: `To: ${f.dateTo}`,
-      onRemove: () => f.setDateTo(null),
-    })
-  }
-  for (const t of f.mediaTypes) {
-    chips.push({
-      key: `mt-${t}`,
-      label: t.toUpperCase(),
-      onRemove: () => f.toggleMediaType(t),
-    })
-  }
-  if (f.ratingMin > 0) {
-    chips.push({
-      key: 'rating',
-      label: `Rating ≥ ${f.ratingMin}★`,
-      onRemove: () => f.setRatingMin(0),
-    })
-  }
-  if (f.colorLabel) {
-    chips.push({
-      key: 'color',
-      label: f.colorLabel,
-      onRemove: () => f.setColorLabel(null),
-    })
-  }
-  if (f.flag !== 'any') {
-    chips.push({
-      key: 'flag',
-      label: f.flag,
-      onRemove: () => f.setFlag('any'),
-    })
-  }
-  if (f.folderId) {
-    chips.push({
-      key: 'folder',
-      label: `Folder: ${folder?.name || folder?.path?.split('/').pop() || f.folderId}`,
-      onRemove: () => f.setFolderId(null),
-    })
-  }
-  if (f.heapId) {
-    chips.push({
-      key: 'heap',
-      label: `Heap: ${heap?.name ?? f.heapId}`,
-      onRemove: () => f.setHeapId(null),
-    })
-  }
-
-  return (
-    <div className="flex flex-wrap items-center gap-2 border-b border-border bg-surface-2 px-4 py-2 text-xs">
-      <span className="text-text-muted">Active filters:</span>
-      {chips.map((chip) => (
-        <span
-          key={chip.key}
-          className="flex items-center gap-1 rounded bg-primary/20 px-2 py-0.5 text-primary"
-        >
-          {chip.label}
-          <button
-            onClick={chip.onRemove}
-            className="rounded p-0.5 hover:bg-primary/30"
-            title="Remove"
-          >
-            <X className="h-3 w-3" />
-          </button>
-        </span>
-      ))}
-    </div>
-  )
-}

frontend/src/components/filter/FilterBar.tsx

@@ -1,222 +0,0 @@
-import { Star, X, ArrowDown, ArrowUp } from 'lucide-react'
-import clsx from 'clsx'
-import {
-  useFilterStore,
-  type MediaType,
-  type ColorLabel,
-  type FlagFilter,
-  type SortField,
-} from '../../store/filterStore'
-
-const MEDIA_TYPES: { value: MediaType; label: string }[] = [
-  { value: 'photo', label: 'Photo' },
-  { value: 'video', label: 'Video' },
-  { value: 'raw', label: 'RAW' },
-  { value: 'heic', label: 'HEIC' },
-]
-
-const COLOR_LABELS: { value: ColorLabel; className: string }[] = [
-  { value: 'red', className: 'bg-red-500' },
-  { value: 'orange', className: 'bg-orange-500' },
-  { value: 'yellow', className: 'bg-yellow-400' },
-  { value: 'green', className: 'bg-green-500' },
-  { value: 'blue', className: 'bg-blue-500' },
-  { value: 'purple', className: 'bg-purple-500' },
-]
-
-const FLAG_OPTIONS: { value: FlagFilter; label: string }[] = [
-  { value: 'any', label: 'Any' },
-  { value: 'discarded', label: 'Discarded' },
-]
-
-const SORT_OPTIONS: { value: SortField; label: string }[] = [
-  { value: 'taken_at', label: 'Date taken' },
-  { value: 'added_at', label: 'Date added' },
-  { value: 'filename', label: 'Filename' },
-  { value: 'file_size', label: 'File size' },
-  { value: 'rating', label: 'Rating' },
-]
-
-export function FilterBar() {
-  const filterBarOpen = useFilterStore((s) => s.filterBarOpen)
-  const dateFrom = useFilterStore((s) => s.dateFrom)
-  const dateTo = useFilterStore((s) => s.dateTo)
-  const mediaTypes = useFilterStore((s) => s.mediaTypes)
-  const ratingMin = useFilterStore((s) => s.ratingMin)
-  const colorLabel = useFilterStore((s) => s.colorLabel)
-  const flag = useFilterStore((s) => s.flag)
-  const sortBy = useFilterStore((s) => s.sortBy)
-  const sortOrder = useFilterStore((s) => s.sortOrder)
-
-  const setDateFrom = useFilterStore((s) => s.setDateFrom)
-  const setDateTo = useFilterStore((s) => s.setDateTo)
-  const toggleMediaType = useFilterStore((s) => s.toggleMediaType)
-  const setRatingMin = useFilterStore((s) => s.setRatingMin)
-  const setColorLabel = useFilterStore((s) => s.setColorLabel)
-  const setFlag = useFilterStore((s) => s.setFlag)
-  const setSortBy = useFilterStore((s) => s.setSortBy)
-  const toggleSortOrder = useFilterStore((s) => s.toggleSortOrder)
-  const clearAll = useFilterStore((s) => s.clearAll)
-
-  if (!filterBarOpen) return null
-
-  return (
-    <div className="flex flex-wrap items-center gap-x-6 gap-y-3 border-b border-border bg-surface px-4 py-3 text-xs">
-      {/* Date range */}
-      <Group label="Date">
-        <input
-          type="date"
-          value={dateFrom ?? ''}
-          onChange={(e) => setDateFrom(e.target.value || null)}
-          className="rounded border border-border bg-bg px-2 py-1 text-xs text-text"
-        />
-        <span className="text-text-muted">→</span>
-        <input
-          type="date"
-          value={dateTo ?? ''}
-          onChange={(e) => setDateTo(e.target.value || null)}
-          className="rounded border border-border bg-bg px-2 py-1 text-xs text-text"
-        />
-      </Group>
-
-      {/* Media type chips */}
-      <Group label="Type">
-        {MEDIA_TYPES.map(({ value, label }) => {
-          const active = mediaTypes.includes(value)
-          return (
-            <button
-              key={value}
-              onClick={() => toggleMediaType(value)}
-              className={clsx(
-                'rounded px-2 py-1 transition-colors',
-                active
-                  ? 'bg-primary text-white'
-                  : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-              )}
-            >
-              {label}
-            </button>
-          )
-        })}
-      </Group>
-
-      {/* Min rating */}
-      <Group label="Rating ≥">
-        {[1, 2, 3, 4, 5].map((n) => (
-          <button
-            key={n}
-            onClick={() => setRatingMin(ratingMin === n ? 0 : n)}
-            className="p-0.5"
-            title={`At least ${n} star${n > 1 ? 's' : ''}`}
-          >
-            <Star
-              className={clsx(
-                'h-4 w-4 transition-colors',
-                n <= ratingMin
-                  ? 'fill-star text-star'
-                  : 'text-text-muted hover:text-star'
-              )}
-            />
-          </button>
-        ))}
-      </Group>
-
-      {/* Color label dots */}
-      <Group label="Color">
-        {COLOR_LABELS.map(({ value, className }) => {
-          const active = colorLabel === value
-          return (
-            <button
-              key={value}
-              onClick={() => setColorLabel(active ? null : value)}
-              className={clsx(
-                'h-4 w-4 rounded-full ring-offset-1 ring-offset-surface transition-all',
-                className,
-                active ? 'ring-2 ring-primary' : 'opacity-60 hover:opacity-100'
-              )}
-              title={value}
-            />
-          )
-        })}
-        {colorLabel && (
-          <button
-            onClick={() => setColorLabel(null)}
-            className="ml-1 text-text-muted hover:text-text"
-            title="Clear color"
-          >
-            <X className="h-3 w-3" />
-          </button>
-        )}
-      </Group>
-
-      {/* Flag */}
-      <Group label="Flag">
-        {FLAG_OPTIONS.map(({ value, label }) => {
-          const active = flag === value
-          return (
-            <button
-              key={value}
-              onClick={() => setFlag(value)}
-              className={clsx(
-                'rounded px-2 py-1 transition-colors',
-                active
-                  ? 'bg-primary text-white'
-                  : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-              )}
-            >
-              {label}
-            </button>
-          )
-        })}
-      </Group>
-
-      {/* Sort */}
-      <Group label="Sort">
-        <select
-          value={sortBy}
-          onChange={(e) => setSortBy(e.target.value as SortField)}
-          className="rounded border border-border bg-bg px-2 py-1 text-xs text-text focus:border-primary focus:outline-none"
-        >
-          {SORT_OPTIONS.map((opt) => (
-            <option key={opt.value} value={opt.value}>
-              {opt.label}
-            </option>
-          ))}
-        </select>
-        <button
-          onClick={toggleSortOrder}
-          className="rounded bg-surface-2 p-1 text-text-muted hover:bg-surface-offset hover:text-text"
-          title={sortOrder === 'desc' ? 'Descending (click for ascending)' : 'Ascending (click for descending)'}
-        >
-          {sortOrder === 'desc' ? (
-            <ArrowDown className="h-3.5 w-3.5" />
-          ) : (
-            <ArrowUp className="h-3.5 w-3.5" />
-          )}
-        </button>
-      </Group>
-
-      <button
-        onClick={clearAll}
-        className="ml-auto rounded border border-border px-2 py-1 text-text-muted hover:bg-surface-2 hover:text-text"
-      >
-        Clear all
-      </button>
-    </div>
-  )
-}
-
-function Group({
-  label,
-  children,
-}: {
-  label: string
-  children: React.ReactNode
-}) {
-  return (
-    <div className="flex items-center gap-1.5">
-      <span className="text-text-muted">{label}:</span>
-      {children}
-    </div>
-  )
-}

frontend/src/components/heaps/HeapsPanel.tsx

@@ -1,299 +0,0 @@
-import { useState } from 'react'
-import {
-  ShoppingBasket,
-  Plus,
-  Target,
-  X,
-  ChevronDown,
-  ChevronRight,
-} from 'lucide-react'
-import clsx from 'clsx'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { useHeapsQuery, HEAPS_QUERY_KEY } from '../../hooks/useHeapsQuery'
-import { heaps as heapsApi } from '../../services/api'
-import { useFilterStore } from '../../store/filterStore'
-import { toast } from '../ToastContainer'
-import { PHOTO_DRAG_MIME } from '../timeline/PhotoThumbnail'
-
-/**
- * Heaps panel for the left sidebar. Renders the list of heaps with the
- * basket icon, lets the user create a new heap, click one to filter the
- * timeline to its contents, set one as the "active" target for the T
- * shortcut, and delete heaps.
- *
- * Heap state:
- *  - filter heapId: which heap is currently filtered to (visual)
- *  - heap.is_active: which heap T adds to (server-side, single per row)
- */
-export function HeapsPanel() {
-  const { data: heaps = [] } = useHeapsQuery()
-  const filterHeapId = useFilterStore((s) => s.heapId)
-  const setFilterHeapId = useFilterStore((s) => s.setHeapId)
-  const queryClient = useQueryClient()
-
-  const [expanded, setExpanded] = useState(true)
-  const [creating, setCreating] = useState(false)
-  const [newName, setNewName] = useState('')
-  // Which heap row is currently being hovered with a drag — used to render
-  // the drop highlight ring. Only one heap can be the target at a time.
-  const [dropTargetId, setDropTargetId] = useState<string | null>(null)
-
-  const invalidate = () => {
-    queryClient.invalidateQueries({ queryKey: HEAPS_QUERY_KEY })
-  }
-
-  const createMutation = useMutation({
-    mutationFn: (name: string) => heapsApi.create(name),
-    onSuccess: () => {
-      invalidate()
-      setNewName('')
-      setCreating(false)
-    },
-    onError: (e: any) =>
-      toast.error('Failed to create heap', e.message || 'Unknown error'),
-  })
-
-  const setActiveMutation = useMutation({
-    mutationFn: (heapId: string) =>
-      heapsApi.update(heapId, { is_active: true }),
-    onSuccess: (heap) => {
-      invalidate()
-      toast.success('Active heap', `Now adding to "${heap.name}" with T`)
-    },
-    onError: (e: any) =>
-      toast.error('Failed to set active', e.message || 'Unknown error'),
-  })
-
-  const deleteMutation = useMutation({
-    mutationFn: (heapId: string) => heapsApi.delete(heapId),
-    onSuccess: (_, heapId) => {
-      invalidate()
-      // If we were filtering by this heap, clear the filter
-      if (filterHeapId === heapId) setFilterHeapId(null)
-    },
-    onError: (e: any) =>
-      toast.error('Failed to delete heap', e.message || 'Unknown error'),
-  })
-
-  // Drop handler: add the dragged photos to the target heap. Optimistically
-  // updates the membership cache so the basket affordance flips immediately,
-  // mirroring the keyboard P-toggle pattern.
-  const dropMutation = useMutation({
-    mutationFn: ({ heapId, photoIds }: { heapId: string; photoIds: string[] }) =>
-      heapsApi.addPhotos(heapId, photoIds),
-    onMutate: ({ heapId, photoIds }) => {
-      const key = ['heap-photo-ids', heapId] as const
-      const previous = queryClient.getQueryData<string[]>(key)
-      const set = new Set(previous ?? [])
-      photoIds.forEach((id) => set.add(id))
-      queryClient.setQueryData<string[]>(key, Array.from(set))
-      return { previous }
-    },
-    onError: (e: any, vars, ctx) => {
-      if (ctx?.previous) {
-        queryClient.setQueryData(['heap-photo-ids', vars.heapId], ctx.previous)
-      }
-      toast.error('Failed to add to heap', e.message || 'Unknown error')
-    },
-    onSuccess: (data, vars) => {
-      const heap = heaps.find((h) => h.id === vars.heapId)
-      const heapName = heap?.name ?? 'heap'
-      const added = data?.added ?? 0
-      const already = data?.already_present ?? 0
-      if (added > 0) {
-        toast.success(
-          `Added to ${heapName}`,
-          `${added} photo${added > 1 ? 's' : ''}${already > 0 ? ` (${already} already present)` : ''}`
-        )
-      } else if (already > 0) {
-        toast.info(`Already in ${heapName}`, `${already} photo${already > 1 ? 's' : ''}`)
-      }
-    },
-    onSettled: (_d, _e, vars) => {
-      queryClient.invalidateQueries({ queryKey: HEAPS_QUERY_KEY })
-      queryClient.invalidateQueries({ queryKey: ['heap-photo-ids', vars.heapId] })
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-    },
-  })
-
-  const handleCreate = () => {
-    const name = newName.trim()
-    if (!name) return
-    createMutation.mutate(name)
-  }
-
-  return (
-    <div>
-      {/* Section header */}
-      <div
-        className="group flex cursor-pointer items-center gap-1 rounded px-2 py-1 text-sm text-text hover:bg-surface-2"
-        onClick={() => setExpanded((v) => !v)}
-      >
-        <button className="rounded p-0.5 hover:bg-surface-offset">
-          {expanded ? (
-            <ChevronDown className="h-3 w-3" />
-          ) : (
-            <ChevronRight className="h-3 w-3" />
-          )}
-        </button>
-        <ShoppingBasket className="h-4 w-4 text-text-muted" />
-        <span className="flex-1 truncate">Heaps</span>
-        <button
-          onClick={(e) => {
-            e.stopPropagation()
-            setCreating(true)
-            setExpanded(true)
-          }}
-          className="invisible rounded p-0.5 text-text-muted hover:bg-surface-offset hover:text-text group-hover:visible"
-          title="New heap"
-        >
-          <Plus className="h-3 w-3" />
-        </button>
-      </div>
-
-      {expanded && (
-        <div>
-          {/* Inline create form */}
-          {creating && (
-            <div
-              className="flex items-center gap-1 px-2 py-1"
-              style={{ paddingLeft: '32px' }}
-            >
-              <input
-                autoFocus
-                type="text"
-                value={newName}
-                onChange={(e) => setNewName(e.target.value)}
-                onKeyDown={(e) => {
-                  if (e.key === 'Enter') handleCreate()
-                  if (e.key === 'Escape') {
-                    setCreating(false)
-                    setNewName('')
-                  }
-                }}
-                placeholder="Heap name"
-                className="flex-1 rounded border border-border bg-bg px-2 py-0.5 text-xs text-text focus:border-primary focus:outline-none"
-              />
-              <button
-                onClick={handleCreate}
-                disabled={!newName.trim() || createMutation.isPending}
-                className="rounded bg-primary px-2 py-0.5 text-xs text-white hover:bg-primary/80 disabled:opacity-50"
-              >
-                Add
-              </button>
-            </div>
-          )}
-
-          {heaps.length === 0 && !creating && (
-            <div
-              className="px-2 py-1 text-xs text-text-faint"
-              style={{ paddingLeft: '32px' }}
-            >
-              No heaps yet
-            </div>
-          )}
-
-          {heaps.map((heap) => {
-            const isFiltered = filterHeapId === heap.id
-            const isActive = heap.is_active
-            const isDropTarget = dropTargetId === heap.id
-            return (
-              <div
-                key={heap.id}
-                className={clsx(
-                  'group flex cursor-pointer items-center gap-1 rounded px-2 py-1 text-[13px]',
-                  isFiltered ? 'bg-primary/20 text-primary' : 'text-text hover:bg-surface-2',
-                  isDropTarget && 'ring-2 ring-primary bg-primary/10'
-                )}
-                style={{ paddingLeft: '32px' }}
-                onClick={() => setFilterHeapId(heap.id)}
-                onDragOver={(e) => {
-                  if (e.dataTransfer.types.includes(PHOTO_DRAG_MIME)) {
-                    e.preventDefault()
-                    e.dataTransfer.dropEffect = 'copy'
-                    if (dropTargetId !== heap.id) setDropTargetId(heap.id)
-                  }
-                }}
-                onDragLeave={(e) => {
-                  // Only clear if we're actually leaving this row, not just
-                  // moving over a child element.
-                  if (!e.currentTarget.contains(e.relatedTarget as Node)) {
-                    if (dropTargetId === heap.id) setDropTargetId(null)
-                  }
-                }}
-                onDrop={(e) => {
-                  e.preventDefault()
-                  setDropTargetId(null)
-                  const raw = e.dataTransfer.getData(PHOTO_DRAG_MIME)
-                  if (!raw) return
-                  try {
-                    const ids = JSON.parse(raw) as string[]
-                    if (Array.isArray(ids) && ids.length > 0) {
-                      dropMutation.mutate({ heapId: heap.id, photoIds: ids })
-                    }
-                  } catch {
-                    // Bad payload — ignore.
-                  }
-                }}
-              >
-                <ShoppingBasket
-                  className={clsx(
-                    'h-4 w-4 flex-shrink-0',
-                    isFiltered ? 'text-primary' : 'text-text-muted'
-                  )}
-                />
-                <span
-                  className={clsx(
-                    'flex-1 truncate',
-                    isActive && 'font-semibold'
-                  )}
-                  title={heap.name}
-                >
-                  {heap.name}
-                </span>
-                {isActive && (
-                  <Target
-                    className="h-3 w-3 text-primary"
-                    aria-label="Active heap (T target)"
-                  />
-                )}
-                {heap.photo_count > 0 && (
-                  <span className="rounded bg-surface-offset px-1.5 py-0.5 text-xs text-text-muted">
-                    {heap.photo_count}
-                  </span>
-                )}
-                <button
-                  onClick={(e) => {
-                    e.stopPropagation()
-                    if (!isActive) setActiveMutation.mutate(heap.id)
-                  }}
-                  className={clsx(
-                    'rounded p-0.5 hover:bg-surface-offset hover:text-text',
-                    isActive
-                      ? 'invisible'
-                      : 'invisible text-text-muted group-hover:visible'
-                  )}
-                  title="Set as active heap (T target)"
-                >
-                  <Target className="h-3 w-3" />
-                </button>
-                <button
-                  onClick={(e) => {
-                    e.stopPropagation()
-                    if (confirm(`Delete heap "${heap.name}"? Photos are not affected.`)) {
-                      deleteMutation.mutate(heap.id)
-                    }
-                  }}
-                  className="invisible rounded p-0.5 text-text-muted hover:bg-surface-offset hover:text-reject group-hover:visible"
-                  title="Delete heap"
-                >
-                  <X className="h-3 w-3" />
-                </button>
-              </div>
-            )
-          })}
-        </div>
-      )}
-    </div>
-  )
-}

frontend/src/components/layout/LeftSidebar.tsx

@@ -1,306 +0,0 @@
-import { useState } from 'react'
-import {
-  ChevronRight,
-  ChevronDown,
-  Folder,
-  Image,
-  Calendar,
-  Star,
-  Trash2,
-  Plus,
-  MoreHorizontal,
-  HardDrive,
-  RefreshCw,
-} from 'lucide-react'
-import clsx from 'clsx'
-import { AddSourceFolderDialog } from '../dialogs/AddSourceFolderDialog'
-import { sourceFolders, library } from '../../services/api'
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-import { toast } from '../ToastContainer'
-import { useFilterStore } from '../../store/filterStore'
-import { HeapsPanel } from '../heaps/HeapsPanel'
-
-interface TreeItem {
-  id: string
-  label: string
-  icon?: React.ReactNode
-  count?: number
-  children?: TreeItem[]
-  type?: 'folder' | 'heap' | 'special'
-}
-
-export function LeftSidebar() {
-  const [expandedItems, setExpandedItems] = useState<Set<string>>(new Set(['library', 'folders', 'heaps']))
-  const [selectedItem, setSelectedItem] = useState<string | null>('all-photos')
-  const [showAddFolderDialog, setShowAddFolderDialog] = useState(false)
-  const [isScanning, setIsScanning] = useState(false)
-
-  const queryClient = useQueryClient()
-  const clearAllFilters = useFilterStore((s) => s.clearAll)
-  const setRatingMin = useFilterStore((s) => s.setRatingMin)
-  const setFlag = useFilterStore((s) => s.setFlag)
-  const setFolderId = useFilterStore((s) => s.setFolderId)
-  const filterFolderId = useFilterStore((s) => s.folderId)
-
-  // Map a library tree id to a filter-store mutation. Each "virtual node" in
-  // the library tree is just a saved filter preset.
-  const applyLibraryNode = (id: string) => {
-    switch (id) {
-      case 'all-photos':
-        clearAllFilters()
-        break
-      case 'rated':
-        clearAllFilters()
-        setRatingMin(1)
-        break
-      case 'discarded':
-        clearAllFilters()
-        setFlag('discarded')
-        break
-      default:
-        if (id.startsWith('folder-')) {
-          // Folder rows: filter to that folder, clear other filters that
-          // would compete (heap, discarded, etc.) so the user sees what they
-          // expect when they click a folder.
-          const folderId = id.slice('folder-'.length)
-          clearAllFilters()
-          setFolderId(folderId)
-        }
-        // 'by-date' is still visual-only.
-    }
-  }
-  
-  // Fetch folders from API
-  const { data: foldersData, refetch: refetchFolders } = useQuery({
-    queryKey: ['folders'],
-    queryFn: sourceFolders.list,
-  })
-  
-  // Mutation for adding folders
-  const addFolderMutation = useMutation({
-    mutationFn: async ({ path, recursive }: { path: string; recursive: boolean }) => {
-      // Add the folder
-      const folder = await sourceFolders.add(path, recursive)
-      // Trigger scan for the new folder
-      await sourceFolders.scan(folder.id)
-      return folder
-    },
-    onSuccess: (folder) => {
-      toast.success('Folder Added', `Scanning ${folder.name || folder.path}...`)
-      // Refetch folders list
-      refetchFolders()
-      // Refetch photos to show new ones
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-    },
-    onError: (error: any) => {
-      toast.error('Failed to Add Folder', error.message || 'An error occurred')
-    },
-  })
-  
-  // Mutation for scanning all folders
-  const scanLibraryMutation = useMutation({
-    mutationFn: library.scan,
-    onMutate: () => {
-      setIsScanning(true)
-      toast.info('Scan Started', 'Scanning all folders for new photos...')
-    },
-    onSuccess: () => {
-      toast.success('Scan Complete', 'All folders have been scanned')
-    },
-    onError: (error: any) => {
-      toast.error('Scan Failed', error.message || 'Failed to scan folders')
-    },
-    onSettled: () => {
-      setIsScanning(false)
-      // Refetch photos after scan
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-    },
-  })
-  
-  const handleAddFolder = async (path: string, recursive: boolean) => {
-    await addFolderMutation.mutateAsync({ path, recursive })
-  }
-  
-  const handleScanAll = () => {
-    scanLibraryMutation.mutate()
-  }
-  
-  const toggleExpanded = (id: string) => {
-    const newExpanded = new Set(expandedItems)
-    if (newExpanded.has(id)) {
-      newExpanded.delete(id)
-    } else {
-      newExpanded.add(id)
-    }
-    setExpandedItems(newExpanded)
-  }
-  
-  const libraryTree: TreeItem[] = [
-    {
-      id: 'library',
-      label: 'Library',
-      icon: <HardDrive className="h-4 w-4" />,
-      children: [
-        { id: 'all-photos', label: 'All Photos', icon: <Image className="h-4 w-4" />, count: 0 },
-        { id: 'by-date', label: 'By Date', icon: <Calendar className="h-4 w-4" /> },
-        { id: 'rated', label: 'Rated', icon: <Star className="h-4 w-4" />, count: 0 },
-        { id: 'discarded', label: 'Discarded', icon: <Trash2 className="h-4 w-4" />, count: 0 },
-      ],
-    },
-    {
-      id: 'folders',
-      label: 'Folders',
-      icon: <Folder className="h-4 w-4" />,
-      children: foldersData?.folders?.map((folder: any) => ({
-        id: `folder-${folder.id}`,
-        label: folder.name || folder.path.split('/').pop() || folder.path,
-        icon: <Folder className="h-4 w-4" />,
-        count: folder.photo_count,
-        type: 'folder',
-      })) || [],
-    },
-  ]
-  
-  // Derive whether a tree item is currently the "active" filter target.
-  // Folder rows are selected when the filter store's folderId matches; the
-  // library "All Photos" virtual node is selected when no folder/heap filter
-  // is set.
-  const isItemActive = (id: string): boolean => {
-    if (id.startsWith('folder-')) {
-      return filterFolderId === id.slice('folder-'.length)
-    }
-    if (id === 'all-photos') {
-      return filterFolderId === null && selectedItem === 'all-photos'
-    }
-    return selectedItem === id
-  }
-
-  const renderTreeItem = (item: TreeItem, depth: number = 0) => {
-    const hasChildren = item.children && item.children.length > 0
-    const isExpanded = expandedItems.has(item.id)
-    const isSelected = isItemActive(item.id)
-    
-    return (
-      <div key={item.id}>
-        <div
-          className={clsx(
-            'group flex cursor-pointer items-center gap-1 rounded px-2 py-1 text-sm',
-            isSelected ? 'bg-primary/20 text-primary' : 'text-text hover:bg-surface-2',
-            depth > 0 && 'text-[13px]'
-          )}
-          style={{ paddingLeft: `${8 + depth * 16}px` }}
-          onClick={() => {
-            setSelectedItem(item.id)
-            if (hasChildren) {
-              toggleExpanded(item.id)
-            } else {
-              applyLibraryNode(item.id)
-            }
-          }}
-        >
-          {/* Expand/Collapse Icon */}
-          {hasChildren ? (
-            <button
-              onClick={(e) => {
-                e.stopPropagation()
-                toggleExpanded(item.id)
-              }}
-              className="rounded p-0.5 hover:bg-surface-offset"
-            >
-              {isExpanded ? (
-                <ChevronDown className="h-3 w-3" />
-              ) : (
-                <ChevronRight className="h-3 w-3" />
-              )}
-            </button>
-          ) : (
-            <div className="w-4" />
-          )}
-          
-          {/* Item Icon */}
-          {item.icon && (
-            <span className={clsx('flex-shrink-0', isSelected ? 'text-primary' : 'text-text-muted')}>
-              {item.icon}
-            </span>
-          )}
-          
-          {/* Label */}
-          <span className="flex-1 truncate">{item.label}</span>
-          
-          {/* Count Badge */}
-          {item.count !== undefined && item.count > 0 && (
-            <span className="rounded bg-surface-offset px-1.5 py-0.5 text-xs text-text-muted">
-              {item.count}
-            </span>
-          )}
-          
-          {/* Actions (shown on hover) */}
-          {(item.id === 'folders' || item.id === 'heaps') && (
-            <button
-              onClick={(e) => {
-                e.stopPropagation()
-                // Handle add folder/heap
-              }}
-              className="invisible rounded p-0.5 text-text-muted hover:bg-surface-offset hover:text-text group-hover:visible"
-            >
-              <Plus className="h-3 w-3" />
-            </button>
-          )}
-        </div>
-        
-        {/* Render Children */}
-        {hasChildren && isExpanded && (
-          <div>
-            {item.children!.map((child) => renderTreeItem(child, depth + 1))}
-          </div>
-        )}
-      </div>
-    )
-  }
-  
-  return (
-    <div className="flex h-full flex-col bg-surface">
-      {/* Sidebar Header */}
-      <div className="flex items-center justify-between border-b border-border px-3 py-2">
-        <h2 className="text-sm font-semibold text-text">Library</h2>
-        <button className="rounded p-1 text-text-muted hover:bg-surface-2 hover:text-text">
-          <MoreHorizontal className="h-4 w-4" />
-        </button>
-      </div>
-      
-      {/* Tree View */}
-      <div className="flex-1 overflow-y-auto py-2">
-        {libraryTree.map((item) => renderTreeItem(item))}
-        <HeapsPanel />
-      </div>
-      
-      {/* Bottom Actions */}
-      <div className="border-t border-border p-3 space-y-2">
-        <button 
-          onClick={() => setShowAddFolderDialog(true)}
-          className="flex w-full items-center gap-2 rounded bg-surface-2 px-3 py-2 text-sm text-text hover:bg-surface-offset"
-        >
-          <Plus className="h-4 w-4" />
-          Add Source Folder
-        </button>
-        {foldersData?.folders?.length > 0 && (
-          <button 
-            onClick={handleScanAll}
-            disabled={isScanning}
-            className="flex w-full items-center gap-2 rounded bg-surface-2 px-3 py-2 text-sm text-text hover:bg-surface-offset disabled:opacity-50"
-          >
-            <RefreshCw className={clsx("h-4 w-4", isScanning && "animate-spin")} />
-            {isScanning ? 'Scanning...' : 'Scan All Folders'}
-          </button>
-        )}
-      </div>
-      
-      {/* Add Source Folder Dialog */}
-      <AddSourceFolderDialog
-        isOpen={showAddFolderDialog}
-        onClose={() => setShowAddFolderDialog(false)}
-        onAdd={handleAddFolder}
-      />
-    </div>
-  )
-}

frontend/src/components/layout/RightSidebar.tsx

@@ -1,584 +0,0 @@
-import { useState, useMemo, useEffect } from 'react'
-import {
-  X,
-  Star,
-  MapPin,
-  Camera,
-  Aperture,
-  Info,
-  ChevronDown,
-  ChevronRight,
-  ShoppingBasket,
-  Trash2,
-} from 'lucide-react'
-import clsx from 'clsx'
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-import { format } from 'date-fns'
-import { usePhotoStore } from '../../store/photoStore'
-import { photos as photosApi, heaps as heapsApi } from '../../services/api'
-import { useActiveHeapMembers } from '../../hooks/useActiveHeapMembersQuery'
-import { HEAPS_QUERY_KEY } from '../../hooks/useHeapsQuery'
-import { toast } from '../ToastContainer'
-
-interface PhotoDetails {
-  id: string
-  filename: string
-  filepath: string
-  width: number | null
-  height: number | null
-  file_size: number | null
-  taken_at: string | null
-  rating: number
-  is_discarded: boolean
-  user_title: string | null
-  user_notes: string | null
-  color_label: string | null
-  exif_json: string | null
-}
-
-type ColorLabel = 'red' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple'
-
-const COLOR_LABEL_OPTIONS: { value: ColorLabel; className: string }[] = [
-  { value: 'red', className: 'bg-red-500' },
-  { value: 'orange', className: 'bg-orange-500' },
-  { value: 'yellow', className: 'bg-yellow-400' },
-  { value: 'green', className: 'bg-green-500' },
-  { value: 'blue', className: 'bg-blue-500' },
-  { value: 'purple', className: 'bg-purple-500' },
-]
-
-interface ExifData {
-  Make?: string
-  Model?: string
-  LensModel?: string
-  Lens?: string
-  ISO?: number | string
-  FNumber?: number | string
-  ApertureValue?: number | string
-  ExposureTime?: string
-  ShutterSpeedValue?: string
-  FocalLength?: string
-  FocalLengthIn35mmFormat?: string
-  GPSLatitude?: number | string
-  GPSLongitude?: number | string
-  [key: string]: unknown
-}
-
-function formatFileSize(bytes: number | null): string {
-  if (bytes == null) return '—'
-  if (bytes < 1024) return `${bytes} B`
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
-  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`
-  return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`
-}
-
-function formatExifValue(v: unknown): string {
-  if (v == null || v === '') return '—'
-  return String(v)
-}
-
-function pickFirst(exif: ExifData, ...keys: string[]): string {
-  for (const k of keys) {
-    const v = exif[k]
-    if (v != null && v !== '') return String(v)
-  }
-  return '—'
-}
-
-function parseExif(json: string | null): ExifData {
-  if (!json) return {}
-  try {
-    const parsed = JSON.parse(json)
-    return typeof parsed === 'object' && parsed !== null ? (parsed as ExifData) : {}
-  } catch {
-    return {}
-  }
-}
-
-export function RightSidebar() {
-  const { selectedPhotos, activePhotoId, clearSelection } = usePhotoStore()
-  const queryClient = useQueryClient()
-
-  const [expandedSections, setExpandedSections] = useState<Set<string>>(
-    new Set(['basic', 'camera', 'location'])
-  )
-
-  const toggleSection = (section: string) => {
-    const newExpanded = new Set(expandedSections)
-    if (newExpanded.has(section)) newExpanded.delete(section)
-    else newExpanded.add(section)
-    setExpandedSections(newExpanded)
-  }
-
-  // Fetch the active photo's full record (with EXIF) on demand.
-  const { data: photo } = useQuery<PhotoDetails>({
-    queryKey: ['photo', activePhotoId],
-    queryFn: () => photosApi.get(activePhotoId!),
-    enabled: !!activePhotoId,
-    staleTime: 60_000,
-  })
-
-  // Mutation for any patchable field on the active photo. Invalidates both
-  // the photo detail cache and the timeline list so the grid reflects the
-  // change too.
-  const updateMutation = useMutation({
-    mutationFn: (data: {
-      filename?: string
-      rating?: number
-      is_discarded?: boolean
-      user_title?: string | null
-      user_notes?: string | null
-      color_label?: string | null
-    }) => photosApi.update(activePhotoId!, data),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['photo', activePhotoId] })
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-    },
-  })
-
-  // Membership in the active heap (for the Pick toggle button).
-  const { activeHeap, memberIds: activeHeapMembers } = useActiveHeapMembers()
-  const isInActiveHeap =
-    !!activePhotoId && activeHeapMembers.has(activePhotoId)
-
-  const heapMutation = useMutation({
-    mutationFn: ({ remove }: { remove: boolean }) => {
-      if (!activeHeap || !activePhotoId) return Promise.resolve(null)
-      return remove
-        ? heapsApi.removePhotos(activeHeap.id, [activePhotoId])
-        : heapsApi.addPhotos(activeHeap.id, [activePhotoId])
-    },
-    // Optimistic flip so the badge / button label update instantly.
-    onMutate: ({ remove }) => {
-      if (!activeHeap || !activePhotoId) return { previous: undefined }
-      const key = ['heap-photo-ids', activeHeap.id] as const
-      const previous = queryClient.getQueryData<string[]>(key)
-      const set = new Set(previous ?? [])
-      if (remove) set.delete(activePhotoId)
-      else set.add(activePhotoId)
-      queryClient.setQueryData<string[]>(key, Array.from(set))
-      return { previous }
-    },
-    onError: (_e, _vars, ctx) => {
-      if (activeHeap && ctx?.previous) {
-        queryClient.setQueryData(['heap-photo-ids', activeHeap.id], ctx.previous)
-      }
-    },
-    onSettled: () => {
-      queryClient.invalidateQueries({ queryKey: HEAPS_QUERY_KEY })
-      if (activeHeap) {
-        queryClient.invalidateQueries({
-          queryKey: ['heap-photo-ids', activeHeap.id],
-        })
-      }
-    },
-  })
-
-  // Local drafts for the editable text fields. These mirror the server value
-  // but stay independent while the user is typing, so we don't fight focus or
-  // clobber edits with stale refetches.
-  const [filenameDraft, setFilenameDraft] = useState('')
-  const [titleDraft, setTitleDraft] = useState('')
-  const [notesDraft, setNotesDraft] = useState('')
-
-  useEffect(() => {
-    setFilenameDraft(photo?.filename ?? '')
-    setTitleDraft(photo?.user_title ?? '')
-    setNotesDraft(photo?.user_notes ?? '')
-  }, [photo?.id, photo?.filename, photo?.user_title, photo?.user_notes])
-
-  const commitFilename = () => {
-    const next = filenameDraft.trim()
-    const current = photo?.filename ?? ''
-    if (!next || next === current) {
-      // Reset draft if user cleared it; we never send an empty filename.
-      setFilenameDraft(current)
-      return
-    }
-    if (next.includes('/') || next.includes('\\') || next === '.' || next === '..') {
-      toast.error('Invalid filename', 'No path separators allowed')
-      setFilenameDraft(current)
-      return
-    }
-    updateMutation.mutate(
-      { filename: next },
-      {
-        onError: (e: any) => {
-          toast.error(
-            'Rename failed',
-            e?.response?.data?.detail || e.message || 'Unknown error'
-          )
-          setFilenameDraft(current)
-        },
-      }
-    )
-  }
-
-  const commitTitle = () => {
-    const next = titleDraft.trim()
-    const current = photo?.user_title ?? ''
-    if (next === current) return
-    updateMutation.mutate({ user_title: next || null })
-  }
-
-  const commitNotes = () => {
-    const next = notesDraft
-    const current = photo?.user_notes ?? ''
-    if (next === current) return
-    updateMutation.mutate({ user_notes: next || null })
-  }
-
-  const setColor = (label: ColorLabel | null) => {
-    updateMutation.mutate({ color_label: label })
-  }
-
-  const exif = useMemo(() => parseExif(photo?.exif_json ?? null), [photo?.exif_json])
-
-  if (selectedPhotos.length === 0) {
-    return (
-      <div className="flex h-full items-center justify-center p-4 text-center">
-        <div className="text-text-muted">
-          <Info className="mx-auto mb-2 h-8 w-8" />
-          <p className="text-sm">Select photos to view details</p>
-        </div>
-      </div>
-    )
-  }
-
-  const multipleSelected = selectedPhotos.length > 1
-  const rating = photo?.rating ?? 0
-  const isDiscarded = photo?.is_discarded ?? false
-  const colorLabel = (photo?.color_label ?? null) as ColorLabel | null
-
-  return (
-    <div className="flex h-full flex-col bg-surface">
-      {/* Header */}
-      <div className="flex items-center justify-between border-b border-border px-4 py-3">
-        <h2 className="text-sm font-semibold text-text">
-          {multipleSelected
-            ? `${selectedPhotos.length} Photos Selected`
-            : 'Photo Details'}
-        </h2>
-        <button
-          onClick={clearSelection}
-          className="rounded p-1 text-text-muted hover:bg-surface-2 hover:text-text"
-          title="Clear selection"
-        >
-          <X className="h-4 w-4" />
-        </button>
-      </div>
-
-      {/* Quick Actions — operate on the active photo */}
-      {photo && !multipleSelected && (
-        <div className="space-y-3 border-b border-border p-4">
-          {/* Filename (editable, renames the file on disk) */}
-          <div>
-            <label className="mb-1 block text-xs text-text-muted">Filename</label>
-            <input
-              type="text"
-              value={filenameDraft}
-              onChange={(e) => setFilenameDraft(e.target.value)}
-              onBlur={commitFilename}
-              onKeyDown={(e) => {
-                if (e.key === 'Enter') {
-                  e.currentTarget.blur()
-                } else if (e.key === 'Escape') {
-                  setFilenameDraft(photo.filename ?? '')
-                  e.currentTarget.blur()
-                }
-              }}
-              className="w-full rounded border border-border bg-bg px-2 py-1 font-mono text-xs text-text focus:border-primary focus:outline-none"
-            />
-          </div>
-
-          {/* Title (editable) */}
-          <div>
-            <label className="mb-1 block text-xs text-text-muted">Title</label>
-            <input
-              type="text"
-              value={titleDraft}
-              onChange={(e) => setTitleDraft(e.target.value)}
-              onBlur={commitTitle}
-              onKeyDown={(e) => {
-                if (e.key === 'Enter') {
-                  e.currentTarget.blur()
-                } else if (e.key === 'Escape') {
-                  setTitleDraft(photo.user_title ?? '')
-                  e.currentTarget.blur()
-                }
-              }}
-              placeholder="No title"
-              className="w-full rounded border border-border bg-bg px-2 py-1 text-sm text-text placeholder-text-faint focus:border-primary focus:outline-none"
-            />
-          </div>
-
-          {/* Notes (editable) */}
-          <div>
-            <label className="mb-1 block text-xs text-text-muted">Notes</label>
-            <textarea
-              value={notesDraft}
-              onChange={(e) => setNotesDraft(e.target.value)}
-              onBlur={commitNotes}
-              placeholder="Add notes…"
-              rows={3}
-              className="w-full resize-none rounded border border-border bg-bg px-2 py-1 text-sm text-text placeholder-text-faint focus:border-primary focus:outline-none"
-            />
-          </div>
-
-          {/* Rating */}
-          <div>
-            <label className="mb-1 block text-xs text-text-muted">Rating</label>
-            <div className="flex gap-1">
-              {[1, 2, 3, 4, 5].map((value) => (
-                <button
-                  key={value}
-                  onClick={() =>
-                    updateMutation.mutate({ rating: rating === value ? 0 : value })
-                  }
-                  className="p-0.5"
-                  title={`Set rating to ${value}`}
-                >
-                  <Star
-                    className={clsx(
-                      'h-5 w-5 transition-colors',
-                      value <= rating
-                        ? 'fill-star text-star'
-                        : 'text-text-muted hover:text-star'
-                    )}
-                  />
-                </button>
-              ))}
-            </div>
-          </div>
-
-          {/* Color label */}
-          <div>
-            <label className="mb-1 block text-xs text-text-muted">Color label</label>
-            <div className="flex items-center gap-1.5">
-              {COLOR_LABEL_OPTIONS.map(({ value, className }) => {
-                const active = colorLabel === value
-                return (
-                  <button
-                    key={value}
-                    onClick={() => setColor(active ? null : value)}
-                    className={clsx(
-                      'h-5 w-5 rounded-full ring-offset-2 ring-offset-surface transition-all',
-                      className,
-                      active ? 'ring-2 ring-primary' : 'opacity-60 hover:opacity-100'
-                    )}
-                    title={value}
-                  />
-                )
-              })}
-              {colorLabel && (
-                <button
-                  onClick={() => setColor(null)}
-                  className="ml-1 rounded p-0.5 text-text-muted hover:bg-surface-2 hover:text-text"
-                  title="Clear color label"
-                >
-                  <X className="h-3 w-3" />
-                </button>
-              )}
-            </div>
-          </div>
-
-          {/* Flag */}
-          <div>
-            <label className="mb-1 block text-xs text-text-muted">Flag</label>
-            <div className="flex gap-2">
-              <button
-                onClick={() => heapMutation.mutate({ remove: isInActiveHeap })}
-                disabled={!activeHeap || heapMutation.isPending}
-                className={clsx(
-                  'flex items-center gap-1 rounded px-2 py-1 text-sm transition-colors disabled:cursor-not-allowed disabled:opacity-50',
-                  isInActiveHeap
-                    ? 'bg-pick/20 text-pick'
-                    : 'bg-surface-2 text-text-muted hover:bg-surface-offset'
-                )}
-                title={
-                  activeHeap
-                    ? isInActiveHeap
-                      ? `Remove from "${activeHeap.name}"`
-                      : `Add to "${activeHeap.name}"`
-                    : 'Set an active heap first'
-                }
-              >
-                <ShoppingBasket className="h-3 w-3" />
-                {isInActiveHeap ? 'Picked' : 'Pick'}
-              </button>
-              <button
-                onClick={() =>
-                  updateMutation.mutate({ is_discarded: !isDiscarded })
-                }
-                className={clsx(
-                  'flex items-center gap-1 rounded px-2 py-1 text-sm transition-colors',
-                  isDiscarded
-                    ? 'bg-reject/20 text-reject'
-                    : 'bg-surface-2 text-text-muted hover:bg-surface-offset'
-                )}
-              >
-                <Trash2 className="h-3 w-3" />
-                Discard
-              </button>
-            </div>
-          </div>
-        </div>
-      )}
-
-      {/* Metadata */}
-      <div className="flex-1 overflow-y-auto">
-        {photo && !multipleSelected && (
-          <>
-            {/* Basic Info */}
-            <Section
-              title="Basic Info"
-              expanded={expandedSections.has('basic')}
-              onToggle={() => toggleSection('basic')}
-            >
-              <div className="grid grid-cols-2 gap-2 text-xs">
-                <Field label="Size" value={formatFileSize(photo.file_size)} />
-                <Field
-                  label="Dimensions"
-                  value={
-                    photo.width && photo.height
-                      ? `${photo.width} × ${photo.height}`
-                      : '—'
-                  }
-                />
-                <Field
-                  label="Date Taken"
-                  value={
-                    photo.taken_at
-                      ? format(new Date(photo.taken_at), 'MMM d, yyyy HH:mm')
-                      : '—'
-                  }
-                />
-              </div>
-            </Section>
-
-            {/* Camera */}
-            <Section
-              title="Camera"
-              expanded={expandedSections.has('camera')}
-              onToggle={() => toggleSection('camera')}
-            >
-              <div className="space-y-1 text-xs">
-                <div className="flex items-center gap-2">
-                  <Camera className="h-3 w-3 text-text-muted" />
-                  <span className="text-text">
-                    {pickFirst(exif, 'Make', 'Model') === '—'
-                      ? '—'
-                      : `${formatExifValue(exif.Make)} ${formatExifValue(exif.Model)}`.trim()}
-                  </span>
-                </div>
-                <div className="flex items-center gap-2">
-                  <Aperture className="h-3 w-3 text-text-muted" />
-                  <span className="text-text">
-                    {pickFirst(exif, 'LensModel', 'Lens')}
-                  </span>
-                </div>
-                <div className="mt-2 grid grid-cols-2 gap-2">
-                  <Field label="ISO" value={formatExifValue(exif.ISO)} />
-                  <Field
-                    label="Aperture"
-                    value={
-                      exif.FNumber
-                        ? `f/${exif.FNumber}`
-                        : pickFirst(exif, 'ApertureValue')
-                    }
-                  />
-                  <Field
-                    label="Shutter"
-                    value={pickFirst(exif, 'ExposureTime', 'ShutterSpeedValue')}
-                  />
-                  <Field
-                    label="Focal"
-                    value={pickFirst(
-                      exif,
-                      'FocalLength',
-                      'FocalLengthIn35mmFormat'
-                    )}
-                  />
-                </div>
-              </div>
-            </Section>
-
-            {/* Location */}
-            <Section
-              title="Location"
-              expanded={expandedSections.has('location')}
-              onToggle={() => toggleSection('location')}
-            >
-              {exif.GPSLatitude && exif.GPSLongitude ? (
-                <div className="flex items-center gap-2 text-xs">
-                  <MapPin className="h-3 w-3 text-text-muted" />
-                  <span className="font-mono text-text">
-                    {String(exif.GPSLatitude)}, {String(exif.GPSLongitude)}
-                  </span>
-                </div>
-              ) : (
-                <div className="text-xs text-text-muted">No GPS data</div>
-              )}
-            </Section>
-          </>
-        )}
-
-        {!photo && !multipleSelected && (
-          <div className="p-4 text-xs text-text-muted">Loading…</div>
-        )}
-      </div>
-
-      {/* Footer Actions for multi-select */}
-      {multipleSelected && (
-        <div className="border-t border-border p-3">
-          <div className="space-y-2">
-            <button className="w-full rounded bg-surface-2 px-3 py-1.5 text-sm text-text hover:bg-surface-offset">
-              Add to Heap
-            </button>
-            <button className="w-full rounded bg-surface-2 px-3 py-1.5 text-sm text-text hover:bg-surface-offset">
-              Export Selected
-            </button>
-          </div>
-        </div>
-      )}
-    </div>
-  )
-}
-
-function Section({
-  title,
-  expanded,
-  onToggle,
-  children,
-}: {
-  title: string
-  expanded: boolean
-  onToggle: () => void
-  children: React.ReactNode
-}) {
-  return (
-    <div className="border-b border-border">
-      <button
-        onClick={onToggle}
-        className="flex w-full items-center justify-between px-4 py-2 text-sm hover:bg-surface-2"
-      >
-        <span className="font-medium text-text">{title}</span>
-        {expanded ? (
-          <ChevronDown className="h-4 w-4 text-text-muted" />
-        ) : (
-          <ChevronRight className="h-4 w-4 text-text-muted" />
-        )}
-      </button>
-      {expanded && <div className="px-4 pb-3">{children}</div>}
-    </div>
-  )
-}
-
-function Field({ label, value }: { label: string; value: string }) {
-  return (
-    <div>
-      <span className="text-text-muted">{label}:</span>
-      <p className="break-words text-text">{value}</p>
-    </div>
-  )
-}

frontend/src/components/layout/TopBar.tsx

@@ -1,194 +0,0 @@
-import { useState, useEffect, useRef } from 'react'
-import {
-  Search,
-  Grid,
-  List,
-  SlidersHorizontal,
-  FolderOpen,
-  Upload,
-  Settings,
-  Menu,
-  X,
-  ShoppingBasket,
-} from 'lucide-react'
-import clsx from 'clsx'
-import { useFilterStore, hasActiveFilters } from '../../store/filterStore'
-import { useHeapsQuery } from '../../hooks/useHeapsQuery'
-import muliLogo from '../../assets/muli-logo.png'
-
-const SEARCH_DEBOUNCE_MS = 300
-
-export function TopBar() {
-  // Filter store is the source of truth for search; the input has a local
-  // mirror so typing stays responsive while we debounce store updates.
-  const storeQ = useFilterStore((s) => s.q)
-  const setStoreQ = useFilterStore((s) => s.setQ)
-  const filterBarOpen = useFilterStore((s) => s.filterBarOpen)
-  const toggleFilterBar = useFilterStore((s) => s.toggleFilterBar)
-  const filterState = useFilterStore()
-  const filtersActive = hasActiveFilters(filterState) || filterBarOpen
-
-  const [searchQuery, setSearchQuery] = useState(storeQ)
-
-  // Keep local input in sync if the store is changed externally (URL hydrate,
-  // active-chip removal, clear-all).
-  useEffect(() => {
-    setSearchQuery(storeQ)
-  }, [storeQ])
-
-  // Debounce local input -> store.
-  const debounceRef = useRef<number | null>(null)
-  useEffect(() => {
-    if (searchQuery === storeQ) return
-    if (debounceRef.current) window.clearTimeout(debounceRef.current)
-    debounceRef.current = window.setTimeout(() => {
-      setStoreQ(searchQuery)
-    }, SEARCH_DEBOUNCE_MS)
-    return () => {
-      if (debounceRef.current) window.clearTimeout(debounceRef.current)
-    }
-  }, [searchQuery, storeQ, setStoreQ])
-
-  const [viewMode, setViewMode] = useState<'grid' | 'list'>('grid')
-
-  // Currently active heap. Shown as a pill so the user always knows where
-  // their next P-press will land.
-  const { data: heapsList = [] } = useHeapsQuery()
-  const activeHeap = heapsList.find((h) => h.is_active)
-
-  return (
-    <header className="flex h-12 items-center justify-between border-b border-border bg-surface px-4">
-      {/* Left Section - Menu and App Name */}
-      <div className="flex items-center gap-3">
-        <button
-          className="group relative rounded p-1 text-text-muted hover:bg-surface-2 hover:text-text"
-          title="Toggle sidebar (Tab)"
-        >
-          <Menu className="h-5 w-5" />
-          <kbd className="absolute -bottom-5 left-1/2 -translate-x-1/2 rounded bg-surface-offset px-1 py-0.5 text-[9px] font-medium text-text opacity-0 group-hover:opacity-100">
-            Tab
-          </kbd>
-        </button>
-        <div className="flex items-center gap-2">
-          <img src={muliLogo} alt="Mulita" className="h-7 w-7 object-contain" />
-          <h1 className="text-lg font-semibold text-text">Mulita</h1>
-        </div>
-        {activeHeap && (
-          <span
-            className="flex items-center gap-1 rounded bg-primary/20 px-2 py-0.5 text-xs text-primary"
-            title="Active heap — press P to add selected photos here"
-          >
-            <ShoppingBasket className="h-3 w-3" />
-            {activeHeap.name}
-          </span>
-        )}
-      </div>
-      
-      {/* Center Section - Search */}
-      <div className="flex max-w-xl flex-1 items-center px-8">
-        <div className="relative w-full">
-          <Search className="absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-text-muted" />
-          <input
-            id="topbar-search"
-            type="text"
-            value={searchQuery}
-            onChange={(e) => setSearchQuery(e.target.value)}
-            onKeyDown={(e) => {
-              if (e.key === 'Escape') {
-                setSearchQuery('')
-                setStoreQ('')
-                e.currentTarget.blur()
-              }
-            }}
-            placeholder="Search photos..."
-            className="w-full rounded-md border border-border bg-bg py-1.5 pl-9 pr-9 text-sm text-text placeholder-text-muted focus:border-primary focus:outline-none"
-          />
-          {searchQuery && (
-            <button
-              onClick={() => {
-                setSearchQuery('')
-                setStoreQ('')
-              }}
-              className="absolute right-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-text-muted hover:bg-surface-2 hover:text-text"
-              title="Clear search"
-            >
-              <X className="h-3.5 w-3.5" />
-            </button>
-          )}
-        </div>
-      </div>
-      
-      {/* Right Section - View Controls and Actions */}
-      <div className="flex items-center gap-2">
-        {/* View Mode Toggle */}
-        <div className="flex rounded-md border border-border">
-          <button
-            className={clsx(
-              'rounded-l-md px-2 py-1',
-              viewMode === 'grid' 
-                ? 'bg-primary text-white' 
-                : 'bg-surface text-text-muted hover:bg-surface-2'
-            )}
-            onClick={() => setViewMode('grid')}
-            title="Grid view"
-          >
-            <Grid className="h-4 w-4" />
-          </button>
-          <button
-            className={clsx(
-              'rounded-r-md px-2 py-1',
-              viewMode === 'list' 
-                ? 'bg-primary text-white' 
-                : 'bg-surface text-text-muted hover:bg-surface-2'
-            )}
-            onClick={() => setViewMode('list')}
-            title="List view"
-          >
-            <List className="h-4 w-4" />
-          </button>
-        </div>
-        
-        {/* Filter Button */}
-        <button
-          onClick={toggleFilterBar}
-          className={clsx(
-            'group relative rounded p-1.5 transition-colors',
-            filtersActive
-              ? 'bg-primary/20 text-primary'
-              : 'text-text-muted hover:bg-surface-2 hover:text-text'
-          )}
-          title="Toggle filters (\\)"
-        >
-          <SlidersHorizontal className="h-4 w-4" />
-          <kbd className="absolute -bottom-5 left-1/2 -translate-x-1/2 whitespace-nowrap rounded bg-surface-offset px-1 py-0.5 text-[9px] font-medium text-text opacity-0 group-hover:opacity-100">
-            \
-          </kbd>
-        </button>
-        
-        <div className="mx-1 h-6 w-px bg-border" />
-        
-        {/* Action Buttons */}
-        <button
-          className="rounded p-1.5 text-text-muted hover:bg-surface-2 hover:text-text"
-          title="Add folder"
-        >
-          <FolderOpen className="h-4 w-4" />
-        </button>
-        
-        <button
-          className="rounded p-1.5 text-text-muted hover:bg-surface-2 hover:text-text"
-          title="Import photos"
-        >
-          <Upload className="h-4 w-4" />
-        </button>
-        
-        <button
-          className="rounded p-1.5 text-text-muted hover:bg-surface-2 hover:text-text"
-          title="Settings"
-        >
-          <Settings className="h-4 w-4" />
-        </button>
-      </div>
-    </header>
-  )
-}

frontend/src/components/preview/PreviewFilmstrip.tsx

@@ -1,55 +0,0 @@
-import { useEffect, useRef } from 'react'
-import clsx from 'clsx'
-import type { Photo } from '../../types/photo'
-import { photos as photosApi } from '../../services/api'
-
-interface PreviewFilmstripProps {
-  photos: Photo[]
-  currentIndex: number
-  onSelect: (id: string) => void
-}
-
-const CELL_SIZE = 72
-
-export function PreviewFilmstrip({ photos, currentIndex, onSelect }: PreviewFilmstripProps) {
-  const activeRef = useRef<HTMLButtonElement>(null)
-
-  useEffect(() => {
-    activeRef.current?.scrollIntoView({
-      block: 'nearest',
-      inline: 'center',
-      behavior: 'smooth',
-    })
-  }, [currentIndex])
-
-  return (
-    <div className="flex h-24 shrink-0 items-center gap-1 overflow-x-auto border-t border-border bg-surface px-2 py-2">
-      {photos.map((photo, index) => {
-        const isActive = index === currentIndex
-        return (
-          <button
-            key={photo.id}
-            ref={isActive ? activeRef : null}
-            onClick={() => onSelect(photo.id)}
-            className={clsx(
-              'shrink-0 overflow-hidden rounded-sm transition-all',
-              'hover:opacity-100',
-              isActive
-                ? 'ring-2 ring-primary opacity-100'
-                : 'opacity-60'
-            )}
-            style={{ width: CELL_SIZE, height: CELL_SIZE }}
-            title={photo.filename}
-          >
-            <img
-              src={photosApi.getThumbnailUrl(photo.id, 'small')}
-              alt={photo.filename}
-              loading="lazy"
-              className="h-full w-full object-cover"
-            />
-          </button>
-        )
-      })}
-    </div>
-  )
-}

frontend/src/components/preview/PreviewImage.tsx

@@ -1,178 +0,0 @@
-import { useState, useEffect, useRef, useCallback } from 'react'
-import { useHotkeys } from 'react-hotkeys-hook'
-import type { Photo } from '../../types/photo'
-import {
-  getPreviewImageSrc,
-  getPreviewFallbackSrc,
-  getVideoSrc,
-  isVideo,
-} from './previewSrc'
-
-interface PreviewImageProps {
-  photo: Photo
-}
-
-const MIN_SCALE = 1
-const MAX_SCALE = 8
-const WHEEL_STEP = 1.15
-
-export function PreviewImage({ photo }: PreviewImageProps) {
-  if (isVideo(photo)) {
-    return <PreviewVideo photo={photo} />
-  }
-  return <PreviewStillImage photo={photo} />
-}
-
-function PreviewVideo({ photo }: { photo: Photo }) {
-  return (
-    <div className="flex flex-1 items-center justify-center bg-black">
-      <video
-        key={photo.id}
-        src={getVideoSrc(photo)}
-        controls
-        autoPlay
-        muted
-        className="max-h-full max-w-full"
-      />
-    </div>
-  )
-}
-
-function PreviewStillImage({ photo }: { photo: Photo }) {
-  const [loaded, setLoaded] = useState(false)
-  const [usingFallback, setUsingFallback] = useState(false)
-
-  // scale=1 means "fit to viewport". Anything >1 zooms in; we don't allow <1
-  // because the fit size already fills the viewport.
-  const [scale, setScale] = useState(1)
-  const [offset, setOffset] = useState({ x: 0, y: 0 })
-  const dragStateRef = useRef<{ x: number; y: number; ox: number; oy: number } | null>(null)
-  const imgRef = useRef<HTMLImageElement>(null)
-
-  // Reset everything when the photo changes.
-  useEffect(() => {
-    setLoaded(false)
-    setUsingFallback(false)
-    setScale(1)
-    setOffset({ x: 0, y: 0 })
-  }, [photo.id])
-
-  const primarySrc = getPreviewImageSrc(photo)
-  const fallbackSrc = getPreviewFallbackSrc(photo)
-  const src = usingFallback ? fallbackSrc : primarySrc
-
-  const handleError = () => {
-    if (!usingFallback && primarySrc !== fallbackSrc) {
-      setUsingFallback(true)
-    }
-  }
-
-  // Z key: toggle between fit (scale=1) and actual size (natural/displayed).
-  // If we're already zoomed (manual wheel zoom), Z snaps back to fit.
-  const toggleZoom = useCallback(() => {
-    if (scale !== 1) {
-      setScale(1)
-      setOffset({ x: 0, y: 0 })
-      return
-    }
-    const img = imgRef.current
-    if (!img) return
-    const ratio = img.naturalWidth / img.clientWidth
-    if (!isFinite(ratio) || ratio <= 1) return
-    setScale(Math.min(ratio, MAX_SCALE))
-  }, [scale])
-
-  useHotkeys(
-    'z',
-    (e) => {
-      e.preventDefault()
-      toggleZoom()
-    },
-    { preventDefault: true },
-    [toggleZoom]
-  )
-
-  const handleWheel = (e: React.WheelEvent) => {
-    e.preventDefault()
-    const delta = e.deltaY < 0 ? WHEEL_STEP : 1 / WHEEL_STEP
-    setScale((prev) => {
-      const next = Math.min(MAX_SCALE, Math.max(MIN_SCALE, prev * delta))
-      // Snapping back to 1 also resets pan offset.
-      if (next === 1) setOffset({ x: 0, y: 0 })
-      return next
-    })
-  }
-
-  const handleMouseDown = (e: React.MouseEvent) => {
-    if (scale === 1) return
-    e.preventDefault()
-    dragStateRef.current = {
-      x: e.clientX,
-      y: e.clientY,
-      ox: offset.x,
-      oy: offset.y,
-    }
-  }
-
-  const handleMouseMove = (e: React.MouseEvent) => {
-    const drag = dragStateRef.current
-    if (!drag) return
-    setOffset({
-      x: drag.ox + (e.clientX - drag.x),
-      y: drag.oy + (e.clientY - drag.y),
-    })
-  }
-
-  const endDrag = () => {
-    dragStateRef.current = null
-  }
-
-  const isZoomed = scale > 1
-  const cursor = isZoomed
-    ? dragStateRef.current
-      ? 'grabbing'
-      : 'grab'
-    : 'zoom-in'
-
-  return (
-    <div
-      className="relative flex flex-1 select-none items-center justify-center overflow-hidden bg-black"
-      onWheel={handleWheel}
-      onMouseDown={handleMouseDown}
-      onMouseMove={handleMouseMove}
-      onMouseUp={endDrag}
-      onMouseLeave={endDrag}
-      style={{ cursor }}
-    >
-      <img
-        ref={imgRef}
-        key={`${photo.id}-${usingFallback}`}
-        src={src}
-        alt={photo.filename}
-        loading="eager"
-        decoding="async"
-        draggable={false}
-        onLoad={() => setLoaded(true)}
-        onError={handleError}
-        className="max-h-full max-w-full object-contain"
-        style={{
-          transform: `translate(${offset.x}px, ${offset.y}px) scale(${scale})`,
-          transformOrigin: 'center center',
-          willChange: 'transform',
-        }}
-      />
-      {!loaded && (
-        <div className="pointer-events-none absolute inset-0 flex items-center justify-center text-text-muted">
-          <div className="h-10 w-10 animate-spin rounded-full border-2 border-primary/30 border-t-primary" />
-        </div>
-      )}
-
-      {/* Zoom indicator */}
-      {isZoomed && (
-        <div className="pointer-events-none absolute bottom-3 left-1/2 -translate-x-1/2 rounded bg-black/60 px-2 py-1 text-xs font-mono text-white">
-          {Math.round(scale * 100)}%
-        </div>
-      )}
-    </div>
-  )
-}

frontend/src/components/preview/PreviewView.tsx

@@ -1,154 +0,0 @@
-import { useCallback, useEffect, useRef } from 'react'
-import { useHotkeys } from 'react-hotkeys-hook'
-import { X } from 'lucide-react'
-import { usePhotoStore } from '../../store/photoStore'
-import { usePhotosQuery } from '../../hooks/usePhotosQuery'
-import type { Photo } from '../../types/photo'
-import { PreviewImage } from './PreviewImage'
-import { PreviewFilmstrip } from './PreviewFilmstrip'
-import { getPreviewImageSrc, isVideo } from './previewSrc'
-
-export function PreviewView() {
-  const activePhotoId = usePhotoStore((s) => s.activePhotoId)
-  const setActivePhoto = usePhotoStore((s) => s.setActivePhoto)
-  const closePreview = usePhotoStore((s) => s.closePreview)
-
-  const containerRef = useRef<HTMLDivElement>(null)
-  const previouslyFocusedRef = useRef<HTMLElement | null>(null)
-
-  // Same hook Timeline uses, so we share one cache entry rather than looking
-  // it up by key (which broke when the key gained the filter params).
-  const { data: photos = [] } = usePhotosQuery()
-
-  const currentIndex = activePhotoId
-    ? photos.findIndex((p) => p.id === activePhotoId)
-    : 0
-  const safeIndex = currentIndex < 0 ? 0 : currentIndex
-  const currentPhoto: Photo | undefined = photos[safeIndex]
-
-  const goPrev = useCallback(() => {
-    if (photos.length === 0) return
-    const next = Math.max(0, safeIndex - 1)
-    setActivePhoto(photos[next].id)
-  }, [photos, safeIndex, setActivePhoto])
-
-  const goNext = useCallback(() => {
-    if (photos.length === 0) return
-    const next = Math.min(photos.length - 1, safeIndex + 1)
-    setActivePhoto(photos[next].id)
-  }, [photos, safeIndex, setActivePhoto])
-
-  // Preview-scoped hotkeys: only mounted while PreviewView is rendered.
-  useHotkeys('escape', closePreview, { preventDefault: true })
-  useHotkeys('left', goPrev, { preventDefault: true }, [goPrev])
-  useHotkeys('right', goNext, { preventDefault: true }, [goNext])
-
-  // Preload the immediate neighbors so arrow nav feels instant. Skip videos
-  // (browsers can't preload them via Image()) and skip when at the edges.
-  useEffect(() => {
-    const neighbors: Photo[] = []
-    if (safeIndex > 0) neighbors.push(photos[safeIndex - 1])
-    if (safeIndex < photos.length - 1) neighbors.push(photos[safeIndex + 1])
-    for (const p of neighbors) {
-      if (isVideo(p)) continue
-      const img = new Image()
-      img.src = getPreviewImageSrc(p)
-    }
-  }, [safeIndex, photos])
-
-  // Focus trap: focus the preview container on mount, restore focus on
-  // unmount. The container is keyboard-focusable (tabIndex=-1) so screen
-  // readers and tab navigation stay scoped here.
-  useEffect(() => {
-    previouslyFocusedRef.current = document.activeElement as HTMLElement | null
-    containerRef.current?.focus()
-    return () => {
-      previouslyFocusedRef.current?.focus?.()
-    }
-  }, [])
-
-  // Trap Tab inside the dialog so users can't accidentally tab into the
-  // hidden grid behind. Simple cycle implementation.
-  const handleKeyDown = (e: React.KeyboardEvent) => {
-    if (e.key !== 'Tab') return
-    const root = containerRef.current
-    if (!root) return
-    const focusable = root.querySelectorAll<HTMLElement>(
-      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
-    )
-    if (focusable.length === 0) {
-      e.preventDefault()
-      root.focus()
-      return
-    }
-    const first = focusable[0]
-    const last = focusable[focusable.length - 1]
-    const active = document.activeElement as HTMLElement | null
-    if (e.shiftKey && active === first) {
-      e.preventDefault()
-      last.focus()
-    } else if (!e.shiftKey && active === last) {
-      e.preventDefault()
-      first.focus()
-    }
-  }
-
-  if (!currentPhoto) {
-    return (
-      <div
-        ref={containerRef}
-        role="dialog"
-        aria-modal="true"
-        aria-label="Photo preview"
-        tabIndex={-1}
-        className="fixed inset-0 z-40 flex flex-col items-center justify-center bg-black text-text-muted outline-none"
-      >
-        <div>No photo to display</div>
-        <button
-          onClick={closePreview}
-          className="mt-4 rounded border border-border px-3 py-1 text-sm hover:bg-surface"
-        >
-          Close
-        </button>
-      </div>
-    )
-  }
-
-  return (
-    <div
-      ref={containerRef}
-      role="dialog"
-      aria-modal="true"
-      aria-label={`Photo preview: ${currentPhoto.filename}`}
-      tabIndex={-1}
-      onKeyDown={handleKeyDown}
-      className="fixed inset-0 z-40 flex flex-col bg-black outline-none"
-    >
-      {/* Close button */}
-      <button
-        onClick={closePreview}
-        className="absolute right-3 top-3 z-10 flex h-9 w-9 items-center justify-center rounded-full bg-black/60 text-white transition hover:bg-black/80"
-        title="Close (Esc)"
-        aria-label="Close preview"
-      >
-        <X className="h-5 w-5" />
-      </button>
-
-      {/* Filename + counter */}
-      <div className="absolute left-3 top-3 z-10 rounded bg-black/60 px-3 py-1.5 text-xs text-white">
-        <div className="font-mono">{currentPhoto.filename}</div>
-        <div className="text-text-muted">
-          {safeIndex + 1} / {photos.length}
-        </div>
-      </div>
-
-      <PreviewImage photo={currentPhoto} />
-
-      <PreviewFilmstrip
-        photos={photos}
-        currentIndex={safeIndex}
-        onSelect={setActivePhoto}
-      />
-    </div>
-  )
-}

frontend/src/components/preview/previewSrc.ts

@@ -1,33 +0,0 @@
-import { photos as photosApi } from '../../services/api'
-import type { Photo } from '../../types/photo'
-
-const VIDEO_EXTENSIONS = ['.mp4', '.mov', '.webm', '.mkv', '.m4v']
-
-export function isVideo(photo: Photo): boolean {
-  if (photo.media_type === 'video') return true
-  const lower = photo.filepath.toLowerCase()
-  return VIDEO_EXTENSIONS.some((ext) => lower.endsWith(ext))
-}
-
-/**
- * Pick the best display URL for a still photo in the preview view.
- *
- * Always uses the /proxy endpoint, which the backend resolves to:
- *   - the original file for web-safe formats (JPEG/PNG/WebP/GIF)
- *   - a transcoded full-res WebP for RAW/HEIC/TIFF (cached on first hit)
- *
- * Videos go through `getVideoSrc` instead and use /original directly.
- */
-export function getPreviewImageSrc(photo: Photo): string {
-  return photosApi.getProxyUrl(photo.id)
-}
-
-/** Fallback used when the proxy endpoint fails or 404s — shows the 1280px
- *  large thumbnail so the user still sees something. */
-export function getPreviewFallbackSrc(photo: Photo): string {
-  return photosApi.getThumbnailUrl(photo.id, 'large')
-}
-
-export function getVideoSrc(photo: Photo): string {
-  return photosApi.getOriginalUrl(photo.id)
-}

frontend/src/components/timeline/PhotoThumbnail.tsx

@@ -1,224 +0,0 @@
-import { useState, useEffect, useCallback, useRef } from 'react'
-import { Star, ShoppingBasket, Trash2, RefreshCw, Check } from 'lucide-react'
-import clsx from 'clsx'
-import { photos as photosApi } from '../../services/api'
-import type { Photo } from '../../types/photo'
-import { usePhotoStore } from '../../store/photoStore'
-
-/** Custom MIME used by HeapsPanel to recognise our drag payload. */
-export const PHOTO_DRAG_MIME = 'application/x-mulita-photos'
-
-// Auto-retry schedule (ms). Backend generates thumbs on-demand via Celery, so
-// first hit often 404s. Try a few times with backoff before giving up.
-const AUTO_RETRY_DELAYS = [1500, 3500, 6000]
-
-interface PhotoThumbnailProps {
-  photo: Photo
-  size: number
-  isSelected: boolean
-  /** True when the photo belongs to the currently active heap. */
-  isInActiveHeap?: boolean
-  onClick: (e: React.MouseEvent) => void
-  onDoubleClick?: (e: React.MouseEvent) => void
-}
-
-export function PhotoThumbnail({
-  photo,
-  size,
-  isSelected,
-  isInActiveHeap = false,
-  onClick,
-  onDoubleClick,
-}: PhotoThumbnailProps) {
-  const [imageError, setImageError] = useState(false)
-  const [imageLoaded, setImageLoaded] = useState(false)
-  const [retryCount, setRetryCount] = useState(0)
-  const [isRetrying, setIsRetrying] = useState(false)
-  const retryTimerRef = useRef<number | null>(null)
-
-  // Cache-bust on retry so the browser actually re-requests instead of
-  // serving the cached 404.
-  const baseUrl = photosApi.getThumbnailUrl(photo.id, 'medium')
-  const thumbnailUrl = retryCount > 0 ? `${baseUrl}?retry=${retryCount}` : baseUrl
-
-  // Square cells (Lightroom-style grid). Variable-aspect cells previously
-  // overflowed their row because TanStack Virtual estimates row height as a
-  // single fixed value — portraits in a landscape row would overlap the row
-  // below. With object-cover the image still fills the cell, just cropped.
-  const displayHeight = size
-
-  const clearRetryTimer = () => {
-    if (retryTimerRef.current !== null) {
-      window.clearTimeout(retryTimerRef.current)
-      retryTimerRef.current = null
-    }
-  }
-
-  const handleImageLoad = () => {
-    setImageLoaded(true)
-    setIsRetrying(false)
-  }
-
-  const handleImageError = () => {
-    // Schedule next auto-retry if attempts remain.
-    const nextDelay = AUTO_RETRY_DELAYS[retryCount]
-    if (nextDelay !== undefined) {
-      setIsRetrying(true)
-      clearRetryTimer()
-      retryTimerRef.current = window.setTimeout(() => {
-        retryTimerRef.current = null
-        setRetryCount(prev => prev + 1)
-      }, nextDelay)
-    } else {
-      setImageError(true)
-      setIsRetrying(false)
-    }
-  }
-
-  const handleManualRetry = useCallback((e: React.MouseEvent) => {
-    e.stopPropagation() // Prevent selection when clicking retry
-    clearRetryTimer()
-    setRetryCount(prev => prev + 1)
-    setImageError(false)
-    setImageLoaded(false)
-    setIsRetrying(true)
-  }, [])
-
-  // Reset state when photo changes (component is reused across rows when virtualized)
-  useEffect(() => {
-    clearRetryTimer()
-    setImageError(false)
-    setImageLoaded(false)
-    setRetryCount(0)
-    setIsRetrying(false)
-  }, [photo.id])
-
-  // Clear pending timer on unmount to avoid setState-after-unmount.
-  useEffect(() => {
-    return () => clearRetryTimer()
-  }, [])
-  
-  // Build the drag payload at fire time so multi-selection drags carry the
-  // current selection. If the dragged photo isn't part of the selection,
-  // drag just that one photo (matches Finder semantics).
-  const handleDragStart = (e: React.DragEvent<HTMLDivElement>) => {
-    const state = usePhotoStore.getState()
-    const ids =
-      state.selectedPhotos.includes(photo.id) && state.selectedPhotos.length > 0
-        ? state.selectedPhotos
-        : [photo.id]
-    e.dataTransfer.effectAllowed = 'copy'
-    e.dataTransfer.setData(PHOTO_DRAG_MIME, JSON.stringify(ids))
-    // A plain text fallback so the OS shows something sensible if the user
-    // drops outside the app.
-    e.dataTransfer.setData('text/plain', `${ids.length} photo${ids.length > 1 ? 's' : ''}`)
-  }
-
-  return (
-    <div
-      className={clsx(
-        'group relative cursor-pointer overflow-hidden rounded-sm transition-all duration-200',
-        'hover:ring-2 hover:ring-primary/50',
-        isSelected && 'ring-2 ring-primary shadow-lg',
-        !imageLoaded && 'bg-surface animate-pulse'
-      )}
-      style={{
-        width: size,
-        height: displayHeight,
-      }}
-      onClick={onClick}
-      onDoubleClick={onDoubleClick}
-      draggable
-      onDragStart={handleDragStart}
-      title="Click to select • Double-click to open • Shift+Click for range • Ctrl+Click to add • Drag onto a heap to add"
-    >
-      {/* Thumbnail Image */}
-      {!imageError ? (
-        <>
-          <img
-            src={thumbnailUrl}
-            alt={photo.filename}
-            className={clsx(
-              'h-full w-full object-cover transition-opacity duration-200',
-              imageLoaded ? 'opacity-100' : 'opacity-0'
-            )}
-            onLoad={handleImageLoad}
-            onError={handleImageError}
-            loading="lazy"
-          />
-          {/* Loading indicator */}
-          {!imageLoaded && (
-            <div className="absolute inset-0 flex items-center justify-center bg-surface">
-              <div className="text-text-muted">
-                {isRetrying ? (
-                  <div className="text-center">
-                    <RefreshCw className="h-5 w-5 animate-spin mx-auto mb-1" />
-                    <div className="text-xs">Retrying...</div>
-                  </div>
-                ) : (
-                  <div className="h-8 w-8 border-2 border-primary/30 border-t-primary rounded-full animate-spin" />
-                )}
-              </div>
-            </div>
-          )}
-        </>
-      ) : (
-        <div className="flex h-full w-full items-center justify-center bg-surface text-text-muted">
-          <div className="text-center text-xs">
-            <button
-              onClick={handleManualRetry}
-              className="p-2 hover:bg-surface-light rounded transition-colors"
-              title="Retry loading thumbnail"
-            >
-              <RefreshCw className="h-5 w-5 mb-1" />
-            </button>
-            <div>Unable to load</div>
-            <div className="mt-1 font-mono text-[10px] px-2 break-all">{photo.filename}</div>
-          </div>
-        </div>
-      )}
-      
-      {/* Selection Indicator */}
-      {isSelected && (
-        <div className="absolute left-1 top-1 flex h-6 w-6 items-center justify-center rounded-full bg-primary text-white">
-          <Check className="h-4 w-4" />
-        </div>
-      )}
-      
-      {/* Rating Stars */}
-      {photo.rating > 0 && (
-        <div className="absolute bottom-1 left-1 flex gap-0.5">
-          {Array.from({ length: photo.rating }).map((_, i) => (
-            <Star
-              key={i}
-              className="h-3 w-3 fill-star text-star"
-            />
-          ))}
-        </div>
-      )}
-      
-      {/* Flag Indicators */}
-      <div className="absolute bottom-1 right-1 flex items-center gap-1">
-        {isInActiveHeap && (
-          <div
-            className="flex h-5 w-5 items-center justify-center rounded-full bg-pick text-white shadow-md"
-            title="In active heap"
-          >
-            <ShoppingBasket className="h-3 w-3" />
-          </div>
-        )}
-        {photo.is_discarded && (
-          <Trash2 className="h-4 w-4 text-reject" />
-        )}
-      </div>
-      
-      {/* File Type Badge for RAW/Video */}
-      {(photo.filepath.toLowerCase().match(/\.(raw|arw|cr2|cr3|nef|orf|rw2|dng)$/i) ||
-        photo.filepath.toLowerCase().match(/\.(mov|mp4|avi|mkv)$/i)) && (
-        <div className="absolute right-1 top-1 rounded bg-black/50 px-1 py-0.5 text-[10px] font-medium text-white">
-          {photo.filepath.toLowerCase().match(/\.(mov|mp4|avi|mkv)$/i) ? 'VIDEO' : 'RAW'}
-        </div>
-      )}
-    </div>
-  )
-}

frontend/src/components/timeline/Timeline.tsx

@@ -1,400 +0,0 @@
-import { useRef, useEffect, useMemo, useState } from 'react'
-import { useVirtualizer } from '@tanstack/react-virtual'
-import { format, parseISO } from 'date-fns'
-import { usePhotoStore } from '../../store/photoStore'
-import { useFilterStore } from '../../store/filterStore'
-import { PhotoThumbnail } from './PhotoThumbnail'
-import { usePhotosQuery } from '../../hooks/usePhotosQuery'
-import { useActiveHeapMembers } from '../../hooks/useActiveHeapMembersQuery'
-import type { Photo } from '../../types/photo'
-
-// Layout constants for the grid + grouped headers.
-const THUMBNAIL_SIZE = 200
-const GAP = 4
-const PADDING = 16
-const HEADER_HEIGHT = 36
-
-interface PhotoCell {
-  photo: Photo
-  globalIndex: number
-}
-
-type TimelineItem =
-  | { type: 'header'; key: string; label: string; height: number }
-  | { type: 'row'; key: string; cells: PhotoCell[]; height: number }
-
-/**
- * Build groups by month label when sorted by a date field. For non-temporal
- * sorts (filename / file_size / rating) we return a single un-headered group.
- */
-function buildItems(
-  photos: Photo[],
-  columns: number,
-  sortBy: string
-): TimelineItem[] {
-  if (photos.length === 0) return []
-
-  const isDateSort = sortBy === 'taken_at' || sortBy === 'added_at'
-  const items: TimelineItem[] = []
-
-  // Helper: split a flat array of cells into rows of `columns` cells.
-  const pushRowsForGroup = (groupKey: string, cells: PhotoCell[]) => {
-    for (let i = 0; i < cells.length; i += columns) {
-      const slice = cells.slice(i, i + columns)
-      items.push({
-        type: 'row',
-        key: `${groupKey}::row::${i}`,
-        cells: slice,
-        height: THUMBNAIL_SIZE + GAP,
-      })
-    }
-  }
-
-  if (!isDateSort) {
-    // No grouping — one row stream.
-    const cells: PhotoCell[] = photos.map((photo, globalIndex) => ({
-      photo,
-      globalIndex,
-    }))
-    pushRowsForGroup('all', cells)
-    return items
-  }
-
-  // Walk photos in order, breaking into groups whenever the month label changes.
-  let currentLabel: string | null = null
-  let bucket: PhotoCell[] = []
-  let bucketIndex = 0
-
-  const flushBucket = () => {
-    if (bucket.length === 0 || currentLabel === null) return
-    items.push({
-      type: 'header',
-      key: `header::${bucketIndex}::${currentLabel}`,
-      label: currentLabel,
-      height: HEADER_HEIGHT,
-    })
-    pushRowsForGroup(`${bucketIndex}::${currentLabel}`, bucket)
-    bucketIndex++
-    bucket = []
-  }
-
-  photos.forEach((photo, globalIndex) => {
-    const dateStr =
-      sortBy === 'taken_at'
-        ? photo.taken_at
-        : (photo as any).added_at ?? photo.taken_at
-    let label: string
-    if (dateStr) {
-      try {
-        label = format(parseISO(dateStr), 'MMMM yyyy')
-      } catch {
-        label = 'Unknown date'
-      }
-    } else {
-      label = 'Unknown date'
-    }
-    if (label !== currentLabel) {
-      flushBucket()
-      currentLabel = label
-    }
-    bucket.push({ photo, globalIndex })
-  })
-  flushBucket()
-
-  return items
-}
-
-export function Timeline() {
-  const parentRef = useRef<HTMLDivElement>(null)
-  const [containerWidth, setContainerWidth] = useState(0)
-
-  const {
-    selectedPhotos,
-    lastSelectedIndex,
-    rangeStartIndex,
-    selectPhoto,
-    togglePhotoSelection,
-    clearSelection,
-    openPreview,
-  } = usePhotoStore()
-
-  const sortBy = useFilterStore((s) => s.sortBy)
-
-  // Calculate number of columns based on container width.
-  const columns = useMemo(() => {
-    if (containerWidth === 0) return 4
-    return Math.max(
-      1,
-      Math.floor((containerWidth - PADDING * 2) / (THUMBNAIL_SIZE + GAP))
-    )
-  }, [containerWidth])
-
-  // Shared photos query — both Timeline and PreviewView use the same hook so
-  // they share one cache entry, regardless of filter state.
-  const { data: photos = [], isLoading } = usePhotosQuery()
-
-  // Membership in the active heap (for the basket affordance). Subscribed
-  // once at this level so we don't have hundreds of thumbnails each
-  // subscribing to the same query.
-  const { memberIds: activeHeapMembers } = useActiveHeapMembers()
-
-  // Build the flat virtualizer items: a mix of date-group headers and rows
-  // of photos. Headers only appear when sorted by a date field.
-  const items = useMemo(
-    () => buildItems(photos, columns, sortBy),
-    [photos, columns, sortBy]
-  )
-
-  // Pre-computed offset of every header in the virtualizer's coordinate
-  // space, used to drive the sticky-header overlay below.
-  const headerOffsets = useMemo(() => {
-    const result: { offset: number; label: string }[] = []
-    let cumulative = 0
-    for (const item of items) {
-      if (item.type === 'header') {
-        result.push({ offset: cumulative, label: item.label })
-      }
-      cumulative += item.height
-    }
-    return result
-  }, [items])
-
-  // Range-selection helper. Operates on the global photos array, not on
-  // virtualizer items.
-  const selectRange = (endIndex: number) => {
-    const startIndex = rangeStartIndex ?? lastSelectedIndex ?? 0
-    const minIndex = Math.min(startIndex, endIndex)
-    const maxIndex = Math.max(startIndex, endIndex)
-    for (let i = minIndex; i <= maxIndex; i++) {
-      if (i < photos.length && !selectedPhotos.includes(photos[i].id)) {
-        togglePhotoSelection(photos[i].id, i)
-      }
-    }
-  }
-
-  // Virtual scrolling setup with per-item heights.
-  const virtualizer = useVirtualizer({
-    count: items.length,
-    getScrollElement: () => parentRef.current,
-    estimateSize: (index) => items[index]?.height ?? THUMBNAIL_SIZE,
-    overscan: 5,
-  })
-
-  // Re-measure when items change (column count, group structure).
-  useEffect(() => {
-    virtualizer.measure()
-  }, [items, virtualizer])
-
-  // Track scroll position so we can show the current group label as a
-  // pinned overlay at the top of the scroll container. The virtualizer's
-  // items use transform translateY (so CSS position: sticky doesn't work
-  // on the inline headers); the overlay sidesteps that by living outside
-  // the virtualizer's positioned children.
-  const [scrollTop, setScrollTop] = useState(0)
-  useEffect(() => {
-    const el = parentRef.current
-    if (!el) return
-    const onScroll = () => setScrollTop(el.scrollTop)
-    el.addEventListener('scroll', onScroll, { passive: true })
-    return () => el.removeEventListener('scroll', onScroll)
-  }, [])
-
-  // Find the latest header whose start <= scrollTop. That's the label of
-  // the group containing whatever is currently at the top of the viewport.
-  const stickyLabel = useMemo(() => {
-    if (headerOffsets.length === 0) return null
-    let current: string | null = null
-    for (const h of headerOffsets) {
-      if (h.offset <= scrollTop) current = h.label
-      else break
-    }
-    return current
-  }, [headerOffsets, scrollTop])
-
-  // Measure container width on mount and resize.
-  useEffect(() => {
-    const measureWidth = () => {
-      if (parentRef.current) {
-        setContainerWidth(parentRef.current.clientWidth)
-      }
-    }
-    measureWidth()
-    window.addEventListener('resize', measureWidth)
-    return () => window.removeEventListener('resize', measureWidth)
-  }, [])
-
-  // Handle keyboard shortcuts for photo navigation. Operates on the flat
-  // photos array, so it ignores grouping.
-  useEffect(() => {
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (photos.length === 0) return
-      const target = e.target as HTMLElement | null
-      if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA')) {
-        return
-      }
-
-      const currentIndex = lastSelectedIndex ?? -1
-
-      switch (e.key) {
-        case 'ArrowUp':
-          e.preventDefault()
-          if (currentIndex > columns - 1) {
-            const newIndex = currentIndex - columns
-            if (e.shiftKey) selectRange(newIndex)
-            else selectPhoto(photos[newIndex].id, newIndex)
-          }
-          break
-        case 'ArrowDown':
-          e.preventDefault()
-          if (currentIndex < photos.length - columns) {
-            const newIndex = Math.min(currentIndex + columns, photos.length - 1)
-            if (e.shiftKey) selectRange(newIndex)
-            else selectPhoto(photos[newIndex].id, newIndex)
-          }
-          break
-        case 'ArrowLeft':
-          e.preventDefault()
-          if (currentIndex > 0) {
-            const newIndex = currentIndex - 1
-            if (e.shiftKey) selectRange(newIndex)
-            else selectPhoto(photos[newIndex].id, newIndex)
-          }
-          break
-        case 'ArrowRight':
-          e.preventDefault()
-          if (currentIndex < photos.length - 1) {
-            const newIndex = currentIndex + 1
-            if (e.shiftKey) selectRange(newIndex)
-            else selectPhoto(photos[newIndex].id, newIndex)
-          }
-          break
-        case 'a':
-          if (e.ctrlKey || e.metaKey) {
-            e.preventDefault()
-            photos.forEach((photo, index) => {
-              if (!selectedPhotos.includes(photo.id)) {
-                togglePhotoSelection(photo.id, index)
-              }
-            })
-          }
-          break
-        case 'Escape':
-          e.preventDefault()
-          clearSelection()
-          break
-      }
-    }
-
-    window.addEventListener('keydown', handleKeyDown)
-    return () => window.removeEventListener('keydown', handleKeyDown)
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [photos, selectedPhotos, lastSelectedIndex, columns])
-
-  if (isLoading) {
-    return (
-      <div className="flex items-center justify-center h-full">
-        <div className="text-text-muted">Loading photos...</div>
-      </div>
-    )
-  }
-
-  if (photos.length === 0) {
-    return (
-      <div className="flex items-center justify-center h-full">
-        <div className="text-text-muted">No photos found. Add a source folder to get started.</div>
-      </div>
-    )
-  }
-
-  return (
-    <div className="relative h-full">
-      {/* Sticky group-header overlay. Lives outside the virtualizer's
-       *  positioned children so it isn't affected by translateY transforms.
-       *  Updates as the user scrolls past month boundaries. */}
-      {stickyLabel && (
-        <div className="pointer-events-none absolute left-0 right-0 top-0 z-20 border-b border-border bg-bg/90 px-4 py-1 backdrop-blur-sm">
-          <h3 className="text-sm font-semibold uppercase tracking-wide text-text">
-            {stickyLabel}
-          </h3>
-        </div>
-      )}
-
-      <div
-        ref={parentRef}
-        className="h-full overflow-auto bg-bg"
-        style={{ padding: `${PADDING}px` }}
-      >
-      <div
-        style={{
-          height: `${virtualizer.getTotalSize()}px`,
-          width: '100%',
-          position: 'relative',
-        }}
-      >
-        {virtualizer.getVirtualItems().map((virtualItem) => {
-          const item = items[virtualItem.index]
-          if (!item) return null
-
-          if (item.type === 'header') {
-            return (
-              <div
-                key={virtualItem.key}
-                style={{
-                  position: 'absolute',
-                  top: 0,
-                  left: 0,
-                  width: '100%',
-                  height: `${virtualItem.size}px`,
-                  transform: `translateY(${virtualItem.start}px)`,
-                }}
-                className="flex items-end pb-1"
-              >
-                <h3 className="text-sm font-semibold uppercase tracking-wide text-text-muted">
-                  {item.label}
-                </h3>
-              </div>
-            )
-          }
-
-          // row
-          return (
-            <div
-              key={virtualItem.key}
-              style={{
-                position: 'absolute',
-                top: 0,
-                left: 0,
-                width: '100%',
-                height: `${virtualItem.size}px`,
-                transform: `translateY(${virtualItem.start}px)`,
-              }}
-            >
-              <div className="flex" style={{ gap: `${GAP}px` }}>
-                {item.cells.map(({ photo, globalIndex }) => (
-                  <PhotoThumbnail
-                    key={photo.id}
-                    photo={photo}
-                    size={THUMBNAIL_SIZE}
-                    isSelected={selectedPhotos.includes(photo.id)}
-                    isInActiveHeap={activeHeapMembers.has(photo.id)}
-                    onClick={(e) => {
-                      if (e.shiftKey && lastSelectedIndex !== null) {
-                        selectRange(globalIndex)
-                      } else if (e.ctrlKey || e.metaKey) {
-                        togglePhotoSelection(photo.id, globalIndex)
-                      } else {
-                        selectPhoto(photo.id, globalIndex)
-                      }
-                    }}
-                    onDoubleClick={() => openPreview(photo.id)}
-                  />
-                ))}
-              </div>
-            </div>
-          )
-        })}
-      </div>
-      </div>
-    </div>
-  )
-}

frontend/src/hooks/useActiveHeapMembersQuery.ts

@@ -1,39 +0,0 @@
-import { useMemo } from 'react'
-import { useQuery } from '@tanstack/react-query'
-import { useHeapsQuery } from './useHeapsQuery'
-import { heaps as heapsApi } from '../services/api'
-
-const EMPTY_SET: ReadonlySet<string> = new Set()
-
-/**
- * Returns the photo ids that belong to the active heap as a Set, plus the
- * active heap itself. Used by PhotoThumbnail to render the basket affordance
- * and by the P shortcut to decide between add vs remove.
- *
- * If no heap is active, the Set is empty (and shared across renders).
- */
-export function useActiveHeapMembers(): {
-  activeHeap: ReturnType<typeof useHeapsQuery>['data'] extends (infer T)[] | undefined
-    ? T | null
-    : never
-  memberIds: ReadonlySet<string>
-} {
-  const { data: heaps } = useHeapsQuery()
-  const activeHeap = heaps?.find((h) => h.is_active) ?? null
-
-  const { data: ids } = useQuery({
-    queryKey: ['heap-photo-ids', activeHeap?.id],
-    queryFn: () => heapsApi.photoIds(activeHeap!.id),
-    enabled: !!activeHeap,
-    staleTime: 30_000,
-  })
-
-  const memberIds = useMemo(
-    () => (ids ? new Set(ids) : EMPTY_SET),
-    [ids]
-  )
-
-  return { activeHeap: activeHeap as any, memberIds }
-}
-
-export const ACTIVE_HEAP_MEMBERS_QUERY_KEY_PREFIX = ['heap-photo-ids'] as const

frontend/src/hooks/useFilterUrlSync.ts

@@ -1,132 +0,0 @@
-import { useEffect, useRef } from 'react'
-import {
-  useFilterStore,
-  type FilterState,
-  type MediaType,
-  type ColorLabel,
-  type FlagFilter,
-  type SortField,
-  type SortOrder,
-} from '../store/filterStore'
-
-const ALLOWED_MEDIA: MediaType[] = ['photo', 'video', 'raw', 'heic']
-const ALLOWED_COLORS: ColorLabel[] = [
-  'red',
-  'orange',
-  'yellow',
-  'green',
-  'blue',
-  'purple',
-]
-const ALLOWED_FLAGS: FlagFilter[] = ['any', 'discarded']
-const ALLOWED_SORT_FIELDS: SortField[] = [
-  'taken_at',
-  'added_at',
-  'filename',
-  'file_size',
-  'rating',
-]
-const ALLOWED_SORT_ORDERS: SortOrder[] = ['asc', 'desc']
-
-function parseUrl(): Partial<FilterState> {
-  const sp = new URLSearchParams(window.location.search)
-  const out: Partial<FilterState> = {}
-
-  const q = sp.get('q')
-  if (q) out.q = q
-
-  const df = sp.get('date_from')
-  if (df) out.dateFrom = df
-
-  const dt = sp.get('date_to')
-  if (dt) out.dateTo = dt
-
-  const mt = sp.get('media_type')
-  if (mt) {
-    const types = mt
-      .split(',')
-      .filter((t): t is MediaType => ALLOWED_MEDIA.includes(t as MediaType))
-    if (types.length > 0) out.mediaTypes = types
-  }
-
-  const rm = sp.get('rating_min')
-  if (rm) {
-    const n = parseInt(rm, 10)
-    if (Number.isFinite(n) && n >= 0 && n <= 5) out.ratingMin = n
-  }
-
-  const cl = sp.get('color_label')
-  if (cl && ALLOWED_COLORS.includes(cl as ColorLabel)) {
-    out.colorLabel = cl as ColorLabel
-  }
-
-  const flag = sp.get('flag')
-  if (flag && ALLOWED_FLAGS.includes(flag as FlagFilter)) {
-    out.flag = flag as FlagFilter
-  }
-
-  const heapId = sp.get('heap_id')
-  if (heapId) out.heapId = heapId
-
-  const folderId = sp.get('folder_id')
-  if (folderId) out.folderId = folderId
-
-  const sortBy = sp.get('sort')
-  if (sortBy && ALLOWED_SORT_FIELDS.includes(sortBy as SortField)) {
-    out.sortBy = sortBy as SortField
-  }
-
-  const sortOrder = sp.get('order')
-  if (sortOrder && ALLOWED_SORT_ORDERS.includes(sortOrder as SortOrder)) {
-    out.sortOrder = sortOrder as SortOrder
-  }
-
-  return out
-}
-
-function writeUrl(f: FilterState) {
-  const sp = new URLSearchParams()
-  if (f.q.trim()) sp.set('q', f.q.trim())
-  if (f.dateFrom) sp.set('date_from', f.dateFrom)
-  if (f.dateTo) sp.set('date_to', f.dateTo)
-  if (f.mediaTypes.length > 0) sp.set('media_type', f.mediaTypes.join(','))
-  if (f.ratingMin > 0) sp.set('rating_min', String(f.ratingMin))
-  if (f.colorLabel) sp.set('color_label', f.colorLabel)
-  if (f.flag !== 'any') sp.set('flag', f.flag)
-  if (f.heapId) sp.set('heap_id', f.heapId)
-  if (f.folderId) sp.set('folder_id', f.folderId)
-  if (f.sortBy !== 'taken_at') sp.set('sort', f.sortBy)
-  if (f.sortOrder !== 'desc') sp.set('order', f.sortOrder)
-
-  const search = sp.toString()
-  const next = search ? `?${search}` : window.location.pathname
-  if (next !== window.location.search && next !== window.location.pathname + window.location.search) {
-    window.history.replaceState(null, '', next)
-  }
-}
-
-/**
- * Bidirectional URL <-> filterStore sync. Hydrates the store from the URL on
- * mount, then writes any subsequent store changes back to the URL via
- * history.replaceState (no navigation).
- */
-export function useFilterUrlSync() {
-  const hydrated = useRef(false)
-
-  // Hydrate once on mount.
-  useEffect(() => {
-    const fromUrl = parseUrl()
-    if (Object.keys(fromUrl).length > 0) {
-      useFilterStore.getState().hydrate(fromUrl)
-    }
-    hydrated.current = true
-  }, [])
-
-  // Mirror store -> URL on every change (after hydration).
-  useEffect(() => {
-    return useFilterStore.subscribe((state) => {
-      if (!hydrated.current) return
-      writeUrl(state)
-    })
-  }, [])
-}

frontend/src/hooks/useHeapsQuery.ts

@@ -1,12 +0,0 @@
-import { useQuery } from '@tanstack/react-query'
-import { heaps as heapsApi, type Heap } from '../services/api'
-
-export const HEAPS_QUERY_KEY = ['heaps'] as const
-
-export function useHeapsQuery() {
-  return useQuery<Heap[]>({
-    queryKey: HEAPS_QUERY_KEY,
-    queryFn: heapsApi.list,
-    staleTime: 30_000,
-  })
-}

frontend/src/hooks/useKeyboardShortcuts.ts

@@ -1,219 +0,0 @@
-import { useHotkeys } from 'react-hotkeys-hook'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { usePhotoStore } from '../store/photoStore'
-import { useFilterStore } from '../store/filterStore'
-import { photos as photosApi, heaps as heapsApi, type Heap } from '../services/api'
-import { HEAPS_QUERY_KEY } from './useHeapsQuery'
-import { toast } from '../components/ToastContainer'
-
-interface KeyboardShortcutsProps {
-  onToggleLeftSidebar: () => void
-  onToggleRightSidebar: () => void
-  /** Returns the first photo id in the current timeline, or null if empty. */
-  getFirstPhotoId?: () => string | null
-}
-
-interface PhotoUpdate {
-  rating?: number
-  is_discarded?: boolean
-  color_label?: string | null
-}
-
-// Spec §6.4 number-key color labels.
-const COLOR_LABELS: Record<string, string> = {
-  '6': 'red',
-  '7': 'orange',
-  '8': 'yellow',
-  '9': 'green',
-}
-
-// Default options shared by every shortcut: preventDefault stops the browser
-// from claiming the event (Firefox quick-find on letter keys, Cmd+F search,
-// `/` quick-find, Tab focus traversal). enableOnFormTags is left default-off
-// so typing in inputs doesn't fire culling shortcuts.
-const HK_OPTS = { preventDefault: true } as const
-
-export function useKeyboardShortcuts(props: KeyboardShortcutsProps) {
-  const { onToggleLeftSidebar, onToggleRightSidebar, getFirstPhotoId } = props
-
-  const viewMode = usePhotoStore((s) => s.viewMode)
-  const openPreview = usePhotoStore((s) => s.openPreview)
-  const closePreview = usePhotoStore((s) => s.closePreview)
-
-  const isPreview = viewMode === 'preview'
-
-  // Photo mutation shared by every culling shortcut. Reads the active photo
-  // id from the store at fire time so the closure stays fresh without forcing
-  // hotkey re-binding on every selection change.
-  const queryClient = useQueryClient()
-  const updateMutation = useMutation({
-    mutationFn: ({ id, data }: { id: string; data: PhotoUpdate }) =>
-      photosApi.update(id, data),
-    onSuccess: (_data, vars) => {
-      queryClient.invalidateQueries({ queryKey: ['photo', vars.id] })
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-    },
-  })
-
-  const updateActive = (data: PhotoUpdate) => {
-    const id = usePhotoStore.getState().activePhotoId
-    if (!id) return
-    updateMutation.mutate({ id, data })
-  }
-
-  // P key (Pick): toggle the current selection's membership in the active
-  // heap. If every selected photo is already a member, remove them; otherwise
-  // add the missing ones. No active heap → toast hint.
-  const heapMutation = useMutation({
-    mutationFn: ({
-      heapId,
-      photoIds,
-      remove,
-    }: {
-      heapId: string
-      photoIds: string[]
-      remove: boolean
-    }) =>
-      remove
-        ? heapsApi.removePhotos(heapId, photoIds)
-        : heapsApi.addPhotos(heapId, photoIds),
-    // Optimistically flip the membership cache so the basket affordance
-    // updates instantly and a quick second P press reads the new state
-    // (otherwise invalidate-then-refetch leaves a brief stale window).
-    onMutate: ({ heapId, photoIds, remove }) => {
-      const key = ['heap-photo-ids', heapId] as const
-      const previous = queryClient.getQueryData<string[]>(key)
-      const set = new Set(previous ?? [])
-      if (remove) photoIds.forEach((id) => set.delete(id))
-      else photoIds.forEach((id) => set.add(id))
-      queryClient.setQueryData<string[]>(key, Array.from(set))
-      return { previous }
-    },
-    onError: (e: any, _vars, ctx) => {
-      // Roll back the optimistic update on failure.
-      if (ctx?.previous) {
-        queryClient.setQueryData(['heap-photo-ids', _vars.heapId], ctx.previous)
-      }
-      toast.error('Heap update failed', e.message || 'Unknown error')
-    },
-    onSuccess: (data, vars) => {
-      const heap = (queryClient.getQueryData<Heap[]>(HEAPS_QUERY_KEY) ?? []).find(
-        (h) => h.id === vars.heapId
-      )
-      const heapName = heap?.name ?? 'heap'
-      if (vars.remove) {
-        const removed = data?.removed ?? 0
-        toast.success(`Removed from ${heapName}`, `${removed} photo${removed === 1 ? '' : 's'}`)
-      } else {
-        const added = data?.added ?? 0
-        const already = data?.already_present ?? 0
-        if (added > 0) {
-          toast.success(
-            `Added to ${heapName}`,
-            `${added} photo${added > 1 ? 's' : ''}${already > 0 ? ` (${already} already present)` : ''}`
-          )
-        }
-      }
-    },
-    onSettled: (_data, _err, vars) => {
-      // Re-sync with server truth (heap counts in particular need this).
-      queryClient.invalidateQueries({ queryKey: HEAPS_QUERY_KEY })
-      queryClient.invalidateQueries({ queryKey: ['heap-photo-ids', vars.heapId] })
-    },
-  })
-
-  const togglePickOnSelection = () => {
-    const state = usePhotoStore.getState()
-    const ids =
-      state.selectedPhotos.length > 0
-        ? state.selectedPhotos
-        : state.activePhotoId
-          ? [state.activePhotoId]
-          : []
-    if (ids.length === 0) {
-      toast.info('Nothing selected', 'Select photos first, then press P')
-      return
-    }
-    const heapsList = queryClient.getQueryData<Heap[]>(HEAPS_QUERY_KEY) ?? []
-    const active = heapsList.find((h) => h.is_active)
-    if (!active) {
-      toast.info('No active heap', 'Set an active heap (target icon next to a heap)')
-      return
-    }
-    // Determine direction: if every selected photo is already a member, this
-    // press REMOVES them; otherwise it ADDS the missing ones. Mirrors how
-    // Lightroom's flag-toggle works.
-    const memberIds =
-      queryClient.getQueryData<string[]>(['heap-photo-ids', active.id]) ?? []
-    const memberSet = new Set(memberIds)
-    const allMembers = ids.every((id) => memberSet.has(id))
-    heapMutation.mutate({
-      heapId: active.id,
-      photoIds: ids,
-      remove: allMembers,
-    })
-  }
-
-  // Toggle sidebars
-  useHotkeys('tab', onToggleLeftSidebar, HK_OPTS)
-  useHotkeys('i', onToggleRightSidebar, HK_OPTS)
-
-  // Filter bar toggle (\) and search focus (/ or Cmd/Ctrl+F).
-  useHotkeys('\\', () => useFilterStore.getState().toggleFilterBar(), HK_OPTS)
-
-  const focusSearch = () => {
-    const el = document.getElementById('topbar-search') as HTMLInputElement | null
-    el?.focus()
-    el?.select()
-  }
-  useHotkeys('/', focusSearch, HK_OPTS)
-  useHotkeys('mod+f', focusSearch, HK_OPTS)
-
-  // Space toggles the preview view (open from grid, close from preview).
-  // Double-click on a thumbnail does the same.
-  const openPreviewFromGrid = () => {
-    const id = usePhotoStore.getState().activePhotoId ?? getFirstPhotoId?.() ?? null
-    if (id) openPreview(id)
-  }
-
-  const togglePreview = () => {
-    if (isPreview) closePreview()
-    else openPreviewFromGrid()
-  }
-
-  useHotkeys('space', togglePreview, HK_OPTS, [isPreview, getFirstPhotoId])
-
-  // ── Culling shortcuts (work in both grid and preview) ────────────────────
-
-  // Star rating: 1-5 set, 0 clears.
-  useHotkeys(
-    '1,2,3,4,5',
-    (_e, handler) => {
-      const rating = parseInt(handler.keys![0])
-      if (Number.isFinite(rating)) updateActive({ rating })
-    },
-    HK_OPTS
-  )
-
-  useHotkeys('0', () => updateActive({ rating: 0 }), HK_OPTS)
-
-  // P (Pick) is unified with "add to active heap" — Pick a photo and you're
-  // adding it to the heap you set as active. Toggling on already-picked
-  // photos removes them from the heap.
-  useHotkeys('p', togglePickOnSelection, HK_OPTS)
-
-  useHotkeys('x', () => updateActive({ is_discarded: true }), HK_OPTS)
-
-  useHotkeys('u', () => updateActive({ is_discarded: false }), HK_OPTS)
-
-  // Color labels 6-9 (red/orange/yellow/green per spec §6.4).
-  useHotkeys(
-    '6,7,8,9',
-    (_e, handler) => {
-      const label = COLOR_LABELS[handler.keys![0]]
-      if (label) updateActive({ color_label: label })
-    },
-    HK_OPTS
-  )
-
-}

frontend/src/hooks/usePhotosQuery.ts

@@ -1,61 +0,0 @@
-import { useMemo } from 'react'
-import { useQuery } from '@tanstack/react-query'
-import axios from 'axios'
-import { useFilterStore, filtersToParams } from '../store/filterStore'
-import type { Photo } from '../types/photo'
-
-/**
- * Single source of truth for the timeline photos query. Both Timeline and
- * PreviewView call this so they share one cache entry — previously
- * PreviewView looked the cache up by key directly, which broke the moment
- * Timeline's key gained the filter params.
- */
-export function usePhotosQuery() {
-  const q = useFilterStore((s) => s.q)
-  const dateFrom = useFilterStore((s) => s.dateFrom)
-  const dateTo = useFilterStore((s) => s.dateTo)
-  const mediaTypes = useFilterStore((s) => s.mediaTypes)
-  const ratingMin = useFilterStore((s) => s.ratingMin)
-  const colorLabel = useFilterStore((s) => s.colorLabel)
-  const flag = useFilterStore((s) => s.flag)
-  const heapId = useFilterStore((s) => s.heapId)
-  const folderId = useFilterStore((s) => s.folderId)
-  const sortBy = useFilterStore((s) => s.sortBy)
-  const sortOrder = useFilterStore((s) => s.sortOrder)
-
-  const filterParams = useMemo(
-    () =>
-      filtersToParams({
-        q,
-        dateFrom,
-        dateTo,
-        mediaTypes,
-        ratingMin,
-        colorLabel,
-        flag,
-        heapId,
-        folderId,
-        sortBy,
-        sortOrder,
-      }),
-    [q, dateFrom, dateTo, mediaTypes, ratingMin, colorLabel, flag, heapId, folderId, sortBy, sortOrder]
-  )
-
-  return useQuery({
-    queryKey: ['photos', filterParams],
-    queryFn: async () => {
-      const response = await axios.get<{ photos: Photo[]; total: number }>(
-        'http://localhost:8001/api/v1/photos',
-        {
-          params: {
-            page: 1,
-            per_page: 500,
-            ...filterParams,
-          },
-        }
-      )
-      return response.data.photos || []
-    },
-    staleTime: 30_000,
-  })
-}

frontend/src/index.css

@@ -1,43 +0,0 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer base {
-  :root {
-    --color-bg: #111110;
-    --color-surface: #161615;
-    --color-surface-2: #1c1c1a;
-    --color-surface-offset: #222220;
-    --color-border: rgba(255, 255, 255, 0.08);
-    --color-text: #e8e6e0;
-    --color-text-muted: #878580;
-    --color-text-faint: #4a4845;
-    --color-primary: #4f98a3;
-    --color-pick: #4f9e5c;
-    --color-reject: #c25a5a;
-    --color-star: #d4a340;
-  }
-
-  body {
-    @apply bg-bg text-text;
-    font-family: 'Geist', system-ui, sans-serif;
-  }
-}
-
-/* Custom scrollbar styles */
-::-webkit-scrollbar {
-  width: 8px;
-  height: 8px;
-}
-
-::-webkit-scrollbar-track {
-  @apply bg-surface;
-}
-
-::-webkit-scrollbar-thumb {
-  @apply bg-surface-offset rounded;
-}
-
-::-webkit-scrollbar-thumb:hover {
-  @apply bg-text-faint;
-}

frontend/src/main.tsx

@@ -1,24 +0,0 @@
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
-import App from './App'
-import './index.css'
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 5 * 60 * 1000, // 5 minutes
-      retry: 2,
-    },
-  },
-})
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <QueryClientProvider client={queryClient}>
-      <App />
-      <ReactQueryDevtools initialIsOpen={false} />
-    </QueryClientProvider>
-  </React.StrictMode>,
-)

frontend/src/services/api.ts

@@ -1,222 +0,0 @@
-import axios from 'axios'
-
-const API_BASE_URL = 'http://localhost:8001/api/v1'
-
-const api = axios.create({
-  baseURL: API_BASE_URL,
-  headers: {
-    'Content-Type': 'application/json',
-  },
-})
-
-// Source Folders API
-export const sourceFolders = {
-  list: async () => {
-    const response = await api.get('/folders')
-    return response.data
-  },
-
-  add: async (path: string, recursive: boolean = true) => {
-    const response = await api.post('/folders', {
-      path,
-      recursive,
-      watch: false, // Can be made configurable later
-    })
-    return response.data
-  },
-
-  scan: async (folderId: string) => {
-    const response = await api.post(`/folders/${folderId}/scan`)
-    return response.data
-  },
-
-  delete: async (folderId: string) => {
-    const response = await api.delete(`/folders/${folderId}`)
-    return response.data
-  },
-}
-
-// Photos API
-export const photos = {
-  list: async (params?: {
-    limit?: number
-    offset?: number
-    folder_id?: string
-    heap_id?: string
-    rating?: number
-    flag?: string
-  }) => {
-    const response = await api.get('/photos', { params })
-    return response.data
-  },
-
-  get: async (photoId: string) => {
-    const response = await api.get(`/photos/${photoId}`)
-    return response.data
-  },
-
-  update: async (photoId: string, data: {
-    filename?: string
-    rating?: number
-    user_title?: string | null
-    user_notes?: string | null
-    color_label?: string | null
-    is_picked?: boolean
-    is_discarded?: boolean
-    taken_at?: string
-  }) => {
-    const response = await api.patch(`/photos/${photoId}`, data)
-    return response.data
-  },
-
-  bulkUpdate: async (photoIds: string[], data: {
-    rating?: number
-    flag?: string
-    heap_id?: string
-    discard?: boolean
-  }) => {
-    const response = await api.post('/photos/bulk', {
-      photo_ids: photoIds,
-      ...data,
-    })
-    return response.data
-  },
-
-  getThumbnailUrl: (photoId: string, size: 'small' | 'medium' | 'large' = 'medium') => {
-    return `${API_BASE_URL}/photos/${photoId}/thumb/${size}`
-  },
-
-  getOriginalUrl: (photoId: string) => {
-    return `${API_BASE_URL}/photos/${photoId}/original`
-  },
-
-  /** Full-resolution display URL. Backend serves the original for web-safe
-   *  formats and a transcoded WebP for RAW/HEIC/TIFF. */
-  getProxyUrl: (photoId: string) => {
-    return `${API_BASE_URL}/photos/${photoId}/proxy`
-  },
-}
-
-// Library API
-export const library = {
-  scan: async () => {
-    const response = await api.post('/library/scan')
-    return response.data
-  },
-
-  scanStatus: async () => {
-    const response = await api.get('/library/scan/status')
-    return response.data
-  },
-
-  stats: async () => {
-    const response = await api.get('/library/stats')
-    return response.data
-  },
-}
-
-// Heaps API
-export interface Heap {
-  id: string
-  name: string
-  is_active: boolean
-  created_at: string
-  updated_at: string | null
-  photo_count: number
-}
-
-export const heaps = {
-  list: async (): Promise<Heap[]> => {
-    const response = await api.get('/heaps')
-    return response.data
-  },
-
-  create: async (name: string): Promise<Heap> => {
-    const response = await api.post('/heaps', { name })
-    return response.data
-  },
-
-  update: async (
-    heapId: string,
-    data: { name?: string; is_active?: boolean }
-  ): Promise<Heap> => {
-    const response = await api.patch(`/heaps/${heapId}`, data)
-    return response.data
-  },
-
-  delete: async (heapId: string): Promise<void> => {
-    await api.delete(`/heaps/${heapId}`)
-  },
-
-  /** Lightweight: just the photo ids in a heap, for client-side membership
-   *  lookups (the basket affordance on thumbnails). */
-  photoIds: async (heapId: string): Promise<string[]> => {
-    const response = await api.get(`/heaps/${heapId}/photo_ids`)
-    return response.data
-  },
-
-  addPhotos: async (heapId: string, photoIds: string[]) => {
-    const response = await api.post(`/heaps/${heapId}/photos`, {
-      photo_ids: photoIds,
-    })
-    return response.data
-  },
-
-  removePhotos: async (heapId: string, photoIds: string[]) => {
-    const response = await api.delete(`/heaps/${heapId}/photos`, {
-      data: { photo_ids: photoIds },
-    })
-    return response.data
-  },
-}
-
-// Tags API
-export const tags = {
-  list: async () => {
-    const response = await api.get('/tags')
-    return response.data
-  },
-
-  create: async (name: string, color?: string) => {
-    const response = await api.post('/tags', {
-      name,
-      color,
-    })
-    return response.data
-  },
-
-  update: async (tagId: string, data: {
-    name?: string
-    color?: string
-  }) => {
-    const response = await api.patch(`/tags/${tagId}`, data)
-    return response.data
-  },
-
-  delete: async (tagId: string) => {
-    const response = await api.delete(`/tags/${tagId}`)
-    return response.data
-  },
-}
-
-// Discard API
-export const discard = {
-  list: async () => {
-    const response = await api.get('/discard')
-    return response.data
-  },
-
-  restore: async (photoIds: string[]) => {
-    const response = await api.post('/discard/restore', {
-      photo_ids: photoIds,
-    })
-    return response.data
-  },
-
-  empty: async () => {
-    const response = await api.delete('/discard/empty')
-    return response.data
-  },
-}
-
-export default api

frontend/src/store/filterStore.ts

@@ -1,129 +0,0 @@
-import { create } from 'zustand'
-
-export type MediaType = 'photo' | 'video' | 'raw' | 'heic'
-export type ColorLabel = 'red' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple'
-export type FlagFilter = 'any' | 'discarded'
-export type SortField =
-  | 'taken_at'
-  | 'added_at'
-  | 'filename'
-  | 'file_size'
-  | 'rating'
-export type SortOrder = 'asc' | 'desc'
-
-export interface FilterState {
-  q: string
-  dateFrom: string | null // ISO yyyy-mm-dd
-  dateTo: string | null
-  mediaTypes: MediaType[]
-  ratingMin: number // 0-5; 0 means no filter
-  colorLabel: ColorLabel | null
-  flag: FlagFilter
-  /** When set, restrict to photos in this heap. Independent of `activeHeapId`
-   *  on the heap store — that's the target for the T shortcut. */
-  heapId: string | null
-  /** When set, restrict to photos in this folder. */
-  folderId: string | null
-  sortBy: SortField
-  sortOrder: SortOrder
-}
-
-interface FilterStore extends FilterState {
-  filterBarOpen: boolean
-
-  setQ: (q: string) => void
-  setDateFrom: (date: string | null) => void
-  setDateTo: (date: string | null) => void
-  toggleMediaType: (t: MediaType) => void
-  setRatingMin: (rating: number) => void
-  setColorLabel: (label: ColorLabel | null) => void
-  setFlag: (flag: FlagFilter) => void
-  setHeapId: (id: string | null) => void
-  setFolderId: (id: string | null) => void
-  setSortBy: (field: SortField) => void
-  setSortOrder: (order: SortOrder) => void
-  toggleSortOrder: () => void
-
-  setFilterBarOpen: (open: boolean) => void
-  toggleFilterBar: () => void
-
-  hydrate: (partial: Partial<FilterState>) => void
-  clearAll: () => void
-}
-
-export const INITIAL_FILTERS: FilterState = {
-  q: '',
-  dateFrom: null,
-  dateTo: null,
-  mediaTypes: [],
-  ratingMin: 0,
-  colorLabel: null,
-  flag: 'any',
-  heapId: null,
-  folderId: null,
-  sortBy: 'taken_at',
-  sortOrder: 'desc',
-}
-
-export const useFilterStore = create<FilterStore>((set) => ({
-  ...INITIAL_FILTERS,
-  filterBarOpen: false,
-
-  setQ: (q) => set({ q }),
-  setDateFrom: (dateFrom) => set({ dateFrom }),
-  setDateTo: (dateTo) => set({ dateTo }),
-  toggleMediaType: (t) =>
-    set((s) => ({
-      mediaTypes: s.mediaTypes.includes(t)
-        ? s.mediaTypes.filter((x) => x !== t)
-        : [...s.mediaTypes, t],
-    })),
-  setRatingMin: (ratingMin) => set({ ratingMin }),
-  setColorLabel: (colorLabel) => set({ colorLabel }),
-  setFlag: (flag) => set({ flag }),
-  setHeapId: (heapId) => set({ heapId }),
-  setFolderId: (folderId) => set({ folderId }),
-  setSortBy: (sortBy) => set({ sortBy }),
-  setSortOrder: (sortOrder) => set({ sortOrder }),
-  toggleSortOrder: () =>
-    set((s) => ({ sortOrder: s.sortOrder === 'desc' ? 'asc' : 'desc' })),
-
-  setFilterBarOpen: (filterBarOpen) => set({ filterBarOpen }),
-  toggleFilterBar: () => set((s) => ({ filterBarOpen: !s.filterBarOpen })),
-
-  hydrate: (partial) => set(partial),
-  clearAll: () => set({ ...INITIAL_FILTERS }),
-}))
-
-/** Convert filter state to the query params the backend list endpoint expects.
- *  Empty / default values are omitted so the cache key is stable. */
-export function filtersToParams(f: FilterState): Record<string, string | number> {
-  const params: Record<string, string | number> = {}
-  if (f.q.trim()) params.q = f.q.trim()
-  if (f.dateFrom) params.date_from = f.dateFrom
-  if (f.dateTo) params.date_to = f.dateTo
-  if (f.mediaTypes.length > 0) params.media_type = f.mediaTypes.join(',')
-  if (f.ratingMin > 0) params.rating_min = f.ratingMin
-  if (f.colorLabel) params.color_label = f.colorLabel
-  if (f.flag === 'discarded') params.is_discarded = 'true'
-  if (f.heapId) params.heap_id = f.heapId
-  if (f.folderId) params.folder_id = f.folderId
-  params.sort = f.sortBy
-  params.order = f.sortOrder
-  return params
-}
-
-/** True if any filter (other than the search box) is active. */
-export function hasActiveFilters(f: FilterState): boolean {
-  return (
-    f.q.trim() !== '' ||
-    f.dateFrom !== null ||
-    f.dateTo !== null ||
-    f.mediaTypes.length > 0 ||
-    f.ratingMin > 0 ||
-    f.colorLabel !== null ||
-    f.flag !== 'any' ||
-    f.heapId !== null ||
-    f.folderId !== null
-  )
-}

frontend/src/store/photoStore.ts

@@ -1,79 +0,0 @@
-import { create } from 'zustand'
-import type { Photo } from '../types/photo'
-
-type ViewMode = 'grid' | 'preview'
-
-interface PhotoStore {
-  photos: Photo[]
-  selectedPhotos: string[]
-  activePhotoId: string | null
-  lastSelectedIndex: number | null
-  rangeStartIndex: number | null
-  viewMode: ViewMode
-
-  setPhotos: (photos: Photo[]) => void
-  selectPhoto: (id: string, index: number) => void
-  togglePhotoSelection: (id: string, index: number) => void
-  selectRange: (endIndex: number) => void
-  deselectPhoto: (id: string) => void
-  clearSelection: () => void
-  setActivePhoto: (id: string | null) => void
-  setViewMode: (mode: ViewMode) => void
-  openPreview: (id: string) => void
-  closePreview: () => void
-}
-
-export const usePhotoStore = create<PhotoStore>((set) => ({
-  photos: [],
-  selectedPhotos: [],
-  activePhotoId: null,
-  lastSelectedIndex: null,
-  rangeStartIndex: null,
-  viewMode: 'grid',
-
-  setPhotos: (photos) => set({ photos }),
-  
-  selectPhoto: (id, index) => set({
-    selectedPhotos: [id],
-    activePhotoId: id,
-    lastSelectedIndex: index,
-    rangeStartIndex: index,
-  }),
-  
-  togglePhotoSelection: (id, index) => set((state) => {
-    const isSelected = state.selectedPhotos.includes(id)
-    return {
-      selectedPhotos: isSelected
-        ? state.selectedPhotos.filter(photoId => photoId !== id)
-        : [...state.selectedPhotos, id],
-      lastSelectedIndex: index,
-      rangeStartIndex: isSelected ? state.rangeStartIndex : index,
-    }
-  }),
-  
-  selectRange: (endIndex) => {
-    // Note: The actual range selection logic should be handled in the Timeline component
-    // which has access to the photos array
-    set({
-      lastSelectedIndex: endIndex,
-    })
-  },
-  
-  deselectPhoto: (id) => set((state) => ({
-    selectedPhotos: state.selectedPhotos.filter(photoId => photoId !== id)
-  })),
-  
-  clearSelection: () => set({ 
-    selectedPhotos: [],
-    lastSelectedIndex: null,
-    rangeStartIndex: null,
-  }),
-  
-  setActivePhoto: (id) => set({ activePhotoId: id }),
-
-  setViewMode: (mode) => set({ viewMode: mode }),
-
-  openPreview: (id) => set({ viewMode: 'preview', activePhotoId: id }),
-
-  closePreview: () => set({ viewMode: 'grid' }),
-}))

frontend/src/types/images.d.ts

@@ -1,29 +0,0 @@
-declare module '*.png' {
-  const value: string;
-  export default value;
-}
-
-declare module '*.jpg' {
-  const value: string;
-  export default value;
-}
-
-declare module '*.jpeg' {
-  const value: string;
-  export default value;
-}
-
-declare module '*.gif' {
-  const value: string;
-  export default value;
-}
-
-declare module '*.svg' {
-  const value: string;
-  export default value;
-}
-
-declare module '*.webp' {
-  const value: string;
-  export default value;
-}

frontend/src/types/photo.ts

@@ -1,15 +0,0 @@
-export interface Photo {
-  id: string
-  filepath: string
-  filename: string
-  media_type: string
-  width: number | null
-  height: number | null
-  taken_at: string | null
-  rating: number
-  is_discarded: boolean
-  file_hash: string
-  thumb_small?: string
-  thumb_medium?: string
-  thumb_large?: string
-}

frontend/tailwind.config.js

@@ -1,51 +0,0 @@
-/** @type {import('tailwindcss').Config} */
-export default {
-  content: [
-    "./index.html",
-    "./src/**/*.{js,ts,jsx,tsx}",
-  ],
-  darkMode: 'class',
-  theme: {
-    extend: {
-      colors: {
-        // Dark-first color scheme for photo apps
-        bg: '#111110',
-        surface: '#161615',
-        'surface-2': '#1c1c1a',
-        'surface-offset': '#222220',
-        border: 'rgba(255,255,255,0.08)',
-        text: '#e8e6e0',
-        'text-muted': '#878580',
-        'text-faint': '#4a4845',
-        primary: '#4f98a3', // desaturated teal
-        pick: '#4f9e5c',    // green for picked
-        reject: '#c25a5a',  // red for rejected
-        star: '#d4a340',    // amber for stars
-      },
-      fontFamily: {
-        sans: ['Geist', 'system-ui', 'sans-serif'],
-        mono: ['Geist Mono', 'monospace'],
-      },
-      animation: {
-        'fade-in': 'fadeIn 0.2s ease-in-out',
-        'slide-up': 'slideUp 0.3s ease-out',
-        'shimmer': 'shimmer 2s infinite linear',
-      },
-      keyframes: {
-        fadeIn: {
-          '0%': { opacity: '0' },
-          '100%': { opacity: '1' },
-        },
-        slideUp: {
-          '0%': { transform: 'translateY(20px)', opacity: '0' },
-          '100%': { transform: 'translateY(0)', opacity: '1' },
-        },
-        shimmer: {
-          '0%': { backgroundPosition: '-200% 0' },
-          '100%': { backgroundPosition: '200% 0' },
-        },
-      },
-    },
-  },
-  plugins: [],
-}

frontend/tsconfig.json

@@ -1,31 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "useDefineForClassFields": true,
-    "lib": ["ES2020", "DOM", "DOM.Iterable"],
-    "module": "ESNext",
-    "skipLibCheck": true,
-
-    /* Bundler mode */
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "noEmit": true,
-    "jsx": "react-jsx",
-
-    /* Linting */
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true,
-
-    /* Path mapping */
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["src/*"]
-    }
-  },
-  "include": ["src"],
-  "references": [{ "path": "./tsconfig.node.json" }]
-}

frontend/tsconfig.node.json

@@ -1,10 +0,0 @@
-{
-  "compilerOptions": {
-    "composite": true,
-    "skipLibCheck": true,
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "allowSyntheticDefaultImports": true
-  },
-  "include": ["vite.config.ts"]
-}

frontend/vite.config.ts

@@ -1,22 +0,0 @@
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import path from 'path'
-
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [react()],
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, './src'),
-    },
-  },
-  server: {
-    port: 5173,
-    proxy: {
-      '/api': {
-        target: 'http://localhost:8000',
-        changeOrigin: true,
-      },
-    },
-  },
-})

mariadb/init/01-sidecar.sql

@@ -0,0 +1,25 @@
+-- Bootstraps the `mule_sidecar` database + user used by the Go sidecar
+-- service (per-user heap sharing + folder mutations, stood up in M4).
+--
+-- MariaDB runs every .sql in /docker-entrypoint-initdb.d ONCE, on first
+-- boot of a fresh data volume. Subsequent boots are no-ops.
+--
+-- The sidecar's MariaDB user is intentionally scoped to `mule_sidecar.*`
+-- only — it never has access to PhotoPrism's schema.
+
+CREATE DATABASE IF NOT EXISTS mule_sidecar
+  CHARACTER SET utf8mb4
+  COLLATE utf8mb4_unicode_ci;
+
+-- The password here is substituted at compose build time via envsubst,
+-- but MariaDB's init script doesn't expand vars in .sql files. So we use
+-- a literal placeholder that the user replaces locally — or, simpler,
+-- we let the M4 sidecar bring-up script create the user via SQL with the
+-- env-var password. Keeping a placeholder here makes the schema visible
+-- in source control without leaking creds.
+--
+-- TODO (M4): replace this block with an entrypoint that templates the
+-- password from $SIDECAR_DB_PASSWORD before MariaDB reads the file.
+CREATE USER IF NOT EXISTS 'sidecar'@'%' IDENTIFIED BY 'replace-at-m4-bringup';
+GRANT ALL PRIVILEGES ON mule_sidecar.* TO 'sidecar'@'%';
+FLUSH PRIVILEGES;

mulita.yml

@@ -1,30 +0,0 @@
-# Mulita configuration file
-
-source_roots:
-  - name: "Main Library"
-    path: /photos/main
-  - name: "iPhone Imports"
-    path: /photos/iphone
-
-thumbnails:
-  small: 240      # px, longest edge
-  medium: 640
-  large: 1280
-  quality: 85     # JPEG/WebP quality
-  format: webp    # output format for thumbs
-
-scanner:
-  watch: true     # use watchfiles inotify
-  initial_scan_on_start: true
-  batch_size: 100
-  concurrent_workers: 4
-
-trash:
-  path: /data/trash
-  auto_empty_days: 30  # auto-delete after 30 days in trash
-
-performance:
-  max_concurrent_thumbnails: 10
-  cache_ttl: 3600
-  db_pool_size: 20
-  db_pool_recycle: 3600

photovault-app-prompt.md

@@ -1,753 +0,0 @@
-# PhotoVault — Full Application Spec Prompt
-
-> A self-hosted, Docker-deployed photo management application inspired by Lightroom's workflow.
-> Use this document as the complete specification to build the app from scratch.
-
----
-
-## 1. Project Overview
-
-Build **PhotoVault**, a self-hosted photo & video management web application optimized for a single-user homelab deployment. The user mounts one or more host folders containing photos/videos; the app indexes them, generates thumbnails, and provides a fast keyboard-driven interface to browse, organize, tag, and manage the library. The architecture must be forward-compatible with AI photo recognition features (face detection, scene classification, CLIP embeddings) to be added in a later phase.
-
----
-
-## 2. Stack & Deployment
-
-### 2.1 Docker Compose (single `docker-compose.yml`)
-
-```
-services:
-  frontend   — React SPA (Nginx)
-  backend    — Python FastAPI
-  db         — SQLite (file-based, volume-mounted)
-  worker     — Celery + Redis for background thumbnail/indexing tasks
-  redis      — Redis (Celery broker)
-```
-
-All services declared in one `docker-compose.yml`. Use named volumes for:
-- `/data/thumbs` — generated thumbnails (persistent)
-- `/data/db` — SQLite database file
-- `/data/trash` — files moved to trash
-
-Photo source folders are mounted as **read-write** bind mounts via an environment variable:
-
-```yaml
-volumes:
-  - ${PHOTO_DIRS}:/photos:rw
-```
-
-`PHOTO_DIRS` supports multiple paths via a config file (`photovault.yml`) described in §4.
-
-### 2.2 Frontend
-
-- **React 18** + **Vite**
-- **Tailwind CSS v4**
-- **shadcn/ui** component library
-- **TanStack Query** (React Query) for data fetching & cache
-- **TanStack Virtual** for virtualized scrolling (critical for performance with thousands of photos)
-- **Zustand** for global UI state (selection, active photo, heap, filters)
-- **Framer Motion** for transitions
-
-### 2.3 Backend
-
-- **Python 3.12 + FastAPI**
-- **SQLite** via **SQLAlchemy 2.0** (async) + **Alembic** for migrations
-- **Celery + Redis** for background tasks (thumbnail generation, folder scanning, metadata extraction)
-- **pyvips** (libvips) for fast thumbnail generation — preferred over Pillow for speed at scale
-- **rawpy** for RAW format decoding (CR2, CR3, NEF, ARW, RAF, DNG, ORF, RW2, etc.)
-- **pillow-heif** for HEIC/HEIF (iPhone photos)
-- **ffmpeg** (via `ffmpeg-python`) for video thumbnail extraction and metadata
-- **pyexiftool** (wraps ExifTool binary) for deep metadata extraction from all formats
-- **Watchfiles** for inotify-based folder watching (auto-detect new/deleted files)
-
-> **AI-readiness note**: The backend worker architecture is designed to add a `clip_embed` task later (using `open-clip-torch`) that stores 512-dim CLIP embeddings per photo in the DB. Reserve a `embeddings` table with a `photo_id` FK and a `BLOB` column for the vector. No AI code yet — just the schema placeholder.
-
----
-
-## 3. Data Model (SQLite via SQLAlchemy)
-
-```sql
--- Core tables
-
-photos (
-  id            TEXT PRIMARY KEY,   -- UUID
-  filepath      TEXT UNIQUE NOT NULL,
-  filename      TEXT NOT NULL,
-  folder_id     TEXT REFERENCES folders(id),
-  media_type    TEXT NOT NULL,      -- 'photo' | 'video' | 'raw' | 'heic'
-  original_format TEXT,            -- 'CR3', 'NEF', 'HEIC', 'MP4', 'JPEG', etc.
-  width         INTEGER,
-  height        INTEGER,
-  file_size     INTEGER,
-  taken_at      DATETIME,          -- from EXIF DateTimeOriginal, fallback to file mtime
-  taken_at_source TEXT,            -- 'exif' | 'filesystem' | 'manual'
-  added_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
-  updated_at    DATETIME,
-  is_trashed    BOOLEAN DEFAULT 0,
-  trashed_at    DATETIME,
-  thumb_small   TEXT,              -- path to 240px thumb
-  thumb_medium  TEXT,              -- path to 640px thumb
-  thumb_large   TEXT,              -- path to 1280px thumb
-  exif_json     TEXT,              -- full EXIF/XMP blob as JSON
-  user_title    TEXT,              -- user-edited title
-  user_notes    TEXT,
-  rating        INTEGER DEFAULT 0, -- 0-5 stars
-  color_label   TEXT,              -- 'red'|'orange'|'yellow'|'green'|'blue'|'purple'|NULL
-  is_picked     BOOLEAN DEFAULT 0,
-  is_rejected   BOOLEAN DEFAULT 0
-)
-
-folders (
-  id            TEXT PRIMARY KEY,
-  name          TEXT NOT NULL,
-  path          TEXT UNIQUE NOT NULL,
-  parent_id     TEXT REFERENCES folders(id),
-  source_root_id TEXT REFERENCES source_roots(id),
-  photo_count   INTEGER DEFAULT 0,
-  last_scanned  DATETIME
-)
-
-source_roots (
-  id            TEXT PRIMARY KEY,
-  name          TEXT NOT NULL,
-  path          TEXT UNIQUE NOT NULL,
-  is_active     BOOLEAN DEFAULT 1,
-  added_at      DATETIME DEFAULT CURRENT_TIMESTAMP
-)
-
-tags (
-  id            TEXT PRIMARY KEY,
-  name          TEXT UNIQUE NOT NULL,
-  color         TEXT
-)
-
-photo_tags (
-  photo_id      TEXT REFERENCES photos(id) ON DELETE CASCADE,
-  tag_id        TEXT REFERENCES tags(id) ON DELETE CASCADE,
-  PRIMARY KEY (photo_id, tag_id)
-)
-
-heaps (
-  id            TEXT PRIMARY KEY,
-  name          TEXT NOT NULL,
-  created_at    DATETIME DEFAULT CURRENT_TIMESTAMP,
-  updated_at    DATETIME
-)
-
-heap_photos (
-  heap_id       TEXT REFERENCES heaps(id) ON DELETE CASCADE,
-  photo_id      TEXT REFERENCES photos(id) ON DELETE CASCADE,
-  added_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
-  sort_order    INTEGER DEFAULT 0,
-  PRIMARY KEY (heap_id, photo_id)
-)
-
--- AI-readiness placeholder (no implementation yet)
-embeddings (
-  photo_id      TEXT PRIMARY KEY REFERENCES photos(id) ON DELETE CASCADE,
-  model         TEXT,              -- e.g. 'clip-vit-b32'
-  vector        BLOB               -- raw float32 bytes
-)
-```
-
-**Indexes**: Create indexes on `photos.taken_at`, `photos.folder_id`, `photos.is_trashed`, `photos.rating`, `photos.color_label`, `photo_tags.tag_id`.
-
----
-
-## 4. Configuration
-
-App is configured via a `photovault.yml` file mounted into the backend container:
-
-```yaml
-source_roots:
-  - name: "Main Library"
-    path: /photos/main
-  - name: "iPhone Imports"
-    path: /photos/iphone
-
-thumbnails:
-  small: 240      # px, longest edge
-  medium: 640
-  large: 1280
-  quality: 85     # JPEG quality
-  format: webp    # output format for thumbs
-
-scanner:
-  watch: true     # use watchfiles inotify
-  initial_scan_on_start: true
-
-trash:
-  path: /data/trash
-```
-
----
-
-## 5. Backend API (FastAPI)
-
-All routes under `/api/v1/`. Authentication: none (single-user, homelab). Use async SQLAlchemy sessions.
-
-### 5.1 Photos
-
-```
-GET    /photos                   List photos (pagination + filters — see §5.5)
-GET    /photos/{id}              Get single photo with full EXIF + tags
-GET    /photos/{id}/thumb/{size} Serve thumbnail (small|medium|large) — use X-Accel-Redirect for Nginx
-GET    /photos/{id}/original     Serve original file (download)
-PATCH  /photos/{id}             Update: user_title, user_notes, rating, color_label, is_picked, is_rejected, taken_at (manual override)
-DELETE /photos/{id}             Move to trash (sets is_trashed=1, moves file to /data/trash)
-POST   /photos/bulk             Bulk actions: { ids: [], action: 'trash'|'restore'|'delete_permanent'|'move'|'copy'|'add_tag'|'remove_tag'|'set_rating'|'set_color'|'pick'|'reject' }
-POST   /photos/bulk/move        Move files to a target folder_id
-POST   /photos/bulk/copy        Copy files to a target folder_id
-```
-
-### 5.2 Folders
-
-```
-GET    /folders                  Folder tree (nested, with photo_count)
-GET    /folders/{id}/photos      Photos in folder (supports same filters as /photos)
-POST   /folders                  Create folder (creates directory on disk)
-PATCH  /folders/{id}             Rename folder (renames directory on disk)
-DELETE /folders/{id}             Delete folder — requires folder to be empty
-POST   /folders/{id}/scan        Trigger manual re-scan of folder
-```
-
-### 5.3 Heaps
-
-```
-GET    /heaps                    List all heaps
-POST   /heaps                    Create heap { name }
-GET    /heaps/{id}               Get heap with photos
-PATCH  /heaps/{id}               Rename heap
-DELETE /heaps/{id}               Delete heap (does NOT delete photos)
-POST   /heaps/{id}/photos        Add photos { photo_ids: [] }
-DELETE /heaps/{id}/photos        Remove photos { photo_ids: [] }
-POST   /heaps/{id}/convert       Convert heap to folder on disk: { target_path, move: bool }
-```
-
-### 5.4 Tags
-
-```
-GET    /tags                     List all tags with usage counts
-POST   /tags                     Create tag
-PATCH  /tags/{id}                Rename / recolor tag
-DELETE /tags/{id}                Delete tag (removes from all photos)
-GET    /tags/{id}/photos         Photos with this tag
-```
-
-### 5.5 Filters & Search
-
-All list endpoints support these query parameters:
-
-```
-q              Full-text search (filename, user_title, user_notes, EXIF JSON)
-date_from      ISO8601 datetime
-date_to        ISO8601 datetime
-folder_id      Filter by folder (recursive if include_subfolders=true)
-tag_ids        Comma-separated tag IDs (AND logic by default; mode=or for OR)
-media_type     photo|video|raw|heic (comma-separated for multiple)
-rating_min     0-5
-rating_max     0-5
-color_label    red|orange|yellow|green|blue|purple|none
-is_picked      true|false
-is_rejected    true|false
-is_trashed     true|false (default false)
-heap_id        Filter to photos in a specific heap
-sort           taken_at|added_at|filename|file_size|rating (default taken_at)
-order          asc|desc (default desc)
-page           integer (default 1)
-per_page       integer (default 100, max 500)
-```
-
-Full-text search uses SQLite FTS5. Create a virtual FTS table:
-```sql
-CREATE VIRTUAL TABLE photos_fts USING fts5(
-  photo_id UNINDEXED,
-  filename,
-  user_title,
-  user_notes,
-  exif_text  -- denormalized key EXIF fields as plain text (camera make/model, GPS, lens, etc.)
-);
-```
-
-### 5.6 Trash
-
-```
-GET    /trash                    List trashed photos (same filters)
-POST   /trash/restore            Restore { photo_ids: [] } — moves files back to original folder
-DELETE /trash/empty              Permanently delete all trashed photos + files
-DELETE /trash/{id}               Permanently delete single photo + file
-```
-
-### 5.7 Library Stats & Scanning
-
-```
-GET    /library/stats            { total_photos, total_videos, total_size, last_scan }
-POST   /library/scan             Trigger full re-scan (Celery task)
-GET    /library/scan/status      { status, progress, current_folder, queued, done }
-```
-
-### 5.8 Background Tasks (Celery)
-
-- `scan_folder(folder_path)` — Walk directory tree, insert/update photos, detect deletions
-- `generate_thumbs(photo_id)` — Generate small/medium/large WebP thumbnails via pyvips/rawpy/ffmpeg
-- `extract_metadata(photo_id)` — Run ExifTool, parse EXIF/XMP/IPTC, update DB
-- `watch_folders()` — Long-running Watchfiles task, dispatches scan_folder on changes
-- `embed_photo(photo_id)` *(placeholder, no-op)* — Reserved for CLIP embeddings
-
-**Priority queues**: Thumbnail generation for visible photos should be on a `high` queue; full library scans on a `low` queue.
-
----
-
-## 6. Frontend Architecture
-
-### 6.1 Layout
-
-Three-pane layout (similar to Lightroom Library module):
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  TOP BAR  [Logo] [Search] [Filters bar] [View mode] [Heap]  │
-├──────────┬──────────────────────────────────┬───────────────┤
-│          │                                  │               │
-│  LEFT    │        MAIN TIMELINE             │  RIGHT        │
-│  SIDEBAR │     (continuous scroll,          │  SIDEBAR      │
-│          │      sticky date headers,        │  (metadata    │
-│  Folder  │      virtualized thumbnail       │   panel for   │
-│  tree    │      grid)                       │   selected    │
-│          │                                  │   photo)      │
-│  Heaps   │                                  │               │
-│  list    │                                  │               │
-│          │                                  │               │
-│  Tags    │                                  │               │
-└──────────┴──────────────────────────────────┴───────────────┘
-```
-
-- Left sidebar: resizable, collapsible (shortcut: `Tab`)
-- Right sidebar: collapsible (shortcut: `I`), shows when ≥1 photo selected
-- Main area: full virtualized scroll, single scroll region
-
-### 6.2 Views
-
-| View | Shortcut | Description |
-|------|----------|-------------|
-| Grid (Library) | `G` | Default timeline thumbnail grid |
-| Loupe (Fullscreen) | `E` | Single photo full-viewport view |
-| Compare | `C` | Side-by-side compare of 2 selected photos |
-
-### 6.3 Timeline View (Grid)
-
-- **Continuous vertical scroll** with **sticky date headers** that label each date group (Year / Month / Day — configurable via a "Group by" dropdown: Year, Month, Day, Week, Folder)
-- Thumbnails rendered via **TanStack Virtual** — only DOM nodes in/near viewport are rendered
-- Thumbnail grid is **responsive** — uses CSS grid with `auto-fill` and configurable thumbnail size (slider or `+/-` keys)
-- Thumbnails show: image, hover overlay with filename, EXIF date, optional rating stars
-- **Lazy thumbnail loading**: request `thumb_small` initially; upgrade to `thumb_medium` on hover/selection
-- On initial scan, show a shimmer skeleton for photos without thumbnails yet; poll backend for thumb completion
-
-### 6.4 Keyboard Shortcuts (Lightroom-style)
-
-#### Navigation (Grid mode)
-| Key | Action |
-|-----|--------|
-| `←` `→` `↑` `↓` | Move cursor one photo in direction |
-| `Shift+←/→/↑/↓` | Extend selection |
-| `Cmd/Ctrl+A` | Select all |
-| `Cmd/Ctrl+Shift+A` | Deselect all |
-| `Space` | Quick preview (fullscreen loupe, hold) |
-| `Enter` | Open loupe view |
-| `Esc` | Deselect / close loupe |
-| `Home` / `End` | Jump to first / last photo |
-| `Page Up/Down` | Scroll by screen height |
-
-#### Navigation (Loupe mode)
-| Key | Action |
-|-----|--------|
-| `←` `→` | Previous / next photo |
-| `Esc` | Return to grid |
-| `Z` | Toggle zoom (fit ↔ 100%) |
-| `+` / `-` | Zoom in / out |
-
-#### Flagging & Rating
-| Key | Action |
-|-----|--------|
-| `P` | Pick (flag) |
-| `X` | Reject |
-| `U` | Unflag |
-| `1–5` | Set star rating |
-| `0` | Remove star rating |
-| `6` | Red label |
-| `7` | Orange label |
-| `8` | Yellow label |
-| `9` | Green label |
-
-#### Actions
-| Key | Action |
-|-----|--------|
-| `G` | Go to grid view |
-| `E` | Go to loupe view |
-| `C` | Compare view (2 selected) |
-| `Tab` | Toggle left sidebar |
-| `I` | Toggle right metadata sidebar |
-| `\` | Toggle filter bar |
-| `F` | Toggle fullscreen |
-| `Delete` | Move selected to trash |
-| `Shift+Delete` | Permanently delete (if in trash view) |
-| `Cmd/Ctrl+Z` | Undo last action |
-| `Cmd/Ctrl+Shift+Z` | Redo |
-| `Cmd/Ctrl+C` | Copy selected to clipboard (for move/copy target) |
-| `Cmd/Ctrl+X` | Cut selected (for move) |
-| `Cmd/Ctrl+V` | Paste into current folder |
-| `T` | Add/remove from active heap |
-| `Cmd/Ctrl+F` | Focus search bar |
-| `/` | Focus search bar |
-| `?` | Show keyboard shortcut reference overlay |
-
-All shortcuts must work without modifier unless noted. Shortcuts must be suppressed when focus is inside an input/textarea.
-
-### 6.5 Bulk Selection
-
-- **Click** — select single photo (deselects others)
-- **Shift+Click** — range select from last selected to clicked
-- **Cmd/Ctrl+Click** — toggle individual photo in selection
-- **Cmd/Ctrl+A** — select all visible
-- A **selection bar** appears at the top of the main area when ≥2 photos selected, showing count and bulk action buttons: Rate, Color Label, Tag, Add to Heap, Move, Copy, Trash, Export
-- Bulk actions call `POST /api/v1/photos/bulk`
-
-### 6.6 Metadata Sidebar (Right Panel)
-
-When a photo is selected, the right sidebar shows:
-
-**Section: Preview**
-- Large thumbnail (clicking opens loupe)
-- Filename (editable inline, renames file on disk)
-- User title (editable)
-- User notes (textarea)
-- Rating (5-star widget, keyboard-interactive)
-- Color label (color dot picker)
-- Flags: Picked / Rejected toggles
-
-**Section: Tags**
-- Tag chips with remove button
-- "Add tag" autocomplete input
-- Create new tag inline
-
-**Section: EXIF / Metadata**
-Collapsible groups:
-- *Camera*: Make, Model, Serial, Lens, Firmware
-- *Capture*: Date Taken (editable override), Shutter Speed, Aperture, ISO, Focal Length, EV, Flash, White Balance, Metering Mode
-- *File*: Format, Dimensions, File Size, Color Space, Bit Depth
-- *Location*: GPS lat/lon shown on a small Leaflet.js map tile if available; altitude, country, city (reverse-geocoded via nominatim.openstreetmap.org on demand)
-- *IPTC/XMP*: Copyright, Creator, Description, Keywords
-
-**Section: Histogram** (stretch goal)
-- Live RGB+Luminosity histogram rendered from a downsampled version of the photo
-
-### 6.7 Filter Bar
-
-A collapsible horizontal bar below the top bar (shortcut `\`). Contains:
-
-| Control | Type |
-|---------|------|
-| Date range | Date range picker (from/to) |
-| Media type | Multi-select chips: Photo / Video / RAW / HEIC |
-| Rating | Min/max star slider |
-| Color label | Color dot multi-select |
-| Flags | Picked / Rejected / Unflagged toggle buttons |
-| Tags | Multi-select tag dropdown (AND/OR mode toggle) |
-| Camera make | Dropdown (populated from DB) |
-| Lens | Dropdown (populated from DB) |
-
-Active filters shown as removable chips in the filter bar. "Clear all" button. Filter state persists in URL query params for shareability/bookmarks.
-
-### 6.8 Search
-
-- Magnifier icon in top bar, shortcut `/` or `Cmd+F`
-- Full-text search via FTS5 backend
-- Search covers: filename, user title, user notes, camera make/model, lens, GPS place names, tags
-- Results appear inline in the current view (no separate search results page)
-- Search combined with active filters (additive)
-
-### 6.9 Folder Tree (Left Sidebar)
-
-- Hierarchical tree view of all source roots and their subfolder structure
-- Each folder shows photo count badge
-- Right-click context menu: New Subfolder, Rename, Move Photos Here, Scan Now, Copy Path
-- Drag-and-drop folders to rearrange (moves directory on disk with confirmation)
-- "All Photos" virtual root node at top
-- "Trash" virtual node at bottom with count badge
-
-### 6.10 Heaps Panel (Left Sidebar)
-
-- List of named heaps below folder tree
-- "+ New Heap" button (creates unnamed heap, prompts for name)
-- Each heap shows photo count
-- Click heap → main area shows heap contents in grid
-- Right-click context menu: Rename, Convert to Folder (prompts for target path + move/copy choice), Delete Heap, Clear Heap
-- **Active Heap indicator**: One heap can be set as "active" (bold + icon). Pressing `T` adds/removes the selected photo(s) from the active heap.
-- A persistent "current heap" pill shown in the top bar when a heap is active
-
-### 6.11 Loupe View
-
-- Single photo, full-viewport
-- Original-quality image (served from backend, format-agnostic — backend transcodes RAW/HEIC to JPEG/WebP on the fly for web display)
-- Zoom: fit-to-window ↔ 100% (toggle `Z`), scroll wheel to zoom, drag to pan at 100%+
-- Filmstrip at bottom: horizontally scrollable strip of thumbnails (current context — same folder or heap), keyboard navigable
-- Left panel collapse, right metadata panel still accessible
-- For videos: HTML5 `<video>` player with controls, muted autoplay of preview, unmute toggle
-
-### 6.12 Trash View
-
-- Accessible via "Trash" node in sidebar
-- Same grid layout, same filters, same shortcuts
-- Extra actions in bulk selection bar: Restore, Permanently Delete
-- "Empty Trash" button at top with confirmation dialog showing count + total size
-
-### 6.13 Library Scan Progress
-
-- On first launch or manual scan trigger: a non-blocking progress bar in the top bar
-- Shows: `Scanning… 1,234 / 12,456 photos indexed`
-- Photos appear in the timeline as they are indexed (optimistic streaming via polling `GET /library/scan/status` every 2s)
-
----
-
-## 7. Media Handling
-
-### 7.1 Supported Formats
-
-| Category | Formats |
-|----------|---------|
-| JPEG | `.jpg`, `.jpeg` |
-| PNG | `.png` |
-| TIFF | `.tif`, `.tiff` |
-| WebP | `.webp` |
-| HEIC/HEIF | `.heic`, `.heif` (via pillow-heif) |
-| RAW — Canon | `.cr2`, `.cr3` |
-| RAW — Nikon | `.nef`, `.nrw` |
-| RAW — Sony | `.arw`, `.srf` |
-| RAW — Fuji | `.raf` |
-| RAW — Panasonic | `.rw2` |
-| RAW — Olympus | `.orf` |
-| RAW — Samsung | `.srw` |
-| RAW — Pentax | `.pef` |
-| RAW — Leica | `.rwl`, `.dng` |
-| RAW — DNG (universal) | `.dng` |
-| RAW — Others | via rawpy (libraw) fallback |
-| Video | `.mp4`, `.mov`, `.avi`, `.mkv`, `.mts`, `.m2ts`, `.3gp` |
-| Live Photos | `.heic` + `.mov` pair (detect by matching base filename) |
-
-### 7.2 Thumbnail Generation Pipeline
-
-For each photo during indexing:
-1. Detect format by extension + magic bytes
-2. Decode to in-memory RGB image:
-   - JPEG/PNG/TIFF/WebP → pyvips native
-   - HEIC/HEIF → pillow-heif → pyvips
-   - RAW → rawpy (half-size decode for speed) → numpy → pyvips
-   - Video → ffmpeg extract frame at 10% duration → pyvips
-3. Auto-rotate by EXIF orientation
-4. Generate 3 sizes: 240px, 640px, 1280px (longest edge, maintain AR)
-5. Save as WebP (quality 85) to `/data/thumbs/{photo_id}/{size}.webp`
-6. Update `thumb_small`, `thumb_medium`, `thumb_large` columns in DB
-
-For web display of original RAW/HEIC in loupe view: generate a full-res WebP proxy on demand (cached). Serve via `GET /photos/{id}/proxy`.
-
-### 7.3 Metadata Extraction
-
-Run ExifTool (subprocess) on every file during indexing. Parse output JSON. Store:
-- `taken_at` — prefer `DateTimeOriginal`, fallback: `CreateDate`, `MediaCreateDate`, file mtime
-- GPS coordinates if present
-- All EXIF/IPTC/XMP fields stored as JSON in `exif_json`
-- Denormalize key fields to FTS table for search
-
-For Live Photos: link the `.mov` sidecar to the `.heic` via a `live_photo_video_id` FK on the photos table.
-
----
-
-## 8. File Operations
-
-All file operations that touch disk must:
-1. Validate target path is within a known source_root (prevent path traversal)
-2. Execute atomically where possible (temp file + rename)
-3. Update DB after successful disk operation (never before)
-4. Emit a WebSocket event (or SSE) so the frontend can update optimistically
-5. Be undoable via Undo stack (store reverse operation in memory, max 50 ops)
-
-### Operations
-
-| Operation | Disk action | DB action |
-|-----------|-------------|-----------|
-| Move photos | `shutil.move` | Update `filepath`, `folder_id` |
-| Copy photos | `shutil.copy2` | Insert new photo record |
-| Rename file | `os.rename` | Update `filepath`, `filename` |
-| Rename folder | `os.rename` | Update folder `path` recursively |
-| Create folder | `os.makedirs` | Insert folder record |
-| Trash photo | Move to `/data/trash/{id}/original.{ext}` | Set `is_trashed=1`, `trashed_at` |
-| Restore from trash | Move back to original path (or new path if original gone) | Clear `is_trashed` |
-| Permanent delete | `os.unlink` | Delete photo record (cascade to tags, heaps) |
-| Convert heap to folder | `os.makedirs(target)` + move/copy each photo | Insert folder, update photo folder_id |
-
----
-
-## 9. Performance Requirements
-
-- **Initial page load**: < 2s (LCP)
-- **Timeline scroll** (10,000+ photos): 60 fps — enforced by TanStack Virtual (only ~20-30 DOM nodes rendered at any time)
-- **Thumbnail serve**: < 50ms via Nginx X-Accel-Redirect (backend sets header, Nginx serves file directly)
-- **Search**: < 200ms for FTS5 query on 100k photos
-- **Thumbnail generation**: ≥ 10 photos/sec on typical homelab CPU (pyvips is ~10x faster than Pillow)
-- **Scan throughput**: ≥ 500 files/sec metadata scan (ExifTool batch mode processes files in bulk)
-- **Celery workers**: 4 concurrent workers by default (`CELERYD_CONCURRENCY=4` env var)
-- Images not yet thumbnailed show a shimmer skeleton; thumbnails stream into view as they complete
-
----
-
-## 10. UI Design System
-
-### 10.1 Aesthetic
-
-Dark-first application (photography tools are dark-themed to preserve color perception). Light mode available via toggle.
-
-- **Dark mode primary surface**: Near-black warm dark `#111110`, not cold gray
-- **Accent**: Desaturated teal — does not compete with photo colors
-- **Typography**: `Geist` (body, UI chrome) + `Geist Mono` (metadata values, EXIF numbers)
-- Dense UI — this is a power tool, not a consumer app. Compact spacing.
-- Inspired by: Lightroom Classic, Linear, Darkroom (iOS)
-
-### 10.2 Key UI Components (shadcn/ui)
-
-Use these shadcn/ui primitives: `Button`, `ContextMenu`, `Dialog`, `DropdownMenu`, `Input`, `Label`, `Popover`, `ScrollArea`, `Separator`, `Sheet` (for mobile sidebar), `Skeleton`, `Slider`, `Switch`, `Tabs`, `Textarea`, `Toast`, `Tooltip`
-
-Build custom components:
-- `<PhotoThumbnail>` — thumbnail with selection state, pick/reject badges, rating overlay on hover
-- `<TimelineGroup>` — sticky date header + grid of thumbnails
-- `<VirtualTimeline>` — TanStack Virtual wrapper over TimelineGroups
-- `<FilmStrip>` — horizontal scrollable strip for loupe view
-- `<StarRating>` — interactive 0-5 stars
-- `<ColorLabel>` — 7-state color dot picker
-- `<MetadataRow>` — label + value pair with edit-in-place for editable fields
-- `<FolderTreeNode>` — recursive folder tree item with context menu
-- `<HeapItem>` — heap list item with active indicator
-- `<FilterChip>` — removable active filter chip
-- `<ProgressBar>` — scan progress in top bar
-- `<ShortcutReference>` — `?` overlay showing all shortcuts in a modal
-
-### 10.3 Color Scheme Variables
-
-```css
-/* Dark mode (default for photo apps) */
---color-bg:           #111110;
---color-surface:      #161615;
---color-surface-2:    #1c1c1a;
---color-surface-offset: #222220;
---color-border:       rgba(255,255,255,0.08);
---color-text:         #e8e6e0;
---color-text-muted:   #878580;
---color-text-faint:   #4a4845;
---color-primary:      #4f98a3;  /* desaturated teal */
---color-pick:         #4f9e5c;  /* green for picked */
---color-reject:       #c25a5a;  /* red for rejected */
---color-star:         #d4a340;  /* amber for stars */
-```
-
----
-
-## 11. Error States & Edge Cases
-
-- **File not found on disk** (moved externally): Show "missing file" badge on thumbnail. Offer "Locate File" action.
-- **Corrupt/unreadable file**: Log error, show broken-image placeholder, never crash the scan worker.
-- **Duplicate detection**: On scan, if a file with the same SHA-256 hash already exists in DB, mark as `is_duplicate=true` — do not create a second record. Show duplicate indicator in thumbnail.
-- **Scan in progress + user navigates**: Show partial results immediately as photos are indexed.
-- **Disk full**: Catch `OSError` on thumbnail write, log, continue scan.
-- **RAW decode failure**: Fall back to extracting the embedded JPEG preview from the RAW file (ExifTool can extract it).
-
----
-
-## 12. Stretch Goals (Phase 2 — Not in Initial Build)
-
-These must not be built now but the architecture must not block them:
-
-1. **AI Scene Classification** — CLIP embeddings per photo, semantic search ("find photos with mountains")
-2. **Face Detection & Clustering** — face_recognition lib or InsightFace, cluster by identity
-3. **Smart Albums** — saved filter presets that auto-populate (e.g., "5-star Canon shots from 2024")
-4. **Duplicate Finder** — perceptual hash (pHash) across library
-5. **Export Presets** — resize + watermark + format conversion on export
-6. **Multi-user** — add FastAPI auth (JWT), per-user libraries
-7. **Mobile PWA** — service worker, offline thumbnail caching
-
----
-
-## 13. Docker Compose File Structure
-
-```
-photovault/
-├── docker-compose.yml
-├── photovault.yml               ← user config
-├── .env                         ← PHOTO_DIRS, REDIS_URL, etc.
-├── frontend/
-│   ├── Dockerfile
-│   ├── package.json
-│   ├── vite.config.ts
-│   └── src/
-│       ├── main.tsx
-│       ├── App.tsx
-│       ├── store/               ← Zustand stores
-│       ├── components/
-│       │   ├── layout/
-│       │   ├── timeline/
-│       │   ├── loupe/
-│       │   ├── sidebar/
-│       │   ├── metadata/
-│       │   └── shared/
-│       ├── hooks/
-│       ├── api/                 ← TanStack Query hooks + axios client
-│       └── lib/
-│           └── shortcuts.ts     ← global keyboard shortcut registry
-└── backend/
-    ├── Dockerfile
-    ├── requirements.txt
-    ├── alembic/
-    ├── app/
-    │   ├── main.py              ← FastAPI app
-    │   ├── config.py            ← pydantic settings
-    │   ├── database.py          ← SQLAlchemy async engine
-    │   ├── models/              ← SQLAlchemy ORM models
-    │   ├── schemas/             ← Pydantic request/response schemas
-    │   ├── routers/             ← FastAPI routers per domain
-    │   │   ├── photos.py
-    │   │   ├── folders.py
-    │   │   ├── heaps.py
-    │   │   ├── tags.py
-    │   │   ├── trash.py
-    │   │   └── library.py
-    │   ├── services/            ← Business logic
-    │   │   ├── scanner.py
-    │   │   ├── thumbnailer.py
-    │   │   ├── metadata.py
-    │   │   └── file_ops.py
-    │   └── tasks/               ← Celery tasks
-    │       ├── celery.py
-    │       ├── scan.py
-    │       └── thumbs.py
-    └── nginx.conf               ← X-Accel-Redirect for thumb serving
-```
-
----
-
-## 14. Implementation Priorities
-
-Build in this order to get a working MVP as fast as possible:
-
-1. **Docker Compose skeleton** — all services up, health checks passing
-2. **DB schema + Alembic migration**
-3. **Folder scanner + thumbnail generator** (Celery tasks) — the core engine
-4. **`GET /photos` + `GET /photos/{id}/thumb/{size}`** — minimum API to display photos
-5. **Frontend: VirtualTimeline + PhotoThumbnail** — display the library
-6. **Frontend: keyboard navigation + selection**
-7. **Frontend: left sidebar (folder tree + heaps)**
-8. **Frontend: right sidebar (metadata panel) + EXIF display**
-9. **Filter bar + search**
-10. **Loupe view with filmstrip**
-11. **File operations: move, copy, rename, trash, restore**
-12. **Metadata editing: title, notes, rating, color label, tags**
-13. **Heaps: create, populate, convert to folder**
-14. **Trash view + permanent delete**
-15. **Polish: undo/redo, bulk actions, duplicate detection, live scan progress**

sidecar/.dockerignore

@@ -0,0 +1,13 @@
+# Files that have no business shipping into the build context.
+# Anything not listed here gets COPY'd into /src so keep this tight.
+
+# Local host-mode build output — re-built inside the image.
+mule-sidecar
+
+# Runtime state from the M3 Node prototype.
+data/
+
+# Docs + git noise.
+README.md
+.git/
+.gitignore

sidecar/Dockerfile

@@ -0,0 +1,28 @@
+# syntax=docker/dockerfile:1.6
+#
+# mule-sidecar — Go service for endpoints PhotoPrism does not expose.
+# Multi-stage build: a Go toolchain image compiles a static binary,
+# then we copy it onto a distroless base so the runtime image is ~12 MB
+# with no shell, package manager, or libc.
+
+FROM docker.io/library/golang:1.25-alpine AS build
+WORKDIR /src
+
+# Cache deps separately from source so a one-line code change doesn't
+# re-download the whole module graph.
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . ./
+# CGO disabled → fully static binary that runs on the distroless base
+# (no libc resolution at startup). -trimpath strips local paths from
+# debug info; -s -w drop the symbol table to keep the binary small.
+RUN CGO_ENABLED=0 GOOS=linux go build \
+    -trimpath \
+    -ldflags='-s -w' \
+    -o /out/mule-sidecar .
+
+FROM gcr.io/distroless/static-debian12:latest
+COPY --from=build /out/mule-sidecar /mule-sidecar
+EXPOSE 8000
+ENTRYPOINT ["/mule-sidecar"]

sidecar/README.md

@@ -0,0 +1,116 @@
+# mule-sidecar
+
+Go + Gin + GORM service for the endpoints PhotoPrism's REST API does not
+expose. Same wire contract as the M3 Node prototype it replaces; the
+SvelteKit client at [web/](../web/) talks to it transparently through
+Vite's `/api/sidecar/*` proxy.
+
+## What it owns
+
+| Method | Path                                    | Purpose                                       |
+| ------ | --------------------------------------- | --------------------------------------------- |
+| GET    | `/api/sidecar/healthz`                  | Unauthenticated liveness probe.               |
+| GET    | `/api/sidecar/photos/marks`             | Every per-photo `{rating, color}` mark.       |
+| GET    | `/api/sidecar/photos/:uid/marks`        | One photo's mark (or `{}` if none).           |
+| PUT    | `/api/sidecar/photos/:uid/marks`        | Patch one photo's mark.                       |
+| POST   | `/api/sidecar/photos/marks/bulk`        | Stamp the same mark onto many photos.         |
+| POST   | `/api/sidecar/files/:uid/rename`        | Rename the primary file on disk + reindex.    |
+| POST   | `/api/sidecar/folders`                  | Create a folder under `${ORIGINALS_ROOT}`.    |
+| POST   | `/api/sidecar/folders/:rel/rename`      | Rename a folder (rel path URL-encoded).       |
+| DELETE | `/api/sidecar/folders/:rel`             | Delete an **empty** folder.                   |
+| POST   | `/api/sidecar/albums/:uid/convert`      | Move/copy every photo in a heap into folder X. |
+| GET    | `/api/sidecar/duplicates/scan`          | Walk originals, return same-hash groups.      |
+| POST   | `/api/sidecar/duplicates/archive`       | Move duplicate paths into `.duplicates/<ts>/`. |
+
+Auth: every endpoint except `healthz` requires the caller's
+`X-Auth-Token` header. The sidecar holds no service credentials — it
+proxies the token straight back to PhotoPrism's `/api/v1/photos?count=1`
+to confirm the session is live before doing anything destructive.
+
+Marks persist to **MariaDB** (`mule_sidecar.marks`); everything else
+operates on the filesystem under `${ORIGINALS_ROOT}` and triggers a
+PhotoPrism reindex of the affected parent in the background.
+
+## Run
+
+The sidecar is a `sidecar` service in the PhotoPrism compose stack.
+Bringing the whole stack up brings it up too:
+
+```sh
+podman-compose --env-file .env \
+  -f docker-compose.yml \
+  -f docker-compose.podman.yml \
+  up -d
+```
+
+This builds [Dockerfile](Dockerfile) (multi-stage `golang:1.25-alpine` →
+`gcr.io/distroless/static`, ~12 MB final image), starts the container,
+and binds `127.0.0.1:8000` to the service. The SvelteKit dev server
+proxies `/api/sidecar/*` to that port transparently.
+
+### Dev-iteration loop (host build)
+
+For tight iteration without rebuilding the image on every change you
+can run it as a host process — Go is already on the dev machine:
+
+```sh
+cd sidecar
+go build -o mule-sidecar .
+
+ORIGINALS_ROOT=/path/to/photoprism/originals \
+PHOTOPRISM_BASE_URL=http://localhost:2342 \
+SIDECAR_PORT=8000 \
+./mule-sidecar
+```
+
+The host build connects to `mariadb` via the loopback port the compose
+file publishes; stop `pp-sidecar` first so they don't fight for 8000.
+
+## Env
+
+| Var                   | Default                           | Notes                                                                                          |
+| --------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `ORIGINALS_ROOT`      | `/photoprism/originals`           | Absolute path; must match PhotoPrism's mount.                                                  |
+| `PHOTOPRISM_BASE_URL` | `http://localhost:2342`           | Where to reach PhotoPrism for session validation + reindex calls.                              |
+| `SIDECAR_PORT`        | `8000`                            | Loopback-only; reverse-proxy fronts it in production.                                          |
+| `SIDECAR_DSN`         | _(built from the vars below)_     | Set this to override the assembled MySQL DSN entirely.                                         |
+| `SIDECAR_DB_HOST`     | `127.0.0.1`                       | Host of the MariaDB the compose stack publishes on `127.0.0.1:3306`.                           |
+| `SIDECAR_DB_PORT`     | `3306`                            |                                                                                                |
+| `SIDECAR_DB_USER`     | `sidecar`                         | Provisioned by [`mariadb/init/01-sidecar.sql`](../mariadb/init/01-sidecar.sql) on first boot.  |
+| `SIDECAR_DB_PASSWORD` | `replace-at-m4-bringup`           | Literal placeholder — **rotate before any non-local deployment**.                              |
+| `SIDECAR_DB_NAME`     | `mule_sidecar`                    |                                                                                                |
+
+## Schema
+
+GORM `AutoMigrate` creates the only table the service owns:
+
+```sql
+CREATE TABLE marks (
+  photo_uid  VARCHAR(64) PRIMARY KEY,
+  rating     BIGINT NULL,
+  color      VARCHAR(16) NULL,
+  updated_at DATETIME(3)
+);
+```
+
+The M3 Node prototype kept the same data in `sidecar/data/marks.json`.
+There is no migration path — the prototype's marks file was dev-only
+state. Heap-sharing tables (M4) will land in subsequent migrations.
+
+## Layout
+
+```text
+sidecar/
+├── Dockerfile            multi-stage golang:1.25 → distroless/static
+├── main.go               entrypoint, route wiring, graceful shutdown
+├── config.go             env-driven Config
+├── db.go                 GORM open + Mark model + AutoMigrate
+├── auth.go               requireSession middleware + ctxToken
+├── fs.go                 path safety, walk, sha1
+├── pp.go                 PhotoPrism HTTP client (validateSession, reindex)
+├── handlers_rename.go
+├── handlers_folders.go
+├── handlers_marks.go
+├── handlers_heap.go
+└── handlers_dups.go
+```

sidecar/auth.go

@@ -0,0 +1,87 @@
+package main
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// requireSession is the standard auth shim every mutating handler wears.
+// We don't store a shared service credential — the caller's X-Auth-Token
+// is the only authority, and we probe PhotoPrism with it before doing any
+// destructive work. The handler reads the validated token off the context
+// via ctxToken so it can keep forwarding it to PhotoPrism for the actual
+// operation. The resolved username is available via ctxUserName.
+func requireSession(pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := c.GetHeader("X-Auth-Token")
+		if token == "" {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "no token"})
+			return
+		}
+		user := pp.resolveSession(c.Request.Context(), token)
+		if user == nil {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid session"})
+			return
+		}
+		c.Set("token", token)
+		c.Set("userName", user.UserName)
+		c.Set("userUID", user.UserUID)
+		c.Set("basePath", user.BasePath)
+		c.Next()
+	}
+}
+
+// ctxToken returns the validated X-Auth-Token a previous requireSession
+// middleware stored on the request. Handlers MUST run behind that
+// middleware; otherwise this returns the empty string.
+func ctxToken(c *gin.Context) string {
+	v, ok := c.Get("token")
+	if !ok {
+		return ""
+	}
+	s, ok := v.(string)
+	if !ok {
+		return ""
+	}
+	return s
+}
+
+// ctxUserName returns the PhotoPrism username resolved by requireSession.
+func ctxUserName(c *gin.Context) string {
+	v, ok := c.Get("userName")
+	if !ok {
+		return ""
+	}
+	s, ok := v.(string)
+	if !ok {
+		return ""
+	}
+	return s
+}
+
+// ctxUserUID returns the PhotoPrism user UID resolved by requireSession.
+func ctxUserUID(c *gin.Context) string {
+	v, ok := c.Get("userUID")
+	if !ok {
+		return ""
+	}
+	s, ok := v.(string)
+	if !ok {
+		return ""
+	}
+	return s
+}
+
+// ctxBasePath returns the PhotoPrism user BasePath resolved by requireSession.
+func ctxBasePath(c *gin.Context) string {
+	v, ok := c.Get("basePath")
+	if !ok {
+		return ""
+	}
+	s, ok := v.(string)
+	if !ok {
+		return ""
+	}
+	return s
+}

sidecar/config.go

@@ -0,0 +1,92 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strconv"
+)
+
+// Config aggregates every runtime knob the sidecar reads from the
+// environment. Held in one struct so the rest of the package can take a
+// pointer instead of poking os.Getenv at use-sites.
+type Config struct {
+	OriginalsRoot     string // absolute path to PhotoPrism's originals dir
+	PhotoprismBaseURL string // e.g. http://localhost:2342
+	ListenAddr        string // bind interface — 127.0.0.1 for host mode, 0.0.0.0 in containers
+	Port              int    // HTTP listen port
+	DSN               string // GORM/MySQL connection string for mule_sidecar
+	// PpDSN is a second DB connection string pointed at PhotoPrism's own
+	// schema (`photoprism.*`). Sidecar code that needs to mutate
+	// PhotoPrism-managed rows (e.g. auth_users.base_path) opens its own
+	// connection with these creds rather than asking for grants on the
+	// mule_sidecar user. Empty if PP_DB_PASSWORD isn't provided, in
+	// which case PP-touching features (user-basepath reconciler) stay
+	// dormant.
+	PpDSN string
+	// UserBasepaths is the parsed `USER_BASEPATHS` env. Maps PhotoPrism
+	// usernames to originals-relative base paths so OIDC-provisioned
+	// users land with the right library scope without any admin
+	// touching `photoprism users mod`.
+	UserBasepaths map[string]string
+}
+
+func loadConfig() (*Config, error) {
+	root := envOr("ORIGINALS_ROOT", "/photoprism/originals")
+	abs, err := filepath.Abs(root)
+	if err != nil {
+		return nil, err
+	}
+
+	portStr := envOr("SIDECAR_PORT", "8000")
+	port, err := strconv.Atoi(portStr)
+	if err != nil {
+		return nil, err
+	}
+
+	dsn := os.Getenv("SIDECAR_DSN")
+	if dsn == "" {
+		// Default matches the user that mariadb/init/01-sidecar.sql provisions
+		// on first boot. The literal placeholder password is intentional: the
+		// SQL ships with it and an env-templating step is left for whoever
+		// runs this in a non-local context.
+		user := envOr("SIDECAR_DB_USER", "sidecar")
+		pass := envOr("SIDECAR_DB_PASSWORD", "replace-at-m4-bringup")
+		host := envOr("SIDECAR_DB_HOST", "127.0.0.1")
+		dbPort := envOr("SIDECAR_DB_PORT", "3306")
+		name := envOr("SIDECAR_DB_NAME", "mule_sidecar")
+		dsn = user + ":" + pass + "@tcp(" + host + ":" + dbPort + ")/" + name +
+			"?charset=utf8mb4&parseTime=true&loc=Local"
+	}
+
+	// PhotoPrism schema connection — only used by the user-basepath
+	// reconciler. Stays empty if PP_DB_PASSWORD isn't set, and callers
+	// gate behaviour on that. We use PhotoPrism's own DB user rather
+	// than the sidecar's because `mule_sidecar` has no grants on
+	// `photoprism.*` (see mariadb/init/01-sidecar.sql).
+	ppDSN := ""
+	if ppPass := os.Getenv("PP_DB_PASSWORD"); ppPass != "" {
+		ppUser := envOr("PP_DB_USER", "photoprism")
+		ppHost := envOr("PP_DB_HOST", envOr("SIDECAR_DB_HOST", "mariadb"))
+		ppPort := envOr("PP_DB_PORT", envOr("SIDECAR_DB_PORT", "3306"))
+		ppName := envOr("PP_DB_NAME", "photoprism")
+		ppDSN = ppUser + ":" + ppPass + "@tcp(" + ppHost + ":" + ppPort + ")/" + ppName +
+			"?charset=utf8mb4&parseTime=true&loc=Local"
+	}
+
+	return &Config{
+		OriginalsRoot:     abs,
+		PhotoprismBaseURL: envOr("PHOTOPRISM_BASE_URL", "http://localhost:2342"),
+		ListenAddr:        envOr("SIDECAR_LISTEN_ADDR", "127.0.0.1"),
+		Port:              port,
+		DSN:               dsn,
+		PpDSN:             ppDSN,
+		UserBasepaths:     parseUserBasepaths(os.Getenv("USER_BASEPATHS")),
+	}, nil
+}
+
+func envOr(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return fallback
+}

sidecar/db.go

@@ -0,0 +1,63 @@
+package main
+
+import (
+	"time"
+
+	"gorm.io/driver/mysql"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+// Mark mirrors the per-photo extras the web client stores via the marks
+// endpoints — rating + four-colour label. Composite primary key
+// (photo_uid, user_name) so each user has independent marks. Both payload
+// fields are nullable so the sparse "no rating / no colour" state
+// round-trips cleanly.
+type Mark struct {
+	PhotoUID  string    `gorm:"primaryKey;size:64;column:photo_uid" json:"-"`
+	UserName  string    `gorm:"primaryKey;size:128;column:user_name" json:"-"`
+	Rating    *int      `gorm:"column:rating" json:"rating,omitempty"`
+	Color     *string   `gorm:"size:16;column:color" json:"color,omitempty"`
+	UpdatedAt time.Time `gorm:"column:updated_at" json:"updatedAt"`
+}
+
+// TableName pins the GORM-pluralised default to a name that matches the
+// other tables the M4 plan calls out (`marks`, `heap_shares`, …) so
+// nothing surprising lands in the schema.
+func (Mark) TableName() string { return "marks" }
+
+// asJSON returns the wire shape clients expect — same flat object the
+// Node prototype emitted. An empty Mark (rating=nil, color=nil) renders
+// as `{}` which the client treats as "no mark on this photo".
+func (m *Mark) asJSON() map[string]any {
+	out := map[string]any{}
+	if m == nil {
+		return out
+	}
+	if m.Rating != nil {
+		out["rating"] = *m.Rating
+	}
+	if m.Color != nil && *m.Color != "" {
+		out["color"] = *m.Color
+	}
+	if !m.UpdatedAt.IsZero() {
+		// ISO-8601 with millisecond precision, UTC — matches the Node
+		// prototype's `new Date().toISOString()` so clients written against
+		// the old endpoint stay happy.
+		out["updatedAt"] = m.UpdatedAt.UTC().Format("2006-01-02T15:04:05.000Z")
+	}
+	return out
+}
+
+func openDB(dsn string) (*gorm.DB, error) {
+	db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Warn),
+	})
+	if err != nil {
+		return nil, err
+	}
+	if err := db.AutoMigrate(&Mark{}); err != nil {
+		return nil, err
+	}
+	return db, nil
+}

sidecar/fs.go

@@ -0,0 +1,213 @@
+package main
+
+import (
+	"crypto/sha1"
+	"encoding/hex"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// sanitizeFilename trims a user-supplied filename and rejects anything
+// dangerous: path separators, leading dots, NUL bytes, the `.`/`..`
+// pseudo-names, anything absurdly long. PhotoPrism's indexer is happy
+// with most filename shapes; we lock down the ones a malicious or
+// careless caller might use to escape the folder.
+func sanitizeFilename(name string) (string, bool) {
+	s := strings.TrimSpace(name)
+	if s == "" || len(s) > 240 {
+		return "", false
+	}
+	if strings.HasPrefix(s, ".") {
+		return "", false
+	}
+	if s == "." || s == ".." {
+		return "", false
+	}
+	if strings.ContainsAny(s, "/\\\x00") {
+		return "", false
+	}
+	return s, true
+}
+
+// resolveUnderRoot takes a user-supplied relative path and returns its
+// absolute form, but only when the resolved location lives under the
+// configured originals root. Symlink escapes are caught by resolving the
+// parent through filepath.EvalSymlinks first.
+//
+// `mustExist=false` is for the *target* of a rename/create where the
+// terminal path isn't on disk yet; the parent still has to exist and
+// still has to be inside the root.
+func resolveUnderRoot(root, rel string, mustExist bool) (string, error) {
+	if rel == "" {
+		return "", errors.New("empty path")
+	}
+	clean := strings.TrimLeft(rel, "/")
+	if clean == "" || clean == "." {
+		return "", errors.New("empty path")
+	}
+	for _, seg := range strings.Split(clean, "/") {
+		if seg == "" || seg == ".." {
+			return "", errors.New("path traversal")
+		}
+	}
+	abs := filepath.Join(root, clean)
+	parent := filepath.Dir(abs)
+
+	parentReal, err := filepath.EvalSymlinks(parent)
+	if err != nil {
+		return "", err
+	}
+	if !sameOrUnder(parentReal, root) {
+		return "", errors.New("parent escapes originals root")
+	}
+	if mustExist {
+		if _, err := os.Stat(abs); err != nil {
+			return "", err
+		}
+	}
+	return abs, nil
+}
+
+// ensureWithinOriginals checks that an absolute path's parent resolves to
+// somewhere inside the root after symlink evaluation. Used for the
+// already-resolved-on-disk paths returned by PhotoPrism's Files[].
+func ensureWithinOriginals(root, absPath string) bool {
+	real, err := filepath.EvalSymlinks(filepath.Dir(absPath))
+	if err != nil {
+		return false
+	}
+	return sameOrUnder(real, root)
+}
+
+func sameOrUnder(p, root string) bool {
+	if p == root {
+		return true
+	}
+	return strings.HasPrefix(p, root+string(os.PathSeparator))
+}
+
+// uniqueName resolves "destDir/basename" against collisions by appending
+// `-1`, `-2`, … to the stem. Caps at 1000 attempts so a runaway loop
+// can't pin the goroutine forever.
+func uniqueName(destDir, basename string) (abs, name string, ok bool) {
+	ext := filepath.Ext(basename)
+	stem := strings.TrimSuffix(basename, ext)
+	for i := 0; i < 1000; i++ {
+		candidate := basename
+		if i > 0 {
+			candidate = stem + "-" + itoa(i) + ext
+		}
+		p := filepath.Join(destDir, candidate)
+		if _, err := os.Stat(p); errors.Is(err, os.ErrNotExist) {
+			return p, candidate, true
+		}
+	}
+	return "", "", false
+}
+
+// itoa is the tiny stdlib-free formatter we use inside hot loops.
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	neg := n < 0
+	if neg {
+		n = -n
+	}
+	var buf [20]byte
+	i := len(buf)
+	for n > 0 {
+		i--
+		buf[i] = byte('0' + n%10)
+		n /= 10
+	}
+	if neg {
+		i--
+		buf[i] = '-'
+	}
+	return string(buf[i:])
+}
+
+// fileEntry is the per-file row walkFiles emits. relPath stays root-
+// relative so it can land in API responses unchanged.
+type fileEntry struct {
+	RelPath string
+	AbsPath string
+	Size    int64
+}
+
+// supportedExts mirrors the Node prototype's whitelist. PhotoPrism
+// itself walks the same set; we keep the list in lock-step so callers
+// don't see "duplicate" warnings about files PhotoPrism would ignore.
+var supportedExts = map[string]struct{}{
+	".jpg": {}, ".jpeg": {}, ".png": {}, ".heic": {}, ".heif": {},
+	".tiff": {}, ".tif": {}, ".gif": {}, ".bmp": {}, ".webp": {}, ".avif": {},
+	".mov": {}, ".mp4": {}, ".m4v": {}, ".avi": {}, ".mkv": {}, ".webm": {},
+	".dng": {}, ".cr2": {}, ".cr3": {}, ".nef": {}, ".arw": {},
+	".orf": {}, ".rw2": {}, ".raw": {},
+}
+
+// walkFiles enumerates every supported media file under root, skipping
+// dotfiles/dotdirs (matches PhotoPrism's indexer and our own quarantine
+// folder). Errors on individual entries are swallowed so a single
+// permission-denied dir doesn't abort the whole scan.
+func walkFiles(root string) ([]fileEntry, error) {
+	var out []fileEntry
+	err := filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error {
+		if err != nil {
+			// Permission errors etc. — skip the offending subtree but
+			// keep walking. The dup-scan endpoint is best-effort.
+			if d != nil && d.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		name := d.Name()
+		if p != root && strings.HasPrefix(name, ".") {
+			if d.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if d.IsDir() {
+			return nil
+		}
+		ext := strings.ToLower(filepath.Ext(name))
+		if _, ok := supportedExts[ext]; !ok {
+			return nil
+		}
+		info, err := d.Info()
+		if err != nil {
+			return nil
+		}
+		rel, err := filepath.Rel(root, p)
+		if err != nil {
+			return nil
+		}
+		out = append(out, fileEntry{
+			RelPath: rel,
+			AbsPath: p,
+			Size:    info.Size(),
+		})
+		return nil
+	})
+	return out, err
+}
+
+// sha1File streams the file through a SHA1 hasher so a 4GB ProRes clip
+// doesn't blow the process's RAM. Returns the hex digest.
+func sha1File(absPath string) (string, error) {
+	f, err := os.Open(absPath)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+	h := sha1.New()
+	if _, err := io.Copy(h, f); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(h.Sum(nil)), nil
+}

sidecar/go.mod

@@ -0,0 +1,45 @@
+module mule-sidecar
+
+go 1.25.0
+
+require (
+	github.com/gin-gonic/gin v1.12.0
+	gorm.io/driver/mysql v1.6.0
+	gorm.io/gorm v1.31.1
+)
+
+require (
+	filippo.io/edwards25519 v1.1.0 // indirect
+	github.com/bytedance/gopkg v0.1.3 // indirect
+	github.com/bytedance/sonic v1.15.0 // indirect
+	github.com/bytedance/sonic/loader v0.5.0 // indirect
+	github.com/cloudwego/base64x v0.1.6 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.12 // indirect
+	github.com/gin-contrib/sse v1.1.0 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-playground/validator/v10 v10.30.1 // indirect
+	github.com/go-sql-driver/mysql v1.8.1 // indirect
+	github.com/goccy/go-json v0.10.5 // indirect
+	github.com/goccy/go-yaml v1.19.2 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/quic-go/qpack v0.6.0 // indirect
+	github.com/quic-go/quic-go v0.59.0 // indirect
+	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/ugorji/go/codec v1.3.1 // indirect
+	go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
+	golang.org/x/arch v0.22.0 // indirect
+	golang.org/x/crypto v0.48.0 // indirect
+	golang.org/x/net v0.51.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/text v0.34.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
+)

sidecar/go.sum

@@ -0,0 +1,101 @@
+filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
+filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
+github.com/bytedance/gopkg v0.1.3/go.mod h1:576VvJ+eJgyCzdjS+c4+77QF3p7ubbtiKARP3TxducM=
+github.com/bytedance/sonic v1.15.0 h1:/PXeWFaR5ElNcVE84U0dOHjiMHQOwNIx3K4ymzh/uSE=
+github.com/bytedance/sonic v1.15.0/go.mod h1:tFkWrPz0/CUCLEF4ri4UkHekCIcdnkqXw9VduqpJh0k=
+github.com/bytedance/sonic/loader v0.5.0 h1:gXH3KVnatgY7loH5/TkeVyXPfESoqSBSBEiDd5VjlgE=
+github.com/bytedance/sonic/loader v0.5.0/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCcdf5x77udYiSJRo=
+github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
+github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/gabriel-vasile/mimetype v1.4.12 h1:e9hWvmLYvtp846tLHam2o++qitpguFiYCKbn0w9jyqw=
+github.com/gabriel-vasile/mimetype v1.4.12/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
+github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
+github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
+github.com/gin-gonic/gin v1.12.0 h1:b3YAbrZtnf8N//yjKeU2+MQsh2mY5htkZidOM7O0wG8=
+github.com/gin-gonic/gin v1.12.0/go.mod h1:VxccKfsSllpKshkBWgVgRniFFAzFb9csfngsqANjnLc=
+github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
+github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
+github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
+github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
+github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
+github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
+github.com/go-playground/validator/v10 v10.30.1 h1:f3zDSN/zOma+w6+1Wswgd9fLkdwy06ntQJp0BBvFG0w=
+github.com/go-playground/validator/v10 v10.30.1/go.mod h1:oSuBIQzuJxL//3MelwSLD5hc2Tu889bF0Idm9Dg26cM=
+github.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpvNJ1Y=
+github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=
+github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
+github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
+github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
+github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
+github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
+github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
+github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
+github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
+github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
+github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII=
+github.com/quic-go/quic-go v0.59.0 h1:OLJkp1Mlm/aS7dpKgTc6cnpynnD2Xg7C1pwL6vy/SAw=
+github.com/quic-go/quic-go v0.59.0/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
+github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
+github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
+github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
+go.mongodb.org/mongo-driver/v2 v2.5.0 h1:yXUhImUjjAInNcpTcAlPHiT7bIXhshCTL3jVBkF3xaE=
+go.mongodb.org/mongo-driver/v2 v2.5.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0=
+go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
+go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
+golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
+golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
+golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
+golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
+golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
+golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
+google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gorm.io/driver/mysql v1.6.0 h1:eNbLmNTpPpTOVZi8MMxCi2aaIm0ZpInbORNXDwyLGvg=
+gorm.io/driver/mysql v1.6.0/go.mod h1:D/oCC2GWK3M/dqoLxnOlaNKmXz8WNTfcS9y5ovaSqKo=
+gorm.io/gorm v1.31.1 h1:7CA8FTFz/gRfgqgpeKIBcervUn3xSyPUmr6B2WXJ7kg=
+gorm.io/gorm v1.31.1/go.mod h1:XyQVbO2k6YkOis7C2437jSit3SsDK72s7n7rsSHd+Gs=

sidecar/handlers_dups.go

@@ -0,0 +1,230 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"os"
+	"path/filepath"
+	"sort"
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+const quarantineDir = ".duplicates"
+
+type dupFileLite struct {
+	Path string `json:"path"`
+	Size int64  `json:"size"`
+}
+
+type dupGroup struct {
+	Hash         string        `json:"hash"`
+	Size         int64         `json:"size"`
+	IndexedPath  *string       `json:"indexedPath"`
+	Files        []dupFileLite `json:"files"`
+}
+
+// dupListPhoto is the partial photo shape we pull from PhotoPrism when
+// looking up "which file path has this hash already indexed", used to
+// hint the UI which copy to keep.
+type dupListPhoto struct {
+	Files []ppFile `json:"Files"`
+}
+
+func handleDupScan(cfg *Config, pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		start := time.Now()
+		slog.Info("dup.scan starting", "root", cfg.OriginalsRoot)
+
+		all, err := walkFiles(cfg.OriginalsRoot)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+
+		// Group by size first: byte-identical files necessarily share size,
+		// so size-collision is a cheap O(N) prefilter that lets us skip
+		// hashing >95% of a typical library.
+		bySize := map[int64][]fileEntry{}
+		for _, f := range all {
+			bySize[f.Size] = append(bySize[f.Size], f)
+		}
+
+		// Hash size-collision buckets concurrently. Cap fan-out to GOMAXPROCS
+		// so we don't drown the disk with parallel reads on a spinning HDD.
+		type hashOut struct {
+			hash string
+			f    fileEntry
+		}
+		var (
+			wg       sync.WaitGroup
+			sem      = make(chan struct{}, 4)
+			outMu    sync.Mutex
+			byHash   = map[string][]fileEntry{}
+			hashSize = map[string]int64{}
+		)
+		for size, group := range bySize {
+			if len(group) < 2 {
+				continue
+			}
+			for _, f := range group {
+				wg.Add(1)
+				sem <- struct{}{}
+				go func(f fileEntry, sz int64) {
+					defer wg.Done()
+					defer func() { <-sem }()
+					h, err := sha1File(f.AbsPath)
+					if err != nil {
+						return
+					}
+					outMu.Lock()
+					byHash[h] = append(byHash[h], f)
+					hashSize[h] = sz
+					outMu.Unlock()
+				}(f, size)
+			}
+		}
+		wg.Wait()
+
+		// Drop singletons (size collision but different hashes), then ask
+		// PhotoPrism which of the duplicates it has indexed so the UI can
+		// default the "keep" selection to that one.
+		groups := make([]dupGroup, 0)
+		for h, files := range byHash {
+			if len(files) < 2 {
+				continue
+			}
+			g := dupGroup{Hash: h, Size: hashSize[h]}
+			for _, f := range files {
+				g.Files = append(g.Files, dupFileLite{Path: f.RelPath, Size: f.Size})
+			}
+			// Best-effort lookup; swallow errors. The hash query is cheap on
+			// PhotoPrism's side (indexed column).
+			resp, err := pp.call(c.Request.Context(), http.MethodGet,
+				"/api/v1/photos?q=hash:"+h+"&count=1&merged=true", token, nil)
+			if err == nil && resp.OK {
+				var photos []dupListPhoto
+				if err := json.Unmarshal(resp.Body, &photos); err == nil && len(photos) > 0 {
+					if pf, ok := primaryFileOf(&ppPhoto{Files: photos[0].Files}); ok && pf.Name != "" {
+						p := pf.Name
+						g.IndexedPath = &p
+					}
+				}
+			}
+			groups = append(groups, g)
+		}
+		// Sort by reclaimable bytes descending (size × duplicate-count) so
+		// the biggest wins float to the top of the UI.
+		sort.Slice(groups, func(i, j int) bool {
+			return groups[i].Size*int64(len(groups[i].Files)-1) >
+				groups[j].Size*int64(len(groups[j].Files)-1)
+		})
+
+		ms := time.Since(start).Milliseconds()
+		slog.Info("dup.scan done", "groups", len(groups), "ms", ms)
+		c.JSON(http.StatusOK, gin.H{
+			"groups":    groups,
+			"scannedMs": ms,
+		})
+	}
+}
+
+type dupArchiveBody struct {
+	Paths []string `json:"paths"`
+}
+
+type dupMoved struct {
+	From string `json:"from"`
+	To   string `json:"to"`
+}
+
+type dupArchiveErr struct {
+	Path  string `json:"path"`
+	Error string `json:"error"`
+}
+
+func handleDupArchive(cfg *Config, pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		var body dupArchiveBody
+		if err := c.ShouldBindJSON(&body); err != nil || len(body.Paths) == 0 {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "paths[] required"})
+			return
+		}
+
+		// Each archive batch lands in its own timestamped subdir so the
+		// user can browse what was quarantined when (and recover by hand
+		// if they change their mind).
+		stamp := time.Now().UTC().Format("2006-01-02T15-04-05.000Z")
+		targetDir := filepath.Join(cfg.OriginalsRoot, quarantineDir, stamp)
+		if err := os.MkdirAll(targetDir, 0o755); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+
+		// archiveOne moves a single file into the quarantine batch dir
+		// and returns the new relative path. Disambiguates same-basename
+		// collisions within the batch so two `IMG_0001.jpg` from
+		// different folders don't clobber each other.
+		archiveOne := func(rel string) (string, error) {
+			abs, err := resolveUnderRoot(cfg.OriginalsRoot, rel, true)
+			if err != nil {
+				return "", errors.New("invalid path")
+			}
+			base := filepath.Base(abs)
+			dest := filepath.Join(targetDir, base)
+			for i := 1; ; i++ {
+				if _, err := os.Stat(dest); errors.Is(err, os.ErrNotExist) {
+					break
+				} else if err != nil {
+					return "", err
+				}
+				stem := base[:len(base)-len(filepath.Ext(base))]
+				dest = filepath.Join(targetDir, stem+"__"+itoa(i)+filepath.Ext(base))
+			}
+			if err := os.Rename(abs, dest); err != nil {
+				// EXDEV fallback — copy+remove for libraries that span
+				// filesystems (e.g. originals on a different mount).
+				if err2 := copyFile(abs, dest); err2 != nil {
+					return "", err
+				}
+				if err2 := os.Remove(abs); err2 != nil {
+					return "", errors.New("moved but source remove failed: " + err2.Error())
+				}
+			}
+			relDest, _ := filepath.Rel(cfg.OriginalsRoot, dest)
+			return relDest, nil
+		}
+
+		moved := []dupMoved{}
+		errs := []dupArchiveErr{}
+		for _, rel := range body.Paths {
+			relDest, err := archiveOne(rel)
+			if err != nil {
+				errs = append(errs, dupArchiveErr{Path: rel, Error: err.Error()})
+				continue
+			}
+			moved = append(moved, dupMoved{From: rel, To: relDest})
+			slog.Info("dup.archive", "from", rel, "to", relDest)
+		}
+
+		// Reindex the entire library so PhotoPrism drops rows for the
+		// archived files. cleanup:true is critical — the files still
+		// exist on disk, just under .duplicates/ which the indexer
+		// ignores.
+		if len(moved) > 0 {
+			go func() {
+				if err := pp.reindex(context.Background(), token, "/"); err != nil {
+					slog.Warn("dup.archive reindex failed", "err", err)
+				}
+			}()
+		}
+		c.JSON(http.StatusOK, gin.H{"moved": moved, "errors": errs})
+	}
+}

sidecar/handlers_folders.go

@@ -0,0 +1,307 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/gin-gonic/gin"
+)
+
+// pathParam pulls the URL-encoded :rel out of the Gin context and
+// unescapes it. UseRawPath is on at the router level (see main.go) so the
+// raw value still carries `%2F` for nested paths; we decode here.
+func pathParam(c *gin.Context, key string) (string, bool) {
+	raw := c.Param(key)
+	if raw == "" {
+		return "", false
+	}
+	dec, err := url.PathUnescape(raw)
+	if err != nil {
+		return "", false
+	}
+	return dec, true
+}
+
+type folderCreateBody struct {
+	Path string `json:"path"`
+}
+
+func handleFolderCreate(cfg *Config, pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		var body folderCreateBody
+		if err := c.ShouldBindJSON(&body); err != nil || body.Path == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "path required"})
+			return
+		}
+		abs, err := resolveUnderRoot(cfg.OriginalsRoot, body.Path, false)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid path"})
+			return
+		}
+		if _, err := os.Stat(abs); err == nil {
+			c.JSON(http.StatusConflict, gin.H{"error": "already exists"})
+			return
+		} else if !errors.Is(err, os.ErrNotExist) {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if err := os.Mkdir(abs, 0o755); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		rel, _ := filepath.Rel(cfg.OriginalsRoot, abs)
+		slog.Info("folder.create", "path", rel)
+		go fireReindex(cfg, pp, token, "/"+filepath.Dir(rel))
+		c.JSON(http.StatusOK, gin.H{"ok": true, "path": rel})
+	}
+}
+
+type folderRenameBody struct {
+	NewName string `json:"newName"`
+}
+
+func handleFolderRename(cfg *Config, pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		rel, ok := pathParam(c, "rel")
+		if !ok {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid path"})
+			return
+		}
+		var body folderRenameBody
+		if err := c.ShouldBindJSON(&body); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid json"})
+			return
+		}
+		newName, ok := sanitizeFilename(body.NewName)
+		if !ok {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "newName must be a plain dirname"})
+			return
+		}
+		oldAbs, err := resolveUnderRoot(cfg.OriginalsRoot, rel, true)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid path"})
+			return
+		}
+		st, err := os.Stat(oldAbs)
+		if err != nil || !st.IsDir() {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "not a directory"})
+			return
+		}
+		newAbs := filepath.Join(filepath.Dir(oldAbs), newName)
+		if _, err := os.Stat(newAbs); err == nil {
+			c.JSON(http.StatusConflict, gin.H{"error": "target already exists"})
+			return
+		} else if !errors.Is(err, os.ErrNotExist) {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if !sameOrUnder(newAbs, cfg.OriginalsRoot) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "target escapes root"})
+			return
+		}
+		if err := os.Rename(oldAbs, newAbs); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		oldRel, _ := filepath.Rel(cfg.OriginalsRoot, oldAbs)
+		newRel, _ := filepath.Rel(cfg.OriginalsRoot, newAbs)
+		slog.Info("folder.rename", "from", oldRel, "to", newRel)
+		go fireReindex(cfg, pp, token, "/"+filepath.Dir(oldRel))
+		c.JSON(http.StatusOK, gin.H{
+			"ok":      true,
+			"oldPath": oldRel,
+			"newPath": newRel,
+		})
+	}
+}
+
+func handleFolderDelete(cfg *Config, pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		rel, ok := pathParam(c, "rel")
+		if !ok {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid path"})
+			return
+		}
+		abs, err := resolveUnderRoot(cfg.OriginalsRoot, rel, true)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid path"})
+			return
+		}
+		if abs == cfg.OriginalsRoot {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "refuse to delete root"})
+			return
+		}
+		st, err := os.Stat(abs)
+		if err != nil || !st.IsDir() {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "not a directory"})
+			return
+		}
+		entries, err := os.ReadDir(abs)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if len(entries) > 0 {
+			c.JSON(http.StatusConflict, gin.H{"error": "directory not empty"})
+			return
+		}
+		if err := os.Remove(abs); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		slog.Info("folder.delete", "path", rel)
+		go fireReindex(cfg, pp, token, "/"+filepath.Dir(rel))
+		c.JSON(http.StatusOK, gin.H{"ok": true, "path": rel})
+	}
+}
+
+type folderCountsBody struct {
+	Paths []string `json:"paths"`
+}
+
+// folderCountsRow is the minimal PhotoPrism photo projection the handler
+// needs — just UID, so dedupe-by-UID survives `merged=false` (which
+// expands one photo into one row per File on disk). PhotoPrism returns a
+// JSON array of much richer objects; unmarshalling into this small
+// shape ignores everything we don't care about.
+type folderCountsRow struct {
+	UID string `json:"UID"`
+}
+
+// handleFolderCounts returns photo counts for each PhotoPrism folder
+// path in one round-trip. The web client used to fire one
+// `/photos?count=1000` per folder from the browser (≈1 MB JSON per
+// folder × N folders) to populate the left-sidebar tree. Moving the
+// fan-out into the sidecar keeps the same correctness profile — same
+// q-DSL, same `merged=false` UID dedupe — but the wire payload back
+// to the browser collapses to a single small JSON object
+// (`{path: count}`).
+//
+// We bounce off PhotoPrism with paginated `count=1000` calls and dedupe
+// UIDs server-side rather than trusting a count header: PhotoPrism's
+// `/photos` X-Count is the *per-page* row count (per existing front-end
+// comment), not the total-match count, so we'd silently undercount any
+// folder with more than 1000 files. The loop walks offsets until PP
+// returns a short page, so the result is correct regardless of folder
+// size (until the wider fan-out becomes the bottleneck, which is many
+// orders of magnitude away on this hardware).
+//
+// Bounded concurrency caps the fan-out so a library with hundreds of
+// folders doesn't open hundreds of connections to PhotoPrism at once.
+// Errors per-folder degrade to count=0 rather than failing the whole
+// batch — the sidebar would rather show a missing badge for one folder
+// than nothing for any.
+func handleFolderCounts(pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		var body folderCountsBody
+		if err := c.ShouldBindJSON(&body); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid json"})
+			return
+		}
+		if len(body.Paths) == 0 {
+			c.JSON(http.StatusOK, gin.H{})
+			return
+		}
+
+		const maxInFlight = 8
+		var (
+			wg     sync.WaitGroup
+			sem    = make(chan struct{}, maxInFlight)
+			mu     sync.Mutex
+			counts = make(map[string]int, len(body.Paths))
+		)
+		// Seed every input key so the response always carries the same
+		// shape the client posted, even for paths whose lookup failed.
+		for _, p := range body.Paths {
+			counts[p] = 0
+		}
+		for _, p := range body.Paths {
+			path := p
+			wg.Add(1)
+			sem <- struct{}{}
+			go func() {
+				defer wg.Done()
+				defer func() { <-sem }()
+				// `path:<x>` is an exact match in PhotoPrism's q-DSL —
+				// it matches only photos whose `photo_path` field equals
+				// <x>, not descendants. The indexer always nests photos
+				// under YYYY/MM, so an internal tree node like `2024` has
+				// zero direct children and reports a count of 0 unless we
+				// recurse. `path:<x>*` is the documented wildcard form and
+				// matches both `<x>` itself (no harm if empty) and every
+				// `<x>/...` descendant.
+				//
+				// `merged=false` still returns one row per File on disk,
+				// so HEIC + companion JPG count twice unless we dedupe by
+				// UID — which is what the old client-side code did, and
+				// what we keep doing here.
+				q := url.QueryEscape(`path:"` + path + `*"`)
+				const pageSize = 1000
+				seen := make(map[string]struct{})
+				for offset := 0; ; offset += pageSize {
+					resp, err := pp.call(c.Request.Context(), http.MethodGet,
+						fmt.Sprintf("/api/v1/photos?count=%d&offset=%d&merged=false&q=%s", pageSize, offset, q),
+						token, nil)
+					if err != nil || !resp.OK {
+						slog.Warn("folder.counts: pp call failed",
+							"path", path,
+							"offset", offset,
+							"err", err,
+							"status", func() int {
+								if resp != nil {
+									return resp.Status
+								}
+								return 0
+							}())
+						return
+					}
+					var rows []folderCountsRow
+					if err := json.Unmarshal(resp.Body, &rows); err != nil {
+						slog.Warn("folder.counts: parse failed", "path", path, "offset", offset, "err", err)
+						return
+					}
+					for _, r := range rows {
+						if r.UID == "" {
+							continue
+						}
+						seen[r.UID] = struct{}{}
+					}
+					if len(rows) < pageSize {
+						break
+					}
+				}
+				mu.Lock()
+				counts[path] = len(seen)
+				mu.Unlock()
+			}()
+		}
+		wg.Wait()
+		c.JSON(http.StatusOK, counts)
+	}
+}
+
+// fireReindex wraps pp.reindex with logging and a detached context so
+// it can run in a goroutine after the response has gone out. The Node
+// prototype kicks reindex with `void reindex(...)` and never awaits;
+// matching that here keeps the apparent latency of mutating endpoints
+// low (PhotoPrism's index can take seconds on a big folder).
+func fireReindex(_ *Config, pp *ppClient, token, parentRel string) {
+	// pp.call's client already enforces a 60s timeout, so the parent
+	// context can be detached from the request — the handler has long
+	// since written its response.
+	if err := pp.reindex(context.Background(), token, parentRel); err != nil {
+		slog.Warn("reindex failed", "path", parentRel, "err", err)
+	}
+}

sidecar/handlers_folders_proxy.go

@@ -0,0 +1,70 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+// handleFoldersProxy proxies PhotoPrism's /api/v1/folders/originals and
+// post-filters by the caller's BasePath so the folder tree only shows
+// folders under the user's library root.
+//
+// Route: GET /api/sidecar/folders  (behind requireSession)
+func handleFoldersProxy(pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		basePath := ctxBasePath(c)
+
+		// Forward query params to PhotoPrism.
+		query := c.Request.URL.RawQuery
+		if query == "" {
+			query = "recursive=true&uncached=true&files=false"
+		}
+
+		resp, err := pp.call(c.Request.Context(), http.MethodGet, "/api/v1/folders/originals?"+query, token, nil)
+		if err != nil || !resp.OK {
+			c.JSON(http.StatusBadGateway, gin.H{"error": "upstream folders request failed"})
+			return
+		}
+
+		// Decode the response — PhotoPrism returns { folders: [...] }.
+		var payload struct {
+			Folders []map[string]any `json:"folders"`
+		}
+		if err := json.Unmarshal(resp.Body, &payload); err != nil {
+			c.Data(resp.Status, "application/json", resp.Body)
+			return
+		}
+
+		// If the user has no BasePath (admin/empty), return as-is.
+		if basePath == "" {
+			c.JSON(http.StatusOK, payload)
+			return
+		}
+
+		prefix := basePath + "/"
+
+		// Post-filter folders by Path field only — frontend handles BasePath
+		// prefix stripping via toUserPath().
+		filtered := make([]map[string]any, 0, len(payload.Folders))
+		for _, f := range payload.Folders {
+			rawPath, ok := f["Path"]
+			if !ok {
+				continue
+			}
+			pathStr, ok := rawPath.(string)
+			if !ok {
+				continue
+			}
+			// Keep only folders under the user's base path.
+			if pathStr == basePath || strings.HasPrefix(pathStr, prefix) {
+				filtered = append(filtered, f)
+			}
+		}
+
+		c.JSON(http.StatusOK, gin.H{"folders": filtered})
+	}
+}

sidecar/handlers_heap.go

@@ -0,0 +1,262 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+type heapConvertBody struct {
+	TargetFolder string `json:"targetFolder"`
+	Mode         string `json:"mode"`      // "move" or "copy"
+	Subfolder    string `json:"subfolder"` // optional, sanitized to a single segment
+	DeleteHeap   bool   `json:"deleteHeap"`
+}
+
+type heapPhoto struct {
+	UID   string   `json:"UID"`
+	Files []ppFile `json:"Files"`
+}
+
+type heapErr struct {
+	UID    string `json:"uid"`
+	Reason string `json:"reason"`
+}
+
+// copyFile is the os.Rename fallback for cross-device moves and the
+// primary path for "copy" mode. Streams so a 4GB video doesn't pin
+// memory; preserves mode bits, sets the modification time to now (we're
+// creating a new inode either way).
+func copyFile(src, dst string) error {
+	in, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer in.Close()
+	st, err := in.Stat()
+	if err != nil {
+		return err
+	}
+	out, err := os.OpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_EXCL, st.Mode())
+	if err != nil {
+		return err
+	}
+	if _, err := io.Copy(out, in); err != nil {
+		out.Close()
+		os.Remove(dst)
+		return err
+	}
+	return out.Close()
+}
+
+func handleHeapConvert(cfg *Config, pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		albumUID := c.Param("uid")
+
+		var body heapConvertBody
+		if err := c.ShouldBindJSON(&body); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid json"})
+			return
+		}
+		mode := body.Mode
+		if mode != "copy" {
+			mode = "move"
+		}
+		deleteHeap := mode == "move" && body.DeleteHeap
+
+		var subfolder string
+		if body.Subfolder != "" {
+			s, ok := sanitizeFilename(body.Subfolder)
+			if !ok {
+				c.JSON(http.StatusBadRequest, gin.H{"error": "invalid subfolder name"})
+				return
+			}
+			subfolder = s
+		}
+
+		// Resolve destination. resolveUnderRoot ensures the target lives
+		// inside ORIGINALS_ROOT and that its parent is a real directory.
+		// Empty / "/" / "." are valid here — they mean "drop these into
+		// originals/ itself" (the modal's "Root" option). resolveUnderRoot
+		// rejects those for safety, so handle the root case explicitly.
+		var targetAbs string
+		trimmed := strings.Trim(body.TargetFolder, "/")
+		if trimmed == "" || trimmed == "." {
+			targetAbs = cfg.OriginalsRoot
+		} else {
+			abs, err := resolveUnderRoot(cfg.OriginalsRoot, body.TargetFolder, true)
+			if err != nil {
+				c.JSON(http.StatusBadRequest, gin.H{"error": "invalid targetFolder"})
+				return
+			}
+			targetAbs = abs
+		}
+		destAbs := targetAbs
+		if subfolder != "" {
+			destAbs = filepath.Join(targetAbs, subfolder)
+			if err := os.MkdirAll(destAbs, 0o755); err != nil {
+				c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+				return
+			}
+		}
+
+		// Pull the heap's photos via the q=album:UID query. count=1000 covers
+		// every realistic heap; merged=true expands stacked variants so we
+		// move the JPG/HEIC sibling alongside the primary.
+		q := url.QueryEscape("album:" + albumUID)
+		listURL := "/api/v1/photos?q=" + q + "&count=1000&merged=true"
+		resp, err := pp.call(c.Request.Context(), http.MethodGet, listURL, token, nil)
+		if err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+			return
+		}
+		if !resp.OK {
+			c.JSON(resp.Status, gin.H{"error": "list photos failed"})
+			return
+		}
+		var photos []heapPhoto
+		if err := json.Unmarshal(resp.Body, &photos); err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": "decode photo list"})
+			return
+		}
+
+		sourceParents := map[string]struct{}{}
+		errs := []heapErr{}
+		moved, copied := 0, 0
+
+		for _, photo := range photos {
+			// Pick the file to physically move. PhotoPrism's "primary" file
+			// for a HEIC photo is the generated `.HEIC.jpg` preview that
+			// lives in storage/sidecar (Root=="sidecar"), not in originals
+			// — moving that path would fail "file missing on disk" every
+			// time. Prefer the primary that lives in originals (Root=="/")
+			// and fall back to the first originals-rooted file. PhotoPrism
+			// regenerates sidecars on reindex, so they don't need to follow.
+			var file ppFile
+			found := false
+			for _, f := range photo.Files {
+				if f.Root == "/" && f.Primary {
+					file, found = f, true
+					break
+				}
+			}
+			if !found {
+				for _, f := range photo.Files {
+					if f.Root == "/" {
+						file, found = f, true
+						break
+					}
+				}
+			}
+			if !found {
+				errs = append(errs, heapErr{UID: photo.UID, Reason: "no originals-rooted file"})
+				continue
+			}
+			srcRel := file.Name
+			srcAbs := filepath.Join(cfg.OriginalsRoot, srcRel)
+			if !sameOrUnder(srcAbs, cfg.OriginalsRoot) {
+				errs = append(errs, heapErr{UID: photo.UID, Reason: "path escapes originals"})
+				continue
+			}
+			st, err := os.Stat(srcAbs)
+			if err != nil || !st.Mode().IsRegular() {
+				errs = append(errs, heapErr{UID: photo.UID, Reason: "file missing on disk"})
+				continue
+			}
+			if filepath.Dir(srcAbs) == destAbs {
+				errs = append(errs, heapErr{UID: photo.UID, Reason: "already in target"})
+				continue
+			}
+			_, name, ok := uniqueName(destAbs, filepath.Base(srcAbs))
+			if !ok {
+				errs = append(errs, heapErr{UID: photo.UID, Reason: "too many collisions"})
+				continue
+			}
+			dstAbs := filepath.Join(destAbs, name)
+			if mode == "move" {
+				if err := os.Rename(srcAbs, dstAbs); err != nil {
+					// Cross-device renames fail with EXDEV — fall back to
+					// copy+remove so a library that spans filesystems still
+					// works.
+					if err2 := copyFile(srcAbs, dstAbs); err2 != nil {
+						errs = append(errs, heapErr{UID: photo.UID, Reason: err.Error()})
+						continue
+					}
+					if err2 := os.Remove(srcAbs); err2 != nil {
+						errs = append(errs, heapErr{UID: photo.UID, Reason: "rename ok, source remove failed: " + err2.Error()})
+						continue
+					}
+				}
+				moved++
+			} else {
+				if err := copyFile(srcAbs, dstAbs); err != nil {
+					errs = append(errs, heapErr{UID: photo.UID, Reason: err.Error()})
+					continue
+				}
+				copied++
+			}
+			sourceParents[filepath.Dir(srcRel)] = struct{}{}
+		}
+
+		// Reindex the destination + every source parent so PhotoPrism's
+		// DB catches up. We block on these so the response only goes out
+		// after the index reflects the move — callers (the frontend's
+		// invalidateQueries refetch in particular) need the next /photos
+		// fetch to return the moved files, otherwise the folder view
+		// looks unchanged. PhotoPrism's index endpoint serialises calls
+		// internally; running them sequentially matches that contract
+		// without surprising the server.
+		destRel, _ := filepath.Rel(cfg.OriginalsRoot, destAbs)
+		paths := map[string]struct{}{destRel: {}}
+		for p := range sourceParents {
+			paths[p] = struct{}{}
+		}
+		if subfolder != "" {
+			parent, _ := filepath.Rel(cfg.OriginalsRoot, targetAbs)
+			paths[parent] = struct{}{}
+		}
+		for p := range paths {
+			reindex := "/"
+			if p != "" && p != "." {
+				reindex = "/" + p
+			}
+			fireReindex(cfg, pp, token, reindex)
+		}
+
+		heapDeleted := false
+		if deleteHeap {
+			r, err := pp.call(context.Background(), http.MethodDelete, "/api/v1/albums/"+albumUID, token, nil)
+			if err == nil && r.OK {
+				heapDeleted = true
+			} else if err != nil {
+				errs = append(errs, heapErr{UID: albumUID, Reason: "album delete: " + err.Error()})
+			} else {
+				errs = append(errs, heapErr{UID: albumUID, Reason: "album delete: HTTP " + itoa(r.Status)})
+			}
+		}
+
+		slog.Info("heap.convert",
+			"album", albumUID,
+			"mode", mode,
+			"moved", moved,
+			"copied", copied,
+			"errors", len(errs),
+			"heap_deleted", heapDeleted,
+		)
+		c.JSON(http.StatusOK, gin.H{
+			"moved":        moved,
+			"copied":       copied,
+			"errors":       errs,
+			"heap_deleted": heapDeleted,
+		})
+	}
+}

sidecar/handlers_labels.go

@@ -0,0 +1,171 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+// PpLabel mirrors the shape PhotoPrism's /api/v1/labels endpoint returns.
+// We decode enough to filter + recalculate PhotoCount; fields the client
+// doesn't render are skipped for token efficiency.
+type PpLabel struct {
+	UID        string `json:"UID"`
+	Name       string `json:"Name"`
+	Slug       string `json:"Slug"`
+	CustomSlug string `json:"CustomSlug"`
+	Priority   int    `json:"Priority"`
+	Favorite   bool   `json:"Favorite"`
+	PhotoCount int    `json:"PhotoCount"`
+	Thumb      string `json:"Thumb"`
+	CreatedAt  string `json:"CreatedAt"`
+	UpdatedAt  string `json:"UpdatedAt"`
+}
+
+// handleLabels proxies PhotoPrism's /api/v1/labels and then post-filters
+// each label's PhotoCount (and removes labels with zero count) so they
+// reflect only photos under the caller's BasePath.
+//
+// Route: GET /api/sidecar/labels  (behind requireSession)
+func handleLabels(pp *ppClient, ppDb *gorm.DB) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		basePath := ctxBasePath(c)
+
+		// Forward the query string (count, offset, q, all, …) to PhotoPrism.
+		query := c.Request.URL.RawQuery
+
+		// Call PhotoPrism's labels endpoint using the caller's token.
+		resp, err := pp.call(c.Request.Context(), http.MethodGet, "/api/v1/labels?"+query, token, nil)
+		if err != nil || !resp.OK {
+			c.JSON(http.StatusBadGateway, gin.H{"error": "upstream labels request failed"})
+			return
+		}
+
+		// Decode labels.
+		var labels []PpLabel
+		if err := json.Unmarshal(resp.Body, &labels); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to parse labels"})
+			return
+		}
+
+		// If the user has no BasePath (admin/empty), return labels as-is.
+		if basePath == "" || ppDb == nil {
+			c.JSON(http.StatusOK, labels)
+			return
+		}
+
+		// One query: count + a representative scoped thumb for every label
+		// the user can see. Replaces N per-label queries with a single JOIN.
+		prefix := basePath + "/%"
+
+		type labelStat struct {
+			LabelUID  string `gorm:"column:label_uid"`
+			Cnt       int64  `gorm:"column:cnt"`
+			ThumbHash string `gorm:"column:thumb_hash"`
+		}
+		var stats []labelStat
+		if err := ppDb.Raw(`
+			SELECT lb.label_uid                          AS label_uid,
+			       COUNT(DISTINCT p.id)                  AS cnt,
+			       COALESCE(MIN(f.file_hash), '')        AS thumb_hash
+			FROM   photos_labels pl
+			JOIN   photos p  ON pl.photo_id  = p.id
+			JOIN   labels lb ON pl.label_id  = lb.id
+			LEFT JOIN files f ON f.photo_uid   = p.photo_uid
+			                 AND f.file_primary = 1
+			                 AND f.file_missing = 0
+			WHERE  (p.photo_path = ? OR p.photo_path LIKE ?)
+			  AND  p.deleted_at IS NULL
+			GROUP  BY lb.label_uid
+			HAVING cnt > 0
+		`, basePath, prefix).Scan(&stats).Error; err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": "label stats query failed"})
+			return
+		}
+
+		cntMap := make(map[string]int64, len(stats))
+		thumbMap := make(map[string]string, len(stats))
+		for _, s := range stats {
+			cntMap[s.LabelUID] = s.Cnt
+			thumbMap[s.LabelUID] = s.ThumbHash
+		}
+
+		filtered := make([]PpLabel, 0, len(stats))
+		for _, l := range labels {
+			cnt, ok := cntMap[l.UID]
+			if !ok || cnt == 0 {
+				continue
+			}
+			l.PhotoCount = int(cnt)
+			if th := thumbMap[l.UID]; th != "" {
+				l.Thumb = th
+			}
+			filtered = append(filtered, l)
+		}
+
+		c.JSON(http.StatusOK, filtered)
+	}
+}
+
+// Now also handle the session/config count scoping.
+
+// PpCounts mirrors PhotoPrism's session config.count block that drives
+// the sidebar badges (review, archive, all, etc.).
+type PpCounts struct {
+	All      int `json:"all"`
+	Photos   int `json:"photos"`
+	Media    int `json:"media"`
+	Videos   int `json:"videos"`
+	Review   int `json:"review"`
+	Archived int `json:"archived"`
+	Hidden   int `json:"hidden"`
+	Private  int `json:"private"`
+	Favorites int `json:"favorites"`
+}
+
+// handleScopedCounts returns user-scoped counts for review/archive/all
+// so the sidebar badges match what the user actually sees.
+//
+// Route: GET /api/sidecar/counts  (behind requireSession)
+func handleScopedCounts(ppDb *gorm.DB) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		basePath := ctxBasePath(c)
+		if basePath == "" || ppDb == nil {
+			// Admin or no DB — can't scope, return empty.
+			c.JSON(http.StatusOK, PpCounts{})
+			return
+		}
+
+		prefix := basePath + "/%"
+		pathCond := "(p.photo_path = ? OR p.photo_path LIKE ?)"
+		args := []any{basePath, prefix}
+
+		var counts PpCounts
+
+		// All non-deleted photos in this user's scope.
+		ppDb.Raw(`SELECT COUNT(*) FROM photos p WHERE p.deleted_at IS NULL AND `+pathCond, args...).Scan(&counts.All)
+
+		// Photos needing review (quality < 3).
+		ppDb.Raw(`SELECT COUNT(*) FROM photos p WHERE p.deleted_at IS NULL AND p.photo_quality < 3 AND `+pathCond, args...).Scan(&counts.Review)
+
+		// Archived (soft-deleted) photos.
+		ppDb.Raw(`SELECT COUNT(*) FROM photos p WHERE p.deleted_at IS NOT NULL AND `+pathCond, args...).Scan(&counts.Archived)
+
+		// Private photos.
+		ppDb.Raw(`SELECT COUNT(*) FROM photos p WHERE p.deleted_at IS NULL AND p.photo_private = 1 AND `+pathCond, args...).Scan(&counts.Private)
+
+		// Photos (type image).
+		ppDb.Raw(`SELECT COUNT(*) FROM photos p WHERE p.deleted_at IS NULL AND p.photo_type IN ('image','raw','live','animated') AND `+pathCond, args...).Scan(&counts.Photos)
+
+		// Videos.
+		ppDb.Raw(`SELECT COUNT(*) FROM photos p WHERE p.deleted_at IS NULL AND p.photo_type IN ('video','hdr','burst','live') AND `+pathCond, args...).Scan(&counts.Videos)
+
+		// Favorites.
+		ppDb.Raw(`SELECT COUNT(*) FROM photos p WHERE p.deleted_at IS NULL AND p.photo_favorite = 1 AND `+pathCond, args...).Scan(&counts.Favorites)
+
+		c.JSON(http.StatusOK, counts)
+	}
+}

sidecar/handlers_marks.go

@@ -0,0 +1,212 @@
+package main
+
+import (
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+// validColors is the color palette the web client offers (COLOR_SWATCHES in
+// web/src/lib/utils/tagGroups.ts) — keep the two in sync. The empty string is
+// the explicit "clear color" sentinel.
+var validColors = map[string]struct{}{
+	"red":    {},
+	"orange": {},
+	"yellow": {},
+	"green":  {},
+	"teal":   {},
+	"blue":   {},
+	"purple": {},
+	"pink":   {},
+}
+
+// markPatch is the request body for all three mutating mark endpoints.
+// Pointers distinguish "field omitted" from "field set to zero" — a PUT
+// with `{"rating": 0}` clears the rating, but a PUT with `{"color": "red"}`
+// alone must NOT wipe an existing rating.
+type markPatch struct {
+	Rating *int    `json:"rating,omitempty"`
+	Color  *string `json:"color,omitempty"`
+}
+
+func (p *markPatch) sanitize() error {
+	if p.Rating != nil {
+		r := *p.Rating
+		if r < 0 || r > 5 {
+			return errors.New("rating out of range")
+		}
+	}
+	if p.Color != nil {
+		c := strings.ToLower(strings.TrimSpace(*p.Color))
+		if c != "" {
+			if _, ok := validColors[c]; !ok {
+				return errors.New("invalid color")
+			}
+		}
+		*p.Color = c
+	}
+	return nil
+}
+
+// apply merges the patch onto an existing row (or a fresh zero-value
+// Mark for an upsert). Returns true if anything in the row still has a
+// non-empty value — false signals "delete the row" to the caller.
+func (p *markPatch) apply(m *Mark) bool {
+	if p.Rating != nil {
+		if *p.Rating > 0 {
+			r := *p.Rating
+			m.Rating = &r
+		} else {
+			m.Rating = nil
+		}
+	}
+	if p.Color != nil {
+		if *p.Color != "" {
+			c := *p.Color
+			m.Color = &c
+		} else {
+			m.Color = nil
+		}
+	}
+	return m.Rating != nil || (m.Color != nil && *m.Color != "")
+}
+
+// allMarksJSON renders the current user's marks as the wire shape
+// `{"<uid>": {"rating": …, "color": …, "updatedAt": …}, …}`. Used by
+// GET /photos/marks which the web client calls once on session start.
+func allMarksJSON(db *gorm.DB, userName string) (map[string]map[string]any, error) {
+	var rows []Mark
+	if err := db.Where("user_name = ?", userName).Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	out := make(map[string]map[string]any, len(rows))
+	for i := range rows {
+		out[rows[i].PhotoUID] = rows[i].asJSON()
+	}
+	return out, nil
+}
+
+func handleMarksAll(db *gorm.DB) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		marks, err := allMarksJSON(db, ctxUserName(c))
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, marks)
+	}
+}
+
+func handleMarkGet(db *gorm.DB) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		uid := c.Param("uid")
+		var m Mark
+		err := db.Where("photo_uid = ? AND user_name = ?", uid, ctxUserName(c)).First(&m).Error
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			c.JSON(http.StatusOK, gin.H{})
+			return
+		}
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, m.asJSON())
+	}
+}
+
+// upsert applies the patch and writes back. Returns the resulting JSON
+// shape (empty map if the row was deleted).
+func upsert(db *gorm.DB, uid, userName string, patch *markPatch) (map[string]any, error) {
+	var m Mark
+	err := db.Where("photo_uid = ? AND user_name = ?", uid, userName).First(&m).Error
+	if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, err
+	}
+	m.PhotoUID = uid
+	m.UserName = userName
+	keep := patch.apply(&m)
+	m.UpdatedAt = time.Now().UTC()
+	if !keep {
+		if err := db.Where("photo_uid = ? AND user_name = ?", uid, userName).Delete(&Mark{}).Error; err != nil {
+			return nil, err
+		}
+		return map[string]any{}, nil
+	}
+	if err := db.Save(&m).Error; err != nil {
+		return nil, err
+	}
+	return m.asJSON(), nil
+}
+
+func handleMarkPut(db *gorm.DB) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		uid := c.Param("uid")
+		var patch markPatch
+		if err := c.ShouldBindJSON(&patch); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid patch"})
+			return
+		}
+		if err := patch.sanitize(); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		out, err := upsert(db, uid, ctxUserName(c), &patch)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, out)
+	}
+}
+
+type bulkBody struct {
+	IDs   []string  `json:"ids"`
+	Patch markPatch `json:"patch"`
+}
+
+func handleMarkBulk(db *gorm.DB) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var body bulkBody
+		if err := c.ShouldBindJSON(&body); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid body"})
+			return
+		}
+		if len(body.IDs) == 0 {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "ids[] required"})
+			return
+		}
+		if err := body.Patch.sanitize(); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		userName := ctxUserName(c)
+		applied := make(map[string]map[string]any, len(body.IDs))
+		// Single transaction so a partial failure rolls back. The client
+		// expects atomic semantics for a bulk star/colour stamp.
+		err := db.Transaction(func(tx *gorm.DB) error {
+			for _, uid := range body.IDs {
+				if uid == "" {
+					continue
+				}
+				out, err := upsert(tx, uid, userName, &body.Patch)
+				if err != nil {
+					return err
+				}
+				applied[uid] = out
+			}
+			return nil
+		})
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{
+			"count": len(applied),
+			"marks": applied,
+		})
+	}
+}

sidecar/handlers_photos.go

@@ -0,0 +1,141 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+// handlePhotos proxies PhotoPrism's /api/v1/photos and then post-filters
+// the response so only photos under the caller's BasePath are returned.
+// This fixes the review/archive tab cross-user leak.
+//
+// Route: GET /api/sidecar/timeline  (behind requireSession)
+func handlePhotos(pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		basePath := ctxBasePath(c)
+
+		// Forward the raw query string to PhotoPrism.
+		query := c.Request.URL.RawQuery
+
+		resp, err := pp.call(c.Request.Context(), http.MethodGet, "/api/v1/photos?"+query, token, nil)
+		if err != nil || !resp.OK {
+			c.JSON(http.StatusBadGateway, gin.H{"error": "upstream photos request failed"})
+			return
+		}
+
+		// Decode as a generic array so we can inspect Path without
+		// committing to a rigid struct (PhotoPrism's photo response
+		// varies between list/detail/search endpoints).
+		var photos []map[string]any
+		if err := json.Unmarshal(resp.Body, &photos); err != nil {
+			// If it's not an array (e.g. error, single object), pass through.
+			c.Data(resp.Status, "application/json", resp.Body)
+			return
+		}
+
+		// If the user has no BasePath (admin/empty), return as-is.
+		if basePath == "" {
+			// Forward PhotoPrism's X-Count header for countPhotos().
+			if count := resp.Header.Get("X-Count"); count != "" {
+				c.Header("X-Count", count)
+			}
+			c.JSON(http.StatusOK, photos)
+			return
+		}
+
+		prefix := basePath + "/"
+
+		// Post-filter by FileName field (originals-relative path).
+		filtered := make([]map[string]any, 0, len(photos))
+		for _, ph := range photos {
+			rawPath, ok := ph["FileName"]
+			if !ok {
+				continue
+			}
+			pathStr, ok := rawPath.(string)
+			if !ok {
+				continue
+			}
+			// Match exact basePath or basePath/...
+			if pathStr == basePath || strings.HasPrefix(pathStr, prefix) {
+				filtered = append(filtered, ph)
+			}
+		}
+
+		// Forward X-Count header adjusted to the filtered count.
+		c.Header("X-Count", itoa(len(filtered)))
+		c.JSON(http.StatusOK, filtered)
+	}
+}
+
+// handleNotes pages PhotoPrism's photo list to completion and returns only
+// photos carrying a non-empty Caption (mule-image's "Note"), scoped to the
+// caller's BasePath. Paging server-side is what makes this correct: the
+// client can't tell when the *BasePath-filtered* list is exhausted (a full
+// upstream page can filter down to a short — or empty — slice), but here we
+// can key the loop off the raw upstream page length.
+//
+// Route: GET /api/sidecar/notes  (behind requireSession)
+func handleNotes(pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		basePath := ctxBasePath(c)
+		prefix := basePath + "/"
+
+		const pageSize = 1000
+		out := make([]map[string]any, 0, 64)
+		seen := make(map[string]struct{})
+
+		for offset := 0; ; offset += pageSize {
+			path := fmt.Sprintf("/api/v1/photos?count=%d&offset=%d&merged=true&order=newest", pageSize, offset)
+			resp, err := pp.call(c.Request.Context(), http.MethodGet, path, token, nil)
+			if err != nil || !resp.OK {
+				c.JSON(http.StatusBadGateway, gin.H{"error": "upstream photos request failed"})
+				return
+			}
+
+			var photos []map[string]any
+			if err := json.Unmarshal(resp.Body, &photos); err != nil {
+				c.JSON(http.StatusBadGateway, gin.H{"error": "unexpected photos response"})
+				return
+			}
+			rawLen := len(photos)
+
+			for _, ph := range photos {
+				// BasePath scope — same rule as handlePhotos.
+				if basePath != "" {
+					pathStr, _ := ph["FileName"].(string)
+					if pathStr != basePath && !strings.HasPrefix(pathStr, prefix) {
+						continue
+					}
+				}
+				// Non-empty caption only.
+				caption, _ := ph["Caption"].(string)
+				if strings.TrimSpace(caption) == "" {
+					continue
+				}
+				// Dedupe by UID — `merged` can still repeat a photo at a page seam.
+				uid, _ := ph["UID"].(string)
+				if uid != "" {
+					if _, ok := seen[uid]; ok {
+						continue
+					}
+					seen[uid] = struct{}{}
+				}
+				out = append(out, ph)
+			}
+
+			// A short upstream page means PhotoPrism has no more rows.
+			if rawLen < pageSize {
+				break
+			}
+		}
+
+		c.JSON(http.StatusOK, out)
+	}
+}

sidecar/handlers_rename.go

@@ -0,0 +1,143 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+// renameBody mirrors the Node prototype's wire contract — a single
+// `newName` field carrying the bare basename (no slashes).
+type renameBody struct {
+	NewName string `json:"newName"`
+}
+
+// ppPhoto is the partial PhotoPrism photo shape we need to find the
+// primary file's on-disk location. Anything we don't read stays
+// unspecified so version drift across PhotoPrism builds doesn't break
+// JSON unmarshalling.
+type ppPhoto struct {
+	Files []ppFile `json:"Files"`
+}
+
+type ppFile struct {
+	Name    string `json:"Name"`
+	Root    string `json:"Root"`
+	Primary bool   `json:"Primary"`
+}
+
+func primaryFileOf(p *ppPhoto) (ppFile, bool) {
+	if p == nil {
+		return ppFile{}, false
+	}
+	for _, f := range p.Files {
+		if f.Primary {
+			return f, true
+		}
+	}
+	if len(p.Files) > 0 {
+		return p.Files[0], true
+	}
+	return ppFile{}, false
+}
+
+func handleRename(cfg *Config, pp *ppClient) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := ctxToken(c)
+		photoUID := c.Param("uid")
+
+		var body renameBody
+		if err := c.ShouldBindJSON(&body); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid json"})
+			return
+		}
+		newName, ok := sanitizeFilename(body.NewName)
+		if !ok {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "newName must be a plain filename"})
+			return
+		}
+
+		// Fetch the photo so we can resolve Files[0].Root + Name into a
+		// concrete on-disk path. PhotoPrism has no "file by UID" endpoint
+		// in this build, so the single-photo lookup is the cheapest path.
+		resp, err := pp.call(c.Request.Context(), http.MethodGet, "/api/v1/photos/"+photoUID, token, nil)
+		if err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+			return
+		}
+		if !resp.OK {
+			c.JSON(resp.Status, gin.H{"error": "photo not found"})
+			return
+		}
+		var photo ppPhoto
+		if err := json.Unmarshal(resp.Body, &photo); err != nil {
+			c.JSON(http.StatusBadGateway, gin.H{"error": "decode photo"})
+			return
+		}
+		file, ok := primaryFileOf(&photo)
+		if !ok {
+			c.JSON(http.StatusNotFound, gin.H{"error": "no files on this photo"})
+			return
+		}
+
+		root := strings.TrimPrefix(file.Root, "/")
+		if root == "" || root == "/" {
+			root = ""
+		}
+		relPath := filepath.Join(root, file.Name)
+		oldAbs := filepath.Join(cfg.OriginalsRoot, relPath)
+
+		if !ensureWithinOriginals(cfg.OriginalsRoot, oldAbs) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "path escapes originals root"})
+			return
+		}
+		st, err := os.Stat(oldAbs)
+		if err != nil || !st.Mode().IsRegular() {
+			c.JSON(http.StatusNotFound, gin.H{"error": "file missing on disk"})
+			return
+		}
+		newAbs := filepath.Join(filepath.Dir(oldAbs), newName)
+		if !ensureWithinOriginals(cfg.OriginalsRoot, newAbs) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "new path escapes originals root"})
+			return
+		}
+		if _, err := os.Stat(newAbs); err == nil {
+			c.JSON(http.StatusConflict, gin.H{"error": "target filename already exists"})
+			return
+		} else if !errors.Is(err, os.ErrNotExist) {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+
+		newRel := filepath.Join(root, newName)
+		slog.Info("rename", "from", relPath, "to", newRel)
+		if err := os.Rename(oldAbs, newAbs); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+
+		// Trigger reindex on the parent so PhotoPrism picks up the new
+		// filename and drops the orphan row for the old name. Best-effort.
+		reindexPath := "/"
+		if root != "" {
+			reindexPath = "/" + root
+		}
+		if err := pp.reindex(c.Request.Context(), token, reindexPath); err != nil {
+			slog.Warn("rename reindex failed", "err", err)
+		}
+
+		c.JSON(http.StatusOK, gin.H{
+			"ok":         true,
+			"oldName":    file.Name,
+			"newName":    newName,
+			"oldRelPath": relPath,
+			"newRelPath": newRel,
+		})
+	}
+}

sidecar/main.go

@@ -0,0 +1,151 @@
+// mule-sidecar — Go service for endpoints PhotoPrism does not expose.
+//
+// Ports the Node prototype (server.mjs) to the stack the merge plan calls
+// out: Go + Gin + GORM + MariaDB. Same wire contract as the prototype so
+// the SvelteKit web client doesn't need to change.
+//
+// Auth model is unchanged: the caller's X-Auth-Token is the only authority.
+// requireSession validates it against PhotoPrism's /api/v1/photos before
+// any destructive op runs.
+package main
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+func main() {
+	slog.SetDefault(slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
+		Level: slog.LevelInfo,
+	})))
+
+	cfg, err := loadConfig()
+	if err != nil {
+		slog.Error("config", "err", err)
+		os.Exit(1)
+	}
+
+	db, err := openDB(cfg.DSN)
+	if err != nil {
+		slog.Error("db open", "err", err)
+		os.Exit(1)
+	}
+	pp := newPPClient(cfg.PhotoprismBaseURL)
+
+	// Apply any declared username→BasePath mapping to PhotoPrism's
+	// auth_users table. Runs immediately + every 60s thereafter so a
+	// user who logs in after the sidecar booted still gets their
+	// BasePath wired without an admin restart.
+	startUserBasepathReconciler(cfg)
+
+	// Open a second DB handle pointed at PhotoPrism's own schema for
+	// handlers that need to query auth_users, photos, labels, etc.
+	// May be nil if PpDSN is empty (no PP_DB_PASSWORD set).
+	var ppDb *gorm.DB
+	if cfg.PpDSN != "" {
+		if d, err := openDB(cfg.PpDSN); err == nil {
+			ppDb = d
+		} else {
+			slog.Warn("pp db open failed — scoped labels/counts unavailable", "err", err)
+		}
+	}
+
+	gin.SetMode(gin.ReleaseMode)
+	r := gin.New()
+	// Keep `%2F` literal in path params so callers can pass URL-encoded
+	// nested folder paths (e.g. `foo%2Fbar`) without the router splitting
+	// them into separate segments. Handlers decode via url.PathUnescape.
+	r.UseRawPath = true
+	r.UnescapePathValues = false
+	r.Use(gin.Recovery())
+
+	// Health probe — unauthenticated so a process supervisor can call it
+	// without needing PhotoPrism to be reachable.
+	r.GET("/api/sidecar/healthz", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{
+			"ok":            true,
+			"originalsRoot": cfg.OriginalsRoot,
+		})
+	})
+
+	// Every other endpoint runs behind the session gate. Mounting them
+	// under one group keeps the middleware wiring obvious.
+		auth := r.Group("/api/sidecar", requireSession(pp))
+		{
+			auth.GET("/photos/marks", handleMarksAll(db))
+			auth.GET("/photos/:uid/marks", handleMarkGet(db))
+			auth.PUT("/photos/:uid/marks", handleMarkPut(db))
+			auth.POST("/photos/marks/bulk", handleMarkBulk(db))
+
+			auth.POST("/files/:uid/rename", handleRename(cfg, pp))
+
+			auth.POST("/folders", handleFolderCreate(cfg, pp))
+			auth.POST("/folders/counts", handleFolderCounts(pp))
+			auth.POST("/folders/:rel/rename", handleFolderRename(cfg, pp))
+			auth.DELETE("/folders/:rel", handleFolderDelete(cfg, pp))
+
+			auth.POST("/albums/:uid/convert", handleHeapConvert(cfg, pp))
+
+			auth.GET("/duplicates/scan", handleDupScan(cfg, pp))
+			auth.POST("/duplicates/archive", handleDupArchive(cfg, pp))
+
+						// User-scoped proxies — require PpDSN connection.
+						if ppDb != nil {
+							auth.GET("/labels", handleLabels(pp, ppDb))
+							auth.GET("/counts", handleScopedCounts(ppDb))
+						}
+
+						// User-scoped photos — post-filters by BasePath so review/archive
+									// tabs only show photos the user owns.
+									auth.GET("/timeline", handlePhotos(pp))
+
+									// Photos carrying a Note (Caption) — pages PhotoPrism fully so
+									// the /notes view isn't capped to the newest slice.
+									auth.GET("/notes", handleNotes(pp))
+
+									// User-scoped folders — post-filters the folder tree by BasePath
+									// so the sidebar shows only folders under the user's library root.
+									auth.GET("/folders", handleFoldersProxy(pp))
+					}
+
+	addr := cfg.ListenAddr + ":" + itoa(cfg.Port)
+	srv := &http.Server{
+		Addr:              addr,
+		Handler:           r,
+		ReadHeaderTimeout: 5 * time.Second,
+	}
+
+	// Graceful shutdown so an in-flight duplicate scan or heap convert
+	// gets a chance to finish (or at least flush logs) on SIGTERM.
+	idleClosed := make(chan struct{})
+	go func() {
+		sigs := make(chan os.Signal, 1)
+		signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+		<-sigs
+		slog.Info("shutdown signal received")
+		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		_ = srv.Shutdown(ctx)
+		close(idleClosed)
+	}()
+
+	slog.Info("mule-sidecar listening",
+		"addr", "http://"+addr,
+		"originals", cfg.OriginalsRoot,
+	)
+	if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+		slog.Error("listen", "err", err)
+		os.Exit(1)
+	}
+	<-idleClosed
+}
+

sidecar/pp.go

@@ -0,0 +1,158 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"time"
+)
+
+// ppClient is the thin HTTP wrapper around PhotoPrism's /api/v1. It is
+// deliberately *not* shared across requests with caching: each handler
+// forwards the caller's X-Auth-Token, so a single shared http.Client (we
+// reuse the stdlib default) plus per-call header injection is all we need.
+type ppClient struct {
+	base string
+	h    *http.Client
+}
+
+func newPPClient(base string) *ppClient {
+	return &ppClient{
+		base: base,
+		h:    &http.Client{Timeout: 60 * time.Second},
+	}
+}
+
+// ppResp is the trimmed projection of an HTTP response that callers
+// actually consume. Status + raw body are exposed so handlers can mirror
+// PhotoPrism's status code or parse the body themselves. Header is
+// retained for callers that need `X-Count` / `X-Limit` / `X-Offset` on
+// list endpoints — PhotoPrism exposes total-match counts there.
+type ppResp struct {
+	OK     bool
+	Status int
+	Body   []byte
+	Header http.Header
+}
+
+// call issues an authenticated request against PhotoPrism. body is
+// optional; pass nil for GET/DELETE. We don't JSON-decode here — callers
+// know the shape they want and decode lazily.
+func (c *ppClient) call(ctx context.Context, method, urlPath, token string, body any) (*ppResp, error) {
+	u, err := url.Parse(c.base)
+	if err != nil {
+		return nil, err
+	}
+	rel, err := url.Parse(urlPath)
+	if err != nil {
+		return nil, err
+	}
+	full := u.ResolveReference(rel).String()
+
+	var reader io.Reader
+	if body != nil {
+		buf, err := json.Marshal(body)
+		if err != nil {
+			return nil, err
+		}
+		reader = bytes.NewReader(buf)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, method, full, reader)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("X-Auth-Token", token)
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.h.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	buf, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, err
+	}
+	return &ppResp{
+		OK:     resp.StatusCode >= 200 && resp.StatusCode < 300,
+		Status: resp.StatusCode,
+		Body:   buf,
+		Header: resp.Header,
+	}, nil
+}
+
+// ppSessionUser is the subset of PhotoPrism's session response we need.
+type ppSessionUser struct {
+	UserUID  string `json:"UID"`
+	UserName string `json:"Name"`
+	BasePath string `json:"BasePath"`
+}
+
+type ppSessionResponse struct {
+	User ppSessionUser `json:"user"`
+}
+
+// resolveSession validates the token AND returns the authenticated user.
+// Returns nil when the token is invalid or the response can't be parsed.
+func (c *ppClient) resolveSession(ctx context.Context, token string) *ppSessionUser {
+	if token == "" {
+		return nil
+	}
+	r, err := c.call(ctx, http.MethodGet, "/api/v1/session", token, nil)
+	if err != nil {
+		slog.Warn("resolveSession: call failed", "err", err)
+		return nil
+	}
+	if !r.OK {
+		slog.Warn("resolveSession: not OK", "status", r.Status, "body", string(r.Body[:min(len(r.Body), 200)]))
+		return nil
+	}
+	var resp ppSessionResponse
+	if err := json.Unmarshal(r.Body, &resp); err != nil {
+		slog.Warn("resolveSession: unmarshal failed", "err", err, "body", string(r.Body[:min(len(r.Body), 200)]))
+		return nil
+	}
+	if resp.User.UserName == "" {
+		slog.Warn("resolveSession: empty username", "body", string(r.Body[:min(len(r.Body), 200)]))
+		return nil
+	}
+	return &resp.User
+}
+
+// validateSession is the cheapest probe that the supplied token is live:
+// list one photo. 401 → bad/expired token. We never read the payload.
+func (c *ppClient) validateSession(ctx context.Context, token string) bool {
+	if token == "" {
+		return false
+	}
+	r, err := c.call(ctx, http.MethodGet, "/api/v1/photos?count=1", token, nil)
+	if err != nil {
+		return false
+	}
+	return r.OK
+}
+
+// reindex tells PhotoPrism to re-walk a single subpath of originals and
+// reconcile its DB with the on-disk state. Callers fire this after any
+// rename/create/delete so the timeline catches up. `cleanup: true` drops
+// orphan rows (e.g. the row for the file's old name after a rename).
+//
+// Best-effort: errors are surfaced to the caller, who logs but does not
+// abort — the file mutation has already happened on disk by the time
+// reindex runs.
+func (c *ppClient) reindex(ctx context.Context, token, parentRel string) error {
+	if parentRel == "" {
+		parentRel = "/"
+	}
+	_, err := c.call(ctx, http.MethodPost, "/api/v1/index", token, map[string]any{
+		"path":    parentRel,
+		"rescan":  false,
+		"cleanup": true,
+	})
+	return err
+}

sidecar/users.go

@@ -0,0 +1,124 @@
+package main
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"gorm.io/driver/mysql"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+// PhotoPrism's open-source edition doesn't expose any way to map OIDC
+// claims to a per-user BasePath — every newly-registered OIDC user
+// lands with `BasePath = ""`, which means PhotoPrism's ACL filter
+// shows them nothing (non-admin) or everything (admin). Neither is the
+// per-user library scope a homelab admin typically wants.
+//
+// This reconciler reads a declarative `USER_BASEPATHS` env at sidecar
+// startup, formatted as `username:originals-relative-path` pairs
+// separated by commas (whitespace tolerated), e.g.:
+//
+//	USER_BASEPATHS="test:test, alice:family/alice, bob:bob"
+//
+// For every entry the sidecar:
+//  1. Ensures the originals subdirectory exists (so PhotoPrism's path:
+//     filter has somewhere to point — empty dirs are fine).
+//  2. UPDATEs `photoprism.auth_users.base_path` for the matching user
+//     row if the current value differs. Idempotent: rows already
+//     matching are skipped, and missing users are no-ops (they'll
+//     materialise when they log in via OIDC; the periodic ticker
+//     catches them on the next pass).
+//
+// A 60-second ticker keeps the mapping in lockstep with new OIDC
+// registrations without needing a webhook.
+
+func parseUserBasepaths(raw string) map[string]string {
+	out := map[string]string{}
+	for _, p := range strings.Split(raw, ",") {
+		p = strings.TrimSpace(p)
+		if p == "" {
+			continue
+		}
+		bits := strings.SplitN(p, ":", 2)
+		if len(bits) != 2 {
+			continue
+		}
+		u := strings.TrimSpace(bits[0])
+		// Strip any leading/trailing slash so the value lands in
+		// auth_users.base_path the same way PhotoPrism's own user-edit
+		// UI persists it (relative, no slashes).
+		path := strings.Trim(strings.TrimSpace(bits[1]), "/")
+		if u == "" || path == "" {
+			continue
+		}
+		out[u] = path
+	}
+	return out
+}
+
+func reconcileUserBasepaths(ppDSN, originalsRoot string, mapping map[string]string) error {
+	if len(mapping) == 0 {
+		return nil
+	}
+	if ppDSN == "" {
+		return fmt.Errorf("USER_BASEPATHS set but PP_DB_PASSWORD missing — can't reach photoprism schema")
+	}
+	db, err := gorm.Open(mysql.Open(ppDSN), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Warn),
+	})
+	if err != nil {
+		return fmt.Errorf("open pp db: %w", err)
+	}
+	if sqlDB, derr := db.DB(); derr == nil {
+		defer sqlDB.Close()
+	}
+
+	for username, path := range mapping {
+		target := filepath.Join(originalsRoot, path)
+		if err := os.MkdirAll(target, 0o775); err != nil {
+			slog.Warn("user-basepath: mkdir failed", "user", username, "path", target, "err", err)
+			// Continue — the DB update is still useful so PhotoPrism's
+			// ACL kicks in even if the directory is created later.
+		}
+
+		res := db.Exec(`UPDATE auth_users
+			SET base_path = ?
+			WHERE user_name = ?
+			  AND COALESCE(base_path, '') <> ?
+			  AND deleted_at IS NULL`,
+			path, username, path)
+		if res.Error != nil {
+			slog.Error("user-basepath: update failed", "user", username, "err", res.Error)
+			continue
+		}
+		if res.RowsAffected > 0 {
+			slog.Info("user-basepath: set", "user", username, "path", path)
+		}
+	}
+	return nil
+}
+
+func startUserBasepathReconciler(cfg *Config) {
+	if len(cfg.UserBasepaths) == 0 {
+		return
+	}
+	slog.Info("user-basepath: starting reconciler", "entries", len(cfg.UserBasepaths))
+	apply := func() {
+		if err := reconcileUserBasepaths(cfg.PpDSN, cfg.OriginalsRoot, cfg.UserBasepaths); err != nil {
+			slog.Warn("user-basepath: reconciliation error", "err", err)
+		}
+	}
+	apply()
+	go func() {
+		t := time.NewTicker(60 * time.Second)
+		defer t.Stop()
+		for range t.C {
+			apply()
+		}
+	}()
+}