feat(compose): opt-in GPU overlay for VA-API ffmpeg accel

Layer docker-compose.gpu.yml to mount /dev/dri/{card0,renderD128}
into pp-app, add it to render (992) + video (44) groups, and set
PHOTOPRISM_FFMPEG_ENCODER=vaapi. Hosts without a VA-API device just
skip the overlay (`-f docker-compose.yml -f docker-compose.gpu.yml`
becomes opt-in per deploy).

Drops video transcode + thumbnail generation from CPU to the iGPU
where present — large win for HEVC libraries. README documents the
flag; default behavior on the base compose is unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.env

@@ -1,30 +0,0 @@
-# Environment variables for Mulita
-#
-# Set PHOTO_DIRS to the HOST path of your photo library. The compose file
-# mounts this at /photos inside the container, and on first boot Mulita
-# auto-creates a source root pointing at /photos so your library is
-# scanned with zero further configuration.
-#
-# Examples:
-#   macOS / Linux:    PHOTO_DIRS=/Users/you/Pictures
-#   Network share:    PHOTO_DIRS=/mnt/nas/photos
-#   Windows (WSL):    PHOTO_DIRS=/mnt/c/Users/you/Pictures
-PHOTO_DIRS=/Users/dtoro/Pictures/MulitaTest
-
-# 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,70 @@
+# 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
+
+
+# ── 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/

README.md

@@ -1,198 +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
-
-### Setup (one variable)
-
-1. Clone the repo:
-```bash
-git clone <repository-url>
-cd muleimage
-```
-
-2. Set **one** environment variable in `.env` — the **host** directory
-   that contains your photo library. Whatever you point at will become
-   your library inside Mulita.
-
-   ```bash
-   # macOS / Linux
-   PHOTO_DIRS=/Users/you/Pictures
-
-   # or any folder
-   PHOTO_DIRS=/mnt/nas/photos
-
-   # Windows (WSL)
-   PHOTO_DIRS=/mnt/c/Users/you/Pictures
-   ```
-
-3. Start the stack:
-```bash
-docker compose up -d
-```
-
-4. Open `http://localhost:3000`. On first boot Mulita will:
-   - Mount your `PHOTO_DIRS` at `/photos` inside the container
-   - Auto-create a source root called **Library** pointing at `/photos`
-   - Queue an initial scan, generate thumbnails, and start serving them
-
-You don't need to touch `mulita.yml` or the API to get started.
-
-### How libraries are managed
-
-Mulita is **config-driven**: the host directory you mount via
-`PHOTO_DIRS` becomes your library, and the backend automatically
-registers it as a source root on startup. There is no UI for adding
-or removing source roots — to change what Mulita scans, edit `.env`
-(or `docker-compose.yml` for multi-mount setups) and restart the
-stack.
-
-This keeps the model simple: **the docker mount IS the library**.
-No two layers, no confusion about which view to use.
-
-### Changing or adding libraries
-
-To point at a different library:
-1. Edit `PHOTO_DIRS` in `.env`
-2. `docker compose down`
-3. (Optional, for a clean slate) `docker volume rm muleimage_db_data muleimage_thumbs_data muleimage_proxies_data`
-4. `docker compose up -d`
-
-The new library shows up automatically. Without step 3 the old
-library's metadata stays in the DB and you'll see a warning at
-startup that the old source root's path is missing on disk —
-that's a hint to clean up.
-
-For multiple libraries, edit `docker-compose.yml` and add additional
-mount lines:
-
-```yaml
-volumes:
-  - ${PHOTO_DIRS}:/photos:rw
-  - /Volumes/Archive:/archive:rw   # additional library
-```
-
-Each mounted directory will need a corresponding source root row in
-the DB; today that means `POST /api/v1/folders` via curl, or wait
-for the multi-mount auto-registration that's on the roadmap.
-
-### Read-only libraries
-
-The default mount is `:rw` because file operations (rename, move,
-empty discard pile) need to mutate the filesystem. If you want a
-strict read-only library — pointing at a network share, an
-authoritative archive, etc. — flip `:rw` to `:ro` in
-`docker-compose.yml`. Mulita will keep working for browsing, rating,
-color labels, picks, heaps, and the (soft) discard flag, but the
-following will return an OS error:
-
-- `PATCH /photos/{id}` with a new `filename` (rename)
-- `POST /photos/move` (bulk move)
-- `DELETE /discard/empty` (file unlinks)
-
-**Heads up**: with `:rw`, Mulita has full write access to whatever
-host directory you mount. 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
 
-Source roots are managed by the UI / API (the database owns them). Edit
-`mulita.yml` to configure operational settings only:
+All knobs live in [`.env.example`](.env.example). The required ones:
 
-- Thumbnail sizes, quality, and format
-- Scanner behaviour (watch, batch size, initial scan)
-- Performance tuning (concurrency, cache TTLs, DB pool)
+| 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`).                                          |
 
-## Performance
+Sidecar-specific env (DB DSN, `USER_BASEPATHS`, etc.) is documented in
+[`sidecar/README.md`](sidecar/README.md).
 
-- Handles 100,000+ photos efficiently
-- Virtual scrolling for smooth timeline navigation
-- Thumbnail generation at 10+ photos/second
-- SQLite FTS5 for fast full-text search
+## Read-only libraries
 
-## Future Features (Phase 2)
+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:
 
-- AI-powered scene classification
-- Face detection and clustering
-- Smart albums
-- Duplicate detection
-- Export presets
-- Multi-user support
+- `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`
 
-## License
+PhotoPrism's `PHOTOPRISM_READONLY` is controlled separately by
+`PP_READONLY` and gates its own backwrite / import paths.
 
-MIT
+## 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/proxies /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,111 +0,0 @@
-"""
-Application configuration using Pydantic Settings
-"""
-from pydantic_settings import BaseSettings
-from pydantic import BaseModel, Field
-from typing import Optional
-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 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 and the discard
-    workflow are owned by the database now — only operational settings
-    live here."""
-    thumbnails: ThumbnailSettings = ThumbnailSettings()
-    scanner: ScannerSettings = ScannerSettings()
-    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 performance(self) -> PerformanceSettings:
-        return self.config.performance
-
-    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,98 +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, bootstrap_default_source_root
-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()
-
-    # First-boot convenience: if there are no source roots in the DB yet,
-    # create one for the default /photos mount so the user sees their
-    # library immediately without configuring anything in the UI.
-    try:
-        await bootstrap_default_source_root()
-    except Exception as e:
-        logger.error(f"Bootstrap source root failed (continuing): {e}")
-
-    # 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,193 +0,0 @@
-"""
-Folders API router. Source roots themselves are config-driven (PHOTO_DIRS
-in .env → backend bootstrap on startup) — adding or removing one is a
-docker-compose change. The UI can read the list, trigger a manual rescan,
-and rename the display label, but it can't change the on-disk path.
-"""
-from fastapi import APIRouter, Depends, HTTPException
-from pydantic import BaseModel
-from sqlalchemy import select, func
-from sqlalchemy.ext.asyncio import AsyncSession
-import os
-
-from app.database import get_db
-from app.models import Folder, SourceRoot, Photo
-
-router = APIRouter()
-
-
-class FolderRename(BaseModel):
-    name: str
-
-@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.get("/tree")
-async def get_folder_tree(db: AsyncSession = Depends(get_db)):
-    """Recursive folder tree, one root per active SourceRoot. The tree
-    starts at the Folder row matching the SourceRoot.path (the scanner
-    creates one for every walked directory), with the SourceRoot's
-    display name overlaid so the top-level entry reads as "Library"
-    instead of "/photos".
-
-    Returns a list of root nodes; each node has:
-        { id, name, path, photo_count, children: [...] }
-
-    photo_count is **recursive** — every node reports the total non-
-    discarded photos in its own subtree, so the badge matches what the
-    user sees when they click the row (which also filters recursively).
-
-    The stored Folder.photo_count column is intentionally NOT trusted;
-    the scanner's bookkeeping for that field has historically been
-    wrong (it leaks the global total into whichever folder os.walk
-    visited last). We compute counts here from the photos table.
-
-    Sub-folders that physically belong to the same source root but
-    weren't created on disk (e.g. the / row the scanner sometimes
-    creates as a parent walk) are skipped via path-prefix filtering.
-    """
-    sr_result = await db.execute(
-        select(SourceRoot).where(SourceRoot.is_active == True)  # noqa: E712
-    )
-    source_roots = sr_result.scalars().all()
-
-    out = []
-    for sr in source_roots:
-        # Folders physically inside this source root, by path prefix.
-        prefix = os.path.normpath(sr.path).rstrip(os.sep)
-        f_result = await db.execute(
-            select(Folder).where(
-                Folder.source_root_id == sr.id,
-                # Either the folder IS the source root, or it sits beneath it.
-                (Folder.path == prefix) | (Folder.path.like(prefix + os.sep + '%'))
-            )
-        )
-        folders = f_result.scalars().all()
-        if not folders:
-            continue
-
-        # Direct (non-recursive) photo counts per folder, computed from
-        # the photos table. Excludes discarded.
-        folder_ids = [f.id for f in folders]
-        direct_counts: dict[str, int] = {}
-        if folder_ids:
-            count_result = await db.execute(
-                select(Photo.folder_id, func.count(Photo.id))
-                .where(
-                    Photo.is_discarded == False,  # noqa: E712
-                    Photo.folder_id.in_(folder_ids),
-                )
-                .group_by(Photo.folder_id)
-            )
-            direct_counts = {row[0]: int(row[1]) for row in count_result.all()}
-
-        # Build a path → node map so we can attach children regardless of
-        # parent_id consistency. We populate photo_count with the direct
-        # count first, then accumulate descendants in a post-order pass.
-        nodes = {
-            f.path: {
-                "id": f.id,
-                "name": f.name or os.path.basename(f.path),
-                "path": f.path,
-                "photo_count": direct_counts.get(f.id, 0),
-                "children": [],
-            }
-            for f in folders
-        }
-
-        root_node = None
-        for f in folders:
-            node = nodes[f.path]
-            if f.path == prefix:
-                root_node = node
-                # Override the display name with the source root's label.
-                node["name"] = sr.name or node["name"]
-                continue
-            parent_path = os.path.normpath(os.path.dirname(f.path))
-            parent = nodes.get(parent_path)
-            if parent is not None:
-                parent["children"].append(node)
-            # If parent isn't in the set (orphan from a partial scan), drop
-            # the node — it can't be rendered consistently.
-
-        if root_node is not None:
-            # Sort children alphabetically at every level.
-            def sort_recursive(n):
-                n["children"].sort(key=lambda c: c["name"].lower())
-                for c in n["children"]:
-                    sort_recursive(c)
-            sort_recursive(root_node)
-
-            # Post-order: each node's recursive count is its own direct
-            # count plus the sum of every descendant's recursive count.
-            def accumulate(n) -> int:
-                total = n["photo_count"]
-                for c in n["children"]:
-                    total += accumulate(c)
-                n["photo_count"] = total
-                return total
-            accumulate(root_node)
-
-            out.append(root_node)
-
-    return out
-
-
-@router.patch("/{folder_id}")
-async def rename_folder(
-    folder_id: str,
-    body: FolderRename,
-    db: AsyncSession = Depends(get_db),
-):
-    """Rename a source root's display label. Does NOT touch the on-disk
-    path — that's controlled by the docker mount."""
-    name = (body.name or '').strip()
-    if not name:
-        raise HTTPException(status_code=400, detail="Name cannot be empty")
-
-    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")
-
-    source_root.name = name
-    await db.commit()
-    return {"id": source_root.id, "name": source_root.name, "path": source_root.path}
-
-
-@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,383 +0,0 @@
-"""
-Heaps API router
-"""
-import os
-import shutil
-import logging
-from typing import Optional, Literal
-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, Photo, Folder
-from app.models.folders import SourceRoot
-from app.models.heaps import heap_photos
-
-logger = logging.getLogger(__name__)
-
-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]
-
-
-class HeapConvertBody(BaseModel):
-    target_id: str  # folder id OR source root id
-    mode: Literal['move', 'copy'] = 'move'
-    delete_heap: bool = False
-    # Optional subfolder name to create inside the target. If provided, the
-    # actual destination is target_dir/subfolder_name (created if missing).
-    # Path separators and dot-segments are rejected.
-    subfolder_name: Optional[str] = None
-
-
-# ── 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.post("/{heap_id}/convert")
-async def convert_heap_to_folder(
-    heap_id: str,
-    body: HeapConvertBody,
-    db: AsyncSession = Depends(get_db),
-):
-    """Convert a heap into a folder by moving (or copying) every member
-    photo into the target directory. Optionally deletes the heap row at
-    the end.
-
-    target_id may be a Folder id or a SourceRoot id (matches the
-    /photos/move convention so the same dropdown can populate it).
-    """
-    heap_result = await db.execute(select(Heap).where(Heap.id == heap_id))
-    heap = heap_result.scalar_one_or_none()
-    if not heap:
-        raise HTTPException(status_code=404, detail="Heap not found")
-
-    # Resolve target_id → (target_dir, target_folder)
-    sr_check = await db.execute(
-        select(SourceRoot).where(SourceRoot.id == body.target_id)
-    )
-    source_root = sr_check.scalar_one_or_none()
-
-    if source_root is not None:
-        parent_dir = source_root.path
-        parent_source_root_id = source_root.id
-    else:
-        folder_check = await db.execute(
-            select(Folder).where(Folder.id == body.target_id)
-        )
-        parent_folder = folder_check.scalar_one_or_none()
-        if parent_folder is None:
-            raise HTTPException(status_code=404, detail="Target folder not found")
-        parent_dir = parent_folder.path
-        parent_source_root_id = parent_folder.source_root_id
-
-    if not os.path.isdir(parent_dir):
-        raise HTTPException(
-            status_code=400,
-            detail=f"Target parent does not exist: {parent_dir}",
-        )
-
-    # Resolve target_dir, creating an optional subfolder if requested.
-    if body.subfolder_name is not None:
-        sub = body.subfolder_name.strip()
-        if not sub:
-            raise HTTPException(status_code=400, detail="Subfolder name cannot be empty")
-        if '/' in sub or '\\' in sub or sub in ('.', '..'):
-            raise HTTPException(status_code=400, detail="Invalid subfolder name")
-        target_dir = os.path.join(parent_dir, sub)
-        if not os.path.exists(target_dir):
-            try:
-                os.makedirs(target_dir)
-            except OSError as e:
-                raise HTTPException(
-                    status_code=500,
-                    detail=f"Failed to create subfolder: {e}",
-                )
-        elif not os.path.isdir(target_dir):
-            raise HTTPException(
-                status_code=400,
-                detail=f"{target_dir} exists but is not a directory",
-            )
-    else:
-        target_dir = parent_dir
-
-    # Ensure a Folder row for the target, reusing the scanner helper so
-    # path normalization + dedupe stay consistent.
-    from app.tasks.scan import get_or_create_folder
-    target_folder = await get_or_create_folder(db, target_dir, parent_source_root_id)
-
-    # Fetch the heap's photos via the join table.
-    photo_result = await db.execute(
-        select(Photo)
-        .join(heap_photos, Photo.id == heap_photos.c.photo_id)
-        .where(heap_photos.c.heap_id == heap_id)
-    )
-    photos = photo_result.scalars().all()
-
-    moved = 0
-    copied = 0
-    errors: list[dict] = []
-
-    def _unique_target_name(directory: str, filename: str) -> Optional[str]:
-        if not os.path.exists(os.path.join(directory, filename)):
-            return filename
-        stem, ext = os.path.splitext(filename)
-        for i in range(1, 100):
-            suffix = '' if i == 1 else f' {i}'
-            candidate = f"{stem} (copy{suffix}){ext}"
-            if not os.path.exists(os.path.join(directory, candidate)):
-                return candidate
-        return None
-
-    for photo in photos:
-        if not os.path.exists(photo.filepath):
-            errors.append({"id": photo.id, "error": "source file missing"})
-            continue
-
-        if body.mode == 'move':
-            if photo.folder_id == target_folder.id:
-                continue  # already there
-            new_path = os.path.join(target_dir, photo.filename)
-            if os.path.exists(new_path):
-                errors.append({"id": photo.id, "error": f"name collision: {photo.filename}"})
-                continue
-            try:
-                shutil.move(photo.filepath, new_path)
-            except OSError as e:
-                errors.append({"id": photo.id, "error": str(e)})
-                continue
-            photo.filepath = new_path
-            photo.folder_id = target_folder.id
-            moved += 1
-        else:  # copy
-            new_name = _unique_target_name(target_dir, photo.filename)
-            if new_name is None:
-                errors.append({"id": photo.id, "error": "too many name collisions"})
-                continue
-            new_path = os.path.join(target_dir, new_name)
-            try:
-                shutil.copy2(photo.filepath, new_path)
-            except OSError as e:
-                errors.append({"id": photo.id, "error": str(e)})
-                continue
-            new_photo = Photo(
-                filepath=new_path,
-                filename=new_name,
-                folder_id=target_folder.id,
-                file_hash=photo.file_hash,
-                media_type=photo.media_type,
-                original_format=photo.original_format,
-                width=photo.width,
-                height=photo.height,
-                file_size=photo.file_size,
-                taken_at=photo.taken_at,
-                taken_at_source=photo.taken_at_source,
-                user_title=photo.user_title,
-                user_notes=photo.user_notes,
-                rating=photo.rating,
-                color_label=photo.color_label,
-                exif_json=photo.exif_json,
-                is_duplicate=True,
-                processing_status='pending',
-            )
-            db.add(new_photo)
-            copied += 1
-
-    if body.delete_heap:
-        await db.delete(heap)
-
-    await db.commit()
-
-    return {
-        "status": "success",
-        "mode": body.mode,
-        "moved": moved,
-        "copied": copied,
-        "errors": errors,
-        "heap_deleted": body.delete_heap,
-    }
-
-
-@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,860 +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 pydantic import BaseModel
-from sqlalchemy import select, and_, or_, func
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import selectinload
-import json
-import os
-import logging
-
-logger = logging.getLogger(__name__)
-
-from app.database import get_db
-from app.models import Photo, Folder, Tag
-from app.models.folders import SourceRoot
-from app.models.heaps import heap_photos
-from app.models.tags import photo_tags
-from app.schemas.photos import PhotoResponse, PhotoUpdate, PhotoListResponse, BulkAction
-from app.config import settings
-
-router = APIRouter()
-
-@router.get("")
-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,
-    is_duplicate: Optional[bool] = None,
-    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 — eager-load tags so the response can include them
-    # without an N+1 round-trip per photo.
-    query = select(Photo).options(selectinload(Photo.tags))
-    
-    # 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 can pass either a SourceRoot id or a
-    # Folder id; both should include descendants so clicking a parent
-    # folder shows everything under it (Lightroom semantics).
-    if folder_id:
-        sr_check = await db.execute(
-            select(SourceRoot).where(SourceRoot.id == folder_id)
-        )
-        sr_row = sr_check.scalar_one_or_none()
-
-        if sr_row is not None:
-            # Source root → all folders under it (any depth).
-            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:
-                filters.append(Photo.id == '__no_match__')
-        else:
-            # Folder id → that folder + every descendant by path prefix.
-            target_check = await db.execute(
-                select(Folder).where(Folder.id == folder_id)
-            )
-            target = target_check.scalar_one_or_none()
-            if target is None:
-                filters.append(Photo.id == '__no_match__')
-            else:
-                target_path = os.path.normpath(target.path).rstrip(os.sep)
-                desc_result = await db.execute(
-                    select(Folder.id).where(
-                        (Folder.path == target_path)
-                        | (Folder.path.like(target_path + os.sep + '%'))
-                    )
-                )
-                desc_ids = [row[0] for row in desc_result.all()]
-                filters.append(Photo.folder_id.in_(desc_ids))
-    
-    # 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)
-
-    # Duplicate filter — only applied when explicitly set, so the default
-    # view shows everything regardless of duplicate status.
-    if is_duplicate is not None:
-        filters.append(Photo.is_duplicate == is_duplicate)
-
-    # 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)
-            )
-        )
-
-    # Tag filter — comma-separated tag ids, AND semantics. A photo must
-    # have a row in photo_tags for EVERY listed tag. Implemented as one
-    # subquery per tag id since SQLite doesn't have an efficient
-    # "set-contains-all" operator.
-    if tag_ids:
-        tag_id_list = [t.strip() for t in tag_ids.split(',') if t.strip()]
-        for tid in tag_id_list:
-            filters.append(
-                Photo.id.in_(
-                    select(photo_tags.c.photo_id).where(photo_tags.c.tag_id == tid)
-                )
-            )
-
-    # 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, attaching tags inline so the frontend can group
-    # client-side without a second round-trip.
-    photo_dicts = []
-    for photo in photos:
-        d = PhotoResponse.from_orm(photo).dict()
-        d["tags"] = [
-            {"id": t.id, "name": t.name, "color": t.color}
-            for t in (photo.tags or [])
-        ]
-        photo_dicts.append(d)
-
-    return {
-        "photos": photo_dicts,
-        "total": total,
-        "page": page,
-        "per_page": per_page,
-        "pages": (total + per_page - 1) // per_page if total else 0,
-    }
-
-@router.get("/{photo_id}")
-async def get_photo(
-    photo_id: str,
-    db: AsyncSession = Depends(get_db)
-):
-    """Get single photo with full EXIF and its 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")
-
-    # Fetch tags via the join table so we don't need to declare a
-    # relationship on the Photo model side.
-    tag_result = await db.execute(
-        select(Tag)
-        .join(photo_tags, Tag.id == photo_tags.c.tag_id)
-        .where(photo_tags.c.photo_id == photo_id)
-        .order_by(Tag.name.asc())
-    )
-    tags = tag_result.scalars().all()
-
-    base = PhotoResponse.from_orm(photo).dict()
-    base["tags"] = [
-        {"id": t.id, "name": t.name, "color": t.color} for t in tags
-    ]
-    return base
-
-
-@router.post("/{photo_id}/tags", status_code=201)
-async def add_photo_tags(
-    photo_id: str,
-    body: dict,
-    db: AsyncSession = Depends(get_db),
-):
-    """Add one or more tags to a photo. Body: { tag_ids: [str, ...] }.
-    Idempotent: re-adding existing members is a no-op."""
-    photo_result = await db.execute(select(Photo).where(Photo.id == photo_id))
-    if photo_result.scalar_one_or_none() is None:
-        raise HTTPException(status_code=404, detail="Photo not found")
-
-    tag_ids = body.get("tag_ids") or []
-    if not isinstance(tag_ids, list) or not tag_ids:
-        return {"status": "success", "added": 0}
-
-    existing = await db.execute(
-        select(photo_tags.c.tag_id).where(
-            photo_tags.c.photo_id == photo_id,
-            photo_tags.c.tag_id.in_(tag_ids),
-        )
-    )
-    existing_ids = {row[0] for row in existing.all()}
-    new_ids = [tid for tid in tag_ids if tid not in existing_ids]
-
-    if new_ids:
-        from sqlalchemy import insert
-        await db.execute(
-            insert(photo_tags),
-            [{"photo_id": photo_id, "tag_id": tid} for tid in new_ids],
-        )
-        await db.commit()
-
-    return {"status": "success", "added": len(new_ids)}
-
-
-@router.delete("/{photo_id}/tags/{tag_id}", status_code=204)
-async def remove_photo_tag(
-    photo_id: str,
-    tag_id: str,
-    db: AsyncSession = Depends(get_db),
-):
-    """Remove a tag from a photo. Removing a non-member is a no-op."""
-    from sqlalchemy import delete as sql_delete
-    await db.execute(
-        sql_delete(photo_tags).where(
-            photo_tags.c.photo_id == photo_id,
-            photo_tags.c.tag_id == tag_id,
-        )
-    )
-    await db.commit()
-    return None
-
-@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"}
-
-class MoveRequest(BaseModel):
-    photo_ids: list[str]
-    target_id: str  # folder id OR source root id
-
-
-class CopyRequest(BaseModel):
-    photo_ids: list[str]
-    target_id: str  # folder id OR source root id
-
-
-@router.post("/copy")
-async def copy_photos(
-    body: CopyRequest,
-    db: AsyncSession = Depends(get_db),
-):
-    """Copy photos into a target folder. Same target resolution as /move
-    (folder id or source root id), but uses shutil.copy2 and creates new
-    Photo rows for each copied file. Original photos are unaffected.
-
-    Each new row gets is_duplicate=true so the user can spot the
-    duplicates later. The new file's name is suffixed with " (copy)" if
-    a name collision would otherwise happen, and " (copy 2)", etc., for
-    further conflicts.
-    """
-    import shutil
-
-    # Resolve target_id → (target_dir, target_folder)
-    sr_check = await db.execute(
-        select(SourceRoot).where(SourceRoot.id == body.target_id)
-    )
-    source_root = sr_check.scalar_one_or_none()
-
-    if source_root is not None:
-        target_dir = source_root.path
-        from app.tasks.scan import get_or_create_folder
-        target_folder = await get_or_create_folder(db, target_dir, source_root.id)
-    else:
-        folder_check = await db.execute(
-            select(Folder).where(Folder.id == body.target_id)
-        )
-        target_folder = folder_check.scalar_one_or_none()
-        if target_folder is None:
-            raise HTTPException(status_code=404, detail="Target folder not found")
-        target_dir = target_folder.path
-
-    if not os.path.isdir(target_dir):
-        raise HTTPException(
-            status_code=400,
-            detail=f"Target directory does not exist: {target_dir}",
-        )
-
-    if not body.photo_ids:
-        return {"status": "success", "copied": 0, "errors": []}
-
-    photos_result = await db.execute(
-        select(Photo).where(Photo.id.in_(body.photo_ids))
-    )
-    photos_to_copy = photos_result.scalars().all()
-
-    copied = 0
-    errors: list[dict] = []
-
-    def _unique_target_name(directory: str, filename: str) -> Optional[str]:
-        """Find a non-colliding filename in `directory` based on `filename`,
-        suffixing " (copy)", " (copy 2)", ... if needed. Gives up after 100
-        attempts."""
-        if not os.path.exists(os.path.join(directory, filename)):
-            return filename
-        stem, ext = os.path.splitext(filename)
-        for i in range(1, 100):
-            candidate = f"{stem} (copy{'' if i == 1 else f' {i}'}){ext}"
-            if not os.path.exists(os.path.join(directory, candidate)):
-                return candidate
-        return None
-
-    for photo in photos_to_copy:
-        if not os.path.exists(photo.filepath):
-            errors.append({"id": photo.id, "error": "source file missing"})
-            continue
-
-        new_name = _unique_target_name(target_dir, photo.filename)
-        if new_name is None:
-            errors.append({"id": photo.id, "error": "too many name collisions"})
-            continue
-
-        new_path = os.path.join(target_dir, new_name)
-
-        try:
-            shutil.copy2(photo.filepath, new_path)
-        except OSError as e:
-            errors.append({"id": photo.id, "error": str(e)})
-            continue
-
-        # Create a new Photo row pointing at the copy. Most metadata is
-        # copied verbatim; the file_hash stays so the duplicate flag does
-        # the right thing across the library.
-        new_photo = Photo(
-            filepath=new_path,
-            filename=new_name,
-            folder_id=target_folder.id,
-            file_hash=photo.file_hash,
-            media_type=photo.media_type,
-            original_format=photo.original_format,
-            width=photo.width,
-            height=photo.height,
-            file_size=photo.file_size,
-            taken_at=photo.taken_at,
-            taken_at_source=photo.taken_at_source,
-            user_title=photo.user_title,
-            user_notes=photo.user_notes,
-            rating=photo.rating,
-            color_label=photo.color_label,
-            exif_json=photo.exif_json,
-            is_duplicate=True,
-            processing_status='pending',
-        )
-        db.add(new_photo)
-        copied += 1
-
-    await db.commit()
-
-    return {
-        "status": "success",
-        "copied": copied,
-        "errors": errors,
-    }
-
-
-@router.post("/move")
-async def move_photos(
-    body: MoveRequest,
-    db: AsyncSession = Depends(get_db),
-):
-    """Move photos into a target folder. The target can be either a Folder
-    id or a SourceRoot id (since the LeftSidebar only exposes source roots
-    today). The handler resolves the target to an on-disk directory, calls
-    shutil.move for each photo, and updates photo.filepath + folder_id.
-
-    Per-file failures (target name collision, missing source) are collected
-    and returned in the response so a single bad photo doesn't abort the
-    batch.
-    """
-    import shutil
-
-    # Resolve target_id → (target_dir, target_folder)
-    sr_check = await db.execute(
-        select(SourceRoot).where(SourceRoot.id == body.target_id)
-    )
-    source_root = sr_check.scalar_one_or_none()
-
-    if source_root is not None:
-        target_dir = source_root.path
-        # We need a Folder row to point photo.folder_id at. Reuse the
-        # scanner's get_or_create helper so we don't duplicate the dedupe
-        # / normalization logic.
-        from app.tasks.scan import get_or_create_folder
-        target_folder = await get_or_create_folder(db, target_dir, source_root.id)
-    else:
-        folder_check = await db.execute(
-            select(Folder).where(Folder.id == body.target_id)
-        )
-        target_folder = folder_check.scalar_one_or_none()
-        if target_folder is None:
-            raise HTTPException(status_code=404, detail="Target folder not found")
-        target_dir = target_folder.path
-
-    if not os.path.isdir(target_dir):
-        raise HTTPException(
-            status_code=400,
-            detail=f"Target directory does not exist: {target_dir}",
-        )
-
-    if not body.photo_ids:
-        return {"status": "success", "moved": 0, "errors": []}
-
-    # Fetch the photo rows
-    photos_result = await db.execute(
-        select(Photo).where(Photo.id.in_(body.photo_ids))
-    )
-    photos_to_move = photos_result.scalars().all()
-
-    moved = 0
-    errors: list[dict] = []
-
-    for photo in photos_to_move:
-        # Skip if already in the target folder.
-        if photo.folder_id == target_folder.id:
-            continue
-
-        new_path = os.path.join(target_dir, photo.filename)
-
-        if not os.path.exists(photo.filepath):
-            errors.append({"id": photo.id, "error": "source file missing"})
-            continue
-        if os.path.exists(new_path):
-            errors.append({"id": photo.id, "error": f"name already exists in target: {photo.filename}"})
-            continue
-
-        try:
-            shutil.move(photo.filepath, new_path)
-        except OSError as e:
-            errors.append({"id": photo.id, "error": str(e)})
-            continue
-
-        photo.filepath = new_path
-        photo.folder_id = target_folder.id
-        moved += 1
-
-    await db.commit()
-
-    return {
-        "status": "success",
-        "moved": moved,
-        "errors": errors,
-    }
-
-
-@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,114 +0,0 @@
-"""
-Tags API router
-"""
-from typing import Optional
-from fastapi import APIRouter, Depends, HTTPException
-from pydantic import BaseModel
-from sqlalchemy import select, func, insert, delete
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.models import Tag
-from app.models.tags import photo_tags
-
-router = APIRouter()
-
-
-# ── Schemas ───────────────────────────────────────────────────────────────
-
-class TagCreate(BaseModel):
-    name: str
-    color: Optional[str] = None
-
-
-class TagUpdate(BaseModel):
-    name: Optional[str] = None
-    color: Optional[str] = None
-
-
-# ── Endpoints ─────────────────────────────────────────────────────────────
-
-@router.get("")
-async def list_tags(db: AsyncSession = Depends(get_db)):
-    """List all tags with their photo counts."""
-    count_subq = (
-        select(
-            photo_tags.c.tag_id,
-            func.count(photo_tags.c.photo_id).label("photo_count"),
-        )
-        .group_by(photo_tags.c.tag_id)
-        .subquery()
-    )
-    stmt = (
-        select(Tag, count_subq.c.photo_count)
-        .outerjoin(count_subq, Tag.id == count_subq.c.tag_id)
-        .order_by(Tag.name.asc())
-    )
-    result = await db.execute(stmt)
-    rows = result.all()
-
-    return [
-        {
-            "id": tag.id,
-            "name": tag.name,
-            "color": tag.color,
-            "photo_count": int(count or 0),
-        }
-        for tag, count in rows
-    ]
-
-
-@router.post("", status_code=201)
-async def create_tag(body: TagCreate, db: AsyncSession = Depends(get_db)):
-    """Create a new tag. Names are unique — re-creating an existing name
-    returns the existing row instead of erroring (idempotent for the
-    autocomplete UI flow)."""
-    name = (body.name or "").strip()
-    if not name:
-        raise HTTPException(status_code=400, detail="Tag name is required")
-
-    existing = await db.execute(select(Tag).where(Tag.name == name))
-    found = existing.scalar_one_or_none()
-    if found:
-        return {"id": found.id, "name": found.name, "color": found.color, "photo_count": 0}
-
-    tag = Tag(name=name, color=body.color)
-    db.add(tag)
-    await db.commit()
-    await db.refresh(tag)
-    return {"id": tag.id, "name": tag.name, "color": tag.color, "photo_count": 0}
-
-
-@router.patch("/{tag_id}")
-async def update_tag(
-    tag_id: str, body: TagUpdate, db: AsyncSession = Depends(get_db)
-):
-    """Rename or recolor a tag."""
-    result = await db.execute(select(Tag).where(Tag.id == tag_id))
-    tag = result.scalar_one_or_none()
-    if not tag:
-        raise HTTPException(status_code=404, detail="Tag not found")
-
-    if body.name is not None:
-        name = body.name.strip()
-        if not name:
-            raise HTTPException(status_code=400, detail="Tag name is required")
-        tag.name = name
-    if body.color is not None:
-        tag.color = body.color or None
-
-    await db.commit()
-    await db.refresh(tag)
-    return {"id": tag.id, "name": tag.name, "color": tag.color}
-
-
-@router.delete("/{tag_id}", status_code=204)
-async def delete_tag(tag_id: str, db: AsyncSession = Depends(get_db)):
-    """Delete a tag. Photo associations cascade-delete via the FK."""
-    result = await db.execute(select(Tag).where(Tag.id == tag_id))
-    tag = result.scalar_one_or_none()
-    if not tag:
-        raise HTTPException(status_code=404, detail="Tag not found")
-    await db.delete(tag)
-    await db.commit()
-    return None

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,163 +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 _warn_stale_source_roots(session: AsyncSession) -> int:
-    """Log a warning for any active source root whose path no longer exists
-    on disk. Doesn't delete — a missing path could be a temporarily
-    unmounted drive, and silently dropping user data is worse than
-    surfacing a noisy log line.
-    """
-    result = await session.execute(select(SourceRoot))
-    rows = result.scalars().all()
-    stale = 0
-    for sr in rows:
-        if not os.path.isdir(sr.path):
-            stale += 1
-            logger.warning(
-                f"Source root '{sr.name}' path is missing on disk: {sr.path} "
-                f"— is the docker mount still in place? "
-                f"(Edit docker-compose.yml or PHOTO_DIRS in .env to fix.)"
-            )
-    return stale
-
-
-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)
-            stale = await _warn_stale_source_roots(session)
-            await session.commit()
-            summary = {
-                "source_roots_merged": sr_deleted,
-                "folders_merged": f_deleted,
-                "source_roots_stale": stale,
-            }
-            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,65 +0,0 @@
-"""
-Scanner service for initial library scan and one-time bootstrap of the
-default source root on first boot.
-"""
-import os
-import logging
-from sqlalchemy import select
-
-from app.database import AsyncSessionLocal
-from app.models import SourceRoot
-from app.tasks.scan import scan_all_source_roots
-from app.config import settings
-
-logger = logging.getLogger(__name__)
-
-# The single host → container mount path. The compose file mounts whatever
-# the user set as PHOTO_DIRS at this path.
-DEFAULT_LIBRARY_PATH = "/photos"
-DEFAULT_LIBRARY_NAME = "Library"
-
-
-async def bootstrap_default_source_root() -> None:
-    """If no source roots exist in the DB, create one pointing at the default
-    library mount. Lets a fresh install pick up photos with zero
-    configuration: the user only needs to set PHOTO_DIRS in .env.
-    """
-    if not os.path.isdir(DEFAULT_LIBRARY_PATH):
-        logger.warning(
-            f"Default library path {DEFAULT_LIBRARY_PATH} is not mounted; "
-            "set PHOTO_DIRS in .env and recreate the container."
-        )
-        return
-
-    async with AsyncSessionLocal() as session:
-        result = await session.execute(select(SourceRoot))
-        if result.scalars().first() is not None:
-            return  # Already have at least one source root, leave it alone.
-
-        source_root = SourceRoot(
-            name=DEFAULT_LIBRARY_NAME,
-            path=DEFAULT_LIBRARY_PATH,
-        )
-        session.add(source_root)
-        await session.commit()
-        logger.info(
-            f"Bootstrapped default source root: {DEFAULT_LIBRARY_NAME} → "
-            f"{DEFAULT_LIBRARY_PATH}"
-        )
-
-
-async def start_initial_scan():
-    """Start the initial library scan.
-
-    NOTE: the folder watcher (watch_folders task) is intentionally NOT
-    dispatched here. It's an infinite loop celery task and every backend
-    restart was queuing a new instance, eventually pinning every worker
-    and starving scan_folder dispatches. Re-enabling it needs a Redis
-    lock or a dedicated long-running container — until then the user
-    triggers scans manually via "Scan all folders".
-    """
-    try:
-        scan_all_source_roots.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,439 +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
-import redis
-
-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__)
-
-
-# Redis keys read by GET /api/v1/library/scan/status. The frontend
-# ScanProgress widget polls that endpoint, so anything we want to surface
-# in the UI lives here.
-REDIS_KEY_ACTIVE = 'scan:active'
-REDIS_KEY_CURRENT_FOLDER = 'scan:current_folder'
-REDIS_KEY_PROCESSED = 'scan:processed_files'
-REDIS_KEY_TOTAL = 'scan:total_files'
-REDIS_KEY_ERRORS = 'scan:errors'
-MAX_ERROR_ENTRIES = 50  # cap the errors list so a noisy scan doesn't blow Redis
-
-
-def _get_redis():
-    """Connect to the broker for progress writes. Returns None on failure
-    so a Redis outage doesn't prevent the scan itself from running."""
-    try:
-        return redis.Redis.from_url(settings.celery_broker_url)
-    except Exception as e:
-        logger.warning(f"Could not reach Redis for scan progress: {e}")
-        return None
-
-# 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. Writes progress to Redis so
-    GET /api/v1/library/scan/status can surface it to the frontend
-    ScanProgress widget."""
-    logger.info(f"Starting scan of folder: {folder_path}")
-
-    r = _get_redis()
-
-    def progress_set(key: str, value) -> None:
-        if r is None:
-            return
-        try:
-            r.set(key, str(value))
-        except Exception as e:
-            logger.debug(f"scan progress set failed: {e}")
-
-    def progress_push_error(message: str) -> None:
-        if r is None:
-            return
-        try:
-            r.lpush(REDIS_KEY_ERRORS, message)
-            r.ltrim(REDIS_KEY_ERRORS, 0, MAX_ERROR_ENTRIES - 1)
-        except Exception as e:
-            logger.debug(f"scan progress push_error failed: {e}")
-
-    # Mark scan active immediately so the UI starts polling fast.
-    progress_set(REDIS_KEY_ACTIVE, 'true')
-    progress_set(REDIS_KEY_CURRENT_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
-
-            # Pre-walk to compute the total file count upfront. Without this
-            # the progress bar would jump every time a new subfolder is
-            # encountered because the running total kept growing.
-            total_files = 0
-            for _root, _dirs, files in os.walk(folder_path):
-                total_files += sum(
-                    1 for f in files if Path(f).suffix.lower() in SUPPORTED_EXTENSIONS
-                )
-            progress_set(REDIS_KEY_TOTAL, total_files)
-            progress_set(REDIS_KEY_PROCESSED, 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)
-                progress_set(REDIS_KEY_CURRENT_FOLDER, root)
-
-                # Filter supported files
-                supported_files = [f for f in files if Path(f).suffix.lower() in SUPPORTED_EXTENSIONS]
-
-                # 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]
-                    # Defer task dispatch until AFTER commit so workers don't
-                    # query for rows that aren't visible to other sessions yet.
-                    pending_dispatch: list[str] = []
-
-                    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
-                                progress_set(REDIS_KEY_PROCESSED, processed_files)
-                                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()  # Assign defaults / FK ids
-
-                            # Queue dispatch happens after the batch commit
-                            # below; otherwise the worker can race the writer
-                            # and see "Photo not found".
-                            pending_dispatch.append(photo.id)
-
-                            processed_files += 1
-                            progress_set(REDIS_KEY_PROCESSED, processed_files)
-
-                            # Celery internal progress (used by celery tooling)
-                            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)})
-                            progress_push_error(f"{filepath}: {e}")
-                            continue
-
-                    # Commit batch, then queue worker tasks. Dispatch order
-                    # matters: commit first so workers can find the rows.
-                    await session.commit()
-
-                    for photo_id in pending_dispatch:
-                        generate_thumbnails.delay(photo_id)
-                        extract_metadata.delay(photo_id)
-
-            # 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}")
-            progress_push_error(f"scan failed: {e}")
-            await session.rollback()
-            raise
-        finally:
-            # Always mark inactive on the way out so a crashed scan doesn't
-            # leave the UI thinking we're still scanning.
-            progress_set(REDIS_KEY_ACTIVE, 'false')
-
-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 every active source root currently registered in the DB."""
-    # Clear stale per-scan progress before queuing new work so the UI sees
-    # a clean slate even if a previous run crashed mid-flight.
-    r = _get_redis()
-    if r is not None:
-        try:
-            r.delete(REDIS_KEY_ERRORS)
-            r.set(REDIS_KEY_PROCESSED, 0)
-            r.set(REDIS_KEY_TOTAL, 0)
-        except Exception as e:
-            logger.debug(f"scan_all_source_roots redis reset failed: {e}")
-
-    return asyncio.run(_scan_all_source_roots_async())
-
-
-async def _scan_all_source_roots_async():
-    """Read every active SourceRoot from the DB and queue a scan_folder task
-    for each. Source roots whose path no longer exists on disk are skipped
-    with a warning (the cleanup service surfaces those at startup too)."""
-    async with AsyncSessionLocal() as session:
-        result = await session.execute(
-            select(SourceRoot).where(SourceRoot.is_active == True)  # noqa: E712
-        )
-        source_roots = result.scalars().all()
-        for sr in source_roots:
-            if os.path.exists(sr.path):
-                scan_folder.delay(sr.path, sr.id)
-            else:
-                logger.warning(f"Source root path does not exist: {sr.path}")
-
-
-@shared_task(name='watch_folders')
-def watch_folders():
-    """
-    Watch folders for changes using watchfiles. Long-running task that
-    monitors filesystem events under every active source root.
-    """
-    from watchfiles import watch
-
-    # Read source roots from the DB instead of the (now-removed) YAML
-    # config. We need both the path and the id so we can dispatch
-    # scan_folder with the source_root_id when an event fires.
-    roots: list[tuple[str, str]] = []
-    try:
-        async def _load_roots():
-            async with AsyncSessionLocal() as session:
-                result = await session.execute(
-                    select(SourceRoot).where(SourceRoot.is_active == True)  # noqa: E712
-                )
-                return [
-                    (os.path.normpath(sr.path), sr.id)
-                    for sr in result.scalars().all()
-                    if os.path.exists(sr.path)
-                ]
-        roots = asyncio.run(_load_roots())
-    except Exception as e:
-        logger.error(f"watch_folders could not load source roots: {e}")
-        return
-
-    if not roots:
-        logger.warning("No valid source roots to watch")
-        return
-
-    paths = [p for p, _ in roots]
-    logger.info(f"Starting folder watcher for: {paths}")
-
-    def find_source_root_for(path: str) -> Optional[str]:
-        """Return the source_root id whose path contains `path`, or None."""
-        normalized = os.path.normpath(path)
-        for root_path, root_id in roots:
-            if normalized == root_path or normalized.startswith(root_path + os.sep):
-                return root_id
-        return None
-
-    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, with the source_root_id
-                # resolved by ancestor lookup so scan_folder doesn't
-                # auto-create a new SourceRoot for an arbitrary subdir.
-                parent_dir = str(Path(filepath).parent)
-                source_root_id = find_source_root_for(parent_dir)
-                if source_root_id is None:
-                    logger.debug(
-                        f"watcher event for {filepath}: parent {parent_dir} "
-                        f"not under any active source root, ignoring"
-                    )
-                    continue
-                scan_folder.delay(parent_dir, source_root_id)
-                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,93 +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
-      # The single host → container mount for your photo library. Set
-      # PHOTO_DIRS in .env to your library root. Mounted :rw because file
-      # operations (rename, move, empty discard pile) need to mutate the
-      # filesystem; flip to :ro for a strict read-only library and the
-      # write endpoints will return EROFS.
-      - ${PHOTO_DIRS:-./photos}:/photos:rw
-      - thumbs_data:/data/thumbs
-      - proxies_data:/data/proxies
-      - db_data:/data/db
+    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
-      - thumbs_data:/data/thumbs
-      - proxies_data:/data/proxies
-      - db_data:/data/db
-    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", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      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:
-  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,94 +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 { 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 />
-      <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,52 +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: '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,184 +0,0 @@
-import { useEffect, useRef, useState } from 'react'
-import { FolderOpen, Loader2, Check, AlertCircle, X } from 'lucide-react'
-import { useQuery, useQueryClient } 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)
-  const queryClient = useQueryClient()
-  const wasScanningRef = useRef(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(() => {
-    const isScanning = scanStatus?.is_scanning ?? false
-
-    if (isScanning) {
-      setIsVisible(true)
-      setIsMinimized(false)
-      wasScanningRef.current = true
-    } else if (wasScanningRef.current) {
-      // Just transitioned from scanning → done. THIS is the right moment
-      // to invalidate caches that might have new data: the photos query
-      // (new files indexed), the folder tree (new folders walked), the
-      // heap counts (in case a heap photo got reattached).
-      wasScanningRef.current = false
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-      queryClient.invalidateQueries({ queryKey: ['folders', 'tree'] })
-      queryClient.invalidateQueries({ queryKey: ['heaps'] })
-      queryClient.invalidateQueries({ queryKey: ['tags'] })
-
-      if (isVisible && (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, queryClient])
-
-  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/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/FilterBar.tsx

@@ -1,340 +0,0 @@
-import { Star, X, ArrowDown, ArrowUp } from 'lucide-react'
-import clsx from 'clsx'
-import {
-  useFilterStore,
-  hasActiveFilters,
-  type MediaType,
-  type ColorLabel,
-  type SortField,
-} from '../../store/filterStore'
-import { useTagsQuery } from '../../hooks/useTagsQuery'
-import { FilterPill } from './FilterPill'
-
-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_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' },
-]
-
-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' },
-]
-
-/**
- * Compact, always-visible filter toolbar built out of FilterPill primitives.
- * Each pill represents a filter category, opens a popover with the
- * underlying control, and shows a short value summary inline when active.
- * Replaces the old expandable FilterBar + ActiveFilterChips combo.
- */
-export function FilterBar() {
-  const filterState = useFilterStore()
-  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 tagIds = useFilterStore((s) => s.tagIds)
-
-  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 setTagIds = useFilterStore((s) => s.setTagIds)
-  const toggleTagId = useFilterStore((s) => s.toggleTagId)
-  const setSortBy = useFilterStore((s) => s.setSortBy)
-  const toggleSortOrder = useFilterStore((s) => s.toggleSortOrder)
-  const clearAll = useFilterStore((s) => s.clearAll)
-
-  const { data: allTags = [] } = useTagsQuery()
-
-  // Pre-compute pill values + active flags so the JSX stays terse.
-  const dateActive = dateFrom !== null || dateTo !== null
-  const dateValue = dateActive
-    ? `${dateFrom ?? '…'} → ${dateTo ?? '…'}`
-    : null
-
-  const typeActive = mediaTypes.length > 0
-  const typeValue = typeActive
-    ? mediaTypes.map((t) => t.toUpperCase()).join(', ')
-    : null
-
-  const ratingActive = ratingMin > 0
-  const ratingValue = ratingActive ? `≥ ${ratingMin}★` : null
-
-  const colorActive = colorLabel !== null
-  const colorValue = colorActive ? colorLabel : null
-
-  const flagActive = flag !== 'any'
-  const flagValue = flagActive ? flag : null
-
-  const tagActive = tagIds.length > 0
-  const activeTagNames = allTags
-    .filter((t) => tagIds.includes(t.id))
-    .map((t) => t.name)
-  const tagValue = tagActive
-    ? activeTagNames.length <= 2
-      ? activeTagNames.join(', ')
-      : `${activeTagNames.slice(0, 2).join(', ')} +${activeTagNames.length - 2}`
-    : null
-
-  const sortLabel = SORT_OPTIONS.find((o) => o.value === sortBy)?.label ?? sortBy
-  const sortValue = `${sortLabel} ${sortOrder === 'desc' ? '↓' : '↑'}`
-
-  const anyActive = hasActiveFilters(filterState)
-
-  return (
-    <div className="flex items-center gap-1.5 overflow-x-auto border-b border-border bg-surface px-3 py-1.5">
-      {/* Date */}
-      <FilterPill
-        label="Date"
-        value={dateValue}
-        isActive={dateActive}
-        onClear={() => {
-          setDateFrom(null)
-          setDateTo(null)
-        }}
-      >
-        <div className="space-y-2">
-          <div>
-            <label className="mb-1 block text-[11px] text-text-muted">From</label>
-            <input
-              type="date"
-              value={dateFrom ?? ''}
-              onChange={(e) => setDateFrom(e.target.value || null)}
-              className="w-full rounded border border-border bg-bg px-2 py-1 text-xs text-text"
-            />
-          </div>
-          <div>
-            <label className="mb-1 block text-[11px] text-text-muted">To</label>
-            <input
-              type="date"
-              value={dateTo ?? ''}
-              onChange={(e) => setDateTo(e.target.value || null)}
-              className="w-full rounded border border-border bg-bg px-2 py-1 text-xs text-text"
-            />
-          </div>
-        </div>
-      </FilterPill>
-
-      {/* Type */}
-      <FilterPill
-        label="Type"
-        value={typeValue}
-        isActive={typeActive}
-        onClear={() => mediaTypes.forEach((t) => toggleMediaType(t))}
-      >
-        <div className="flex flex-wrap gap-1">
-          {MEDIA_TYPES.map(({ value, label }) => {
-            const active = mediaTypes.includes(value)
-            return (
-              <button
-                key={value}
-                onClick={() => toggleMediaType(value)}
-                className={clsx(
-                  'rounded px-2 py-1 text-xs transition-colors',
-                  active
-                    ? 'bg-primary text-white'
-                    : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-                )}
-              >
-                {label}
-              </button>
-            )
-          })}
-        </div>
-      </FilterPill>
-
-      {/* Rating */}
-      <FilterPill
-        label="Rating"
-        value={ratingValue}
-        isActive={ratingActive}
-        onClear={() => setRatingMin(0)}
-      >
-        <div>
-          <p className="mb-1 text-[11px] text-text-muted">Minimum</p>
-          <div className="flex gap-1">
-            {[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-5 w-5 transition-colors',
-                    n <= ratingMin
-                      ? 'fill-star text-star'
-                      : 'text-text-muted hover:text-star'
-                  )}
-                />
-              </button>
-            ))}
-          </div>
-        </div>
-      </FilterPill>
-
-      {/* Color */}
-      <FilterPill
-        label="Color"
-        value={colorValue}
-        isActive={colorActive}
-        onClear={() => setColorLabel(null)}
-      >
-        <div className="flex items-center gap-1.5">
-          {COLOR_LABEL_OPTIONS.map(({ value, className }) => {
-            const active = colorLabel === value
-            return (
-              <button
-                key={value}
-                onClick={() => setColorLabel(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={() => setColorLabel(null)}
-              className="ml-1 rounded p-0.5 text-text-muted hover:bg-surface-2 hover:text-text"
-              title="Clear color"
-            >
-              <X className="h-3 w-3" />
-            </button>
-          )}
-        </div>
-      </FilterPill>
-
-      {/* Flag — discarded toggle */}
-      <FilterPill
-        label="Flag"
-        value={flagValue}
-        isActive={flagActive}
-        onClear={() => setFlag('any')}
-      >
-        <div className="flex flex-col gap-1">
-          <button
-            onClick={() => setFlag('any')}
-            className={clsx(
-              'rounded px-2 py-1 text-left text-xs transition-colors',
-              flag === 'any'
-                ? 'bg-primary text-white'
-                : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-            )}
-          >
-            Any
-          </button>
-          <button
-            onClick={() => setFlag('discarded')}
-            className={clsx(
-              'rounded px-2 py-1 text-left text-xs transition-colors',
-              flag === 'discarded'
-                ? 'bg-primary text-white'
-                : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-            )}
-          >
-            Discarded
-          </button>
-        </div>
-      </FilterPill>
-
-      {/* Tags */}
-      {allTags.length > 0 && (
-        <FilterPill
-          label="Tags"
-          value={tagValue}
-          isActive={tagActive}
-          onClear={() => setTagIds([])}
-        >
-          <div className="flex max-h-60 flex-wrap gap-1 overflow-y-auto">
-            {allTags.map((tag) => {
-              const active = tagIds.includes(tag.id)
-              return (
-                <button
-                  key={tag.id}
-                  onClick={() => toggleTagId(tag.id)}
-                  className={clsx(
-                    'rounded px-2 py-1 text-xs transition-colors',
-                    active
-                      ? 'bg-primary text-white'
-                      : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-                  )}
-                >
-                  {tag.name}
-                </button>
-              )
-            })}
-          </div>
-        </FilterPill>
-      )}
-
-      {/* Sort — always present, never "active/inactive" since there's
-          always a value. */}
-      <FilterPill label="Sort" value={sortValue} isActive>
-        <div className="space-y-2">
-          <select
-            value={sortBy}
-            onChange={(e) => setSortBy(e.target.value as SortField)}
-            className="w-full 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="flex w-full items-center justify-center gap-1 rounded bg-surface-2 px-2 py-1 text-xs text-text-muted hover:bg-surface-offset hover:text-text"
-          >
-            {sortOrder === 'desc' ? (
-              <>
-                <ArrowDown className="h-3.5 w-3.5" />
-                Descending
-              </>
-            ) : (
-              <>
-                <ArrowUp className="h-3.5 w-3.5" />
-                Ascending
-              </>
-            )}
-          </button>
-        </div>
-      </FilterPill>
-
-      {anyActive && (
-        <button
-          onClick={clearAll}
-          className="ml-auto whitespace-nowrap rounded-full border border-border px-2.5 py-1 text-xs text-text-muted hover:bg-surface-2 hover:text-text"
-          title="Clear all filters in this section"
-        >
-          Clear all
-        </button>
-      )}
-    </div>
-  )
-}

frontend/src/components/filter/FilterPill.tsx

@@ -1,107 +0,0 @@
-import { useEffect, useRef, useState } from 'react'
-import { ChevronDown, X } from 'lucide-react'
-import clsx from 'clsx'
-
-interface FilterPillProps {
-  /** Category label, always shown ("Date", "Type", etc.). */
-  label: string
-  /** When the filter is active, a short summary of its current value
-   *  ("≥ 3★", "RAW + Photo", "Mar 2024 → Apr 2026"). Renders inside the
-   *  pill so the user sees the state without opening the popover. */
-  value?: string | null
-  isActive?: boolean
-  /** When provided + isActive, an X appears inside the pill that clears
-   *  this filter without opening the popover. */
-  onClear?: () => void
-  /** Popover contents — usually the existing control for this filter. */
-  children: React.ReactNode
-  /** Force the popover open programmatically (rare). */
-  defaultOpen?: boolean
-  /** Right-align the popover instead of left (for pills near the right
-   *  edge so they don't overflow the viewport). */
-  alignRight?: boolean
-}
-
-/**
- * A toolbar pill that hosts a filter category. Click the pill to open a
- * small popover with the actual control; the popover closes on outside
- * click or Escape. Active filters tint the pill primary and show their
- * current value inline.
- */
-export function FilterPill({
-  label,
-  value,
-  isActive = false,
-  onClear,
-  children,
-  defaultOpen = false,
-  alignRight = false,
-}: FilterPillProps) {
-  const [open, setOpen] = useState(defaultOpen)
-  const wrapperRef = useRef<HTMLDivElement>(null)
-
-  // Close on outside click + Escape.
-  useEffect(() => {
-    if (!open) return
-    const onDocMouseDown = (e: MouseEvent) => {
-      if (!wrapperRef.current) return
-      if (!wrapperRef.current.contains(e.target as Node)) {
-        setOpen(false)
-      }
-    }
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') setOpen(false)
-    }
-    document.addEventListener('mousedown', onDocMouseDown)
-    document.addEventListener('keydown', onKey)
-    return () => {
-      document.removeEventListener('mousedown', onDocMouseDown)
-      document.removeEventListener('keydown', onKey)
-    }
-  }, [open])
-
-  return (
-    <div ref={wrapperRef} className="relative">
-      <button
-        onClick={() => setOpen((v) => !v)}
-        className={clsx(
-          'flex items-center gap-1 rounded-full border px-2.5 py-1 text-xs transition-colors',
-          isActive
-            ? 'border-primary/40 bg-primary/15 text-primary'
-            : 'border-border bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-        )}
-      >
-        <span className={clsx(isActive && 'font-medium')}>{label}</span>
-        {isActive && value && (
-          <span className="font-mono text-[11px] opacity-90">{value}</span>
-        )}
-        {isActive && onClear ? (
-          <button
-            onClick={(e) => {
-              e.stopPropagation()
-              onClear()
-            }}
-            className="ml-0.5 rounded-full p-0.5 hover:bg-primary/30"
-            title={`Clear ${label}`}
-            aria-label={`Clear ${label}`}
-          >
-            <X className="h-3 w-3" />
-          </button>
-        ) : (
-          <ChevronDown className="h-3 w-3 opacity-60" />
-        )}
-      </button>
-
-      {open && (
-        <div
-          className={clsx(
-            'absolute top-full z-30 mt-1 min-w-[220px] rounded-lg border border-border bg-surface p-3 shadow-xl',
-            alignRight ? 'right-0' : 'left-0'
-          )}
-        >
-          {children}
-        </div>
-      )}
-    </div>
-  )
-}

frontend/src/components/heaps/HeapConvertDialog.tsx

@@ -1,221 +0,0 @@
-import { useState, useEffect } from 'react'
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-import { X, Folder, AlertCircle } from 'lucide-react'
-import clsx from 'clsx'
-import { sourceFolders, heaps as heapsApi, type Heap } from '../../services/api'
-import { HEAPS_QUERY_KEY } from '../../hooks/useHeapsQuery'
-import { toast } from '../ToastContainer'
-
-interface HeapConvertDialogProps {
-  heap: Heap | null
-  onClose: () => void
-}
-
-/**
- * Modal that converts a heap into a folder. The user picks a target folder
- * (any source root, today — sub-folder picking is a follow-up), chooses
- * move vs copy semantics, and optionally has the heap deleted on success.
- */
-export function HeapConvertDialog({ heap, onClose }: HeapConvertDialogProps) {
-  const queryClient = useQueryClient()
-  const [targetId, setTargetId] = useState('')
-  const [mode, setMode] = useState<'move' | 'copy'>('move')
-  const [deleteHeap, setDeleteHeap] = useState(false)
-  const [subfolderName, setSubfolderName] = useState('')
-
-  const { data: foldersData } = useQuery({
-    queryKey: ['folders'],
-    queryFn: sourceFolders.list,
-    enabled: !!heap,
-  })
-  const folders = foldersData?.folders ?? []
-
-  // Default to the first folder when the dialog opens or folders load.
-  useEffect(() => {
-    if (!targetId && folders.length > 0) {
-      setTargetId(folders[0].id)
-    }
-  }, [folders, targetId])
-
-  // Reset state on close, prefill subfolder name when opened.
-  useEffect(() => {
-    if (heap) {
-      setSubfolderName(heap.name)
-    } else {
-      setTargetId('')
-      setMode('move')
-      setDeleteHeap(false)
-      setSubfolderName('')
-    }
-  }, [heap])
-
-  const convertMutation = useMutation({
-    mutationFn: () =>
-      heapsApi.convert(heap!.id, {
-        target_id: targetId,
-        mode,
-        delete_heap: deleteHeap,
-        // Empty subfolder = drop directly into the parent. Trim and only
-        // send if the user kept it populated.
-        subfolder_name: subfolderName.trim() || null,
-      }),
-    onSuccess: (data) => {
-      const total = (data.moved ?? 0) + (data.copied ?? 0)
-      const verb = data.mode === 'move' ? 'Moved' : 'Copied'
-      toast.success(
-        `${verb} ${total} photo${total === 1 ? '' : 's'}`,
-        data.heap_deleted ? `Heap "${heap?.name}" deleted` : undefined
-      )
-      queryClient.invalidateQueries({ queryKey: HEAPS_QUERY_KEY })
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-      onClose()
-    },
-    onError: (e: any) =>
-      toast.error('Convert failed', e?.response?.data?.detail || e.message),
-  })
-
-  if (!heap) return null
-
-  const targetFolder = folders.find((f: any) => f.id === targetId)
-
-  return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center">
-      <div className="absolute inset-0 bg-black/60 backdrop-blur-sm" onClick={onClose} />
-
-      <div className="relative z-10 w-full max-w-md rounded-lg border border-border bg-surface p-6 shadow-xl">
-        <div className="mb-4 flex items-center justify-between">
-          <h2 className="text-lg font-semibold text-text">
-            Convert "{heap.name}" to folder
-          </h2>
-          <button
-            onClick={onClose}
-            disabled={convertMutation.isPending}
-            className="rounded p-1 text-text-muted hover:bg-surface-2 hover:text-text"
-          >
-            <X className="h-5 w-5" />
-          </button>
-        </div>
-
-        {/* Target picker */}
-        <div className="mb-4">
-          <label className="mb-1 block text-xs text-text-muted">Target folder</label>
-          {folders.length === 0 ? (
-            <div className="rounded border border-border bg-bg px-3 py-2 text-xs text-text-muted">
-              No folders available
-            </div>
-          ) : (
-            <select
-              value={targetId}
-              onChange={(e) => setTargetId(e.target.value)}
-              className="w-full rounded border border-border bg-bg px-2 py-1.5 text-sm text-text focus:border-primary focus:outline-none"
-            >
-              {folders.map((f: any) => (
-                <option key={f.id} value={f.id}>
-                  {f.name}
-                </option>
-              ))}
-            </select>
-          )}
-          {targetFolder && (
-            <p className="mt-1 flex items-center gap-1 text-xs text-text-faint">
-              <Folder className="h-3 w-3" />
-              {targetFolder.path}
-            </p>
-          )}
-        </div>
-
-        {/* Subfolder name */}
-        <div className="mb-4">
-          <label className="mb-1 block text-xs text-text-muted">
-            Subfolder name
-          </label>
-          <input
-            type="text"
-            value={subfolderName}
-            onChange={(e) => setSubfolderName(e.target.value)}
-            placeholder="(none — use parent directly)"
-            className="w-full rounded border border-border bg-bg px-2 py-1.5 text-sm text-text placeholder-text-faint focus:border-primary focus:outline-none"
-          />
-          <p className="mt-1 text-xs text-text-faint">
-            {subfolderName.trim() && targetFolder
-              ? `Will create ${targetFolder.path}/${subfolderName.trim()} if missing.`
-              : 'Photos go directly into the parent folder.'}
-          </p>
-        </div>
-
-        {/* Mode toggle */}
-        <div className="mb-4">
-          <label className="mb-1 block text-xs text-text-muted">Mode</label>
-          <div className="flex gap-2">
-            <button
-              onClick={() => setMode('move')}
-              className={clsx(
-                'flex-1 rounded px-3 py-1.5 text-sm transition-colors',
-                mode === 'move'
-                  ? 'bg-primary text-white'
-                  : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-              )}
-            >
-              Move
-            </button>
-            <button
-              onClick={() => setMode('copy')}
-              className={clsx(
-                'flex-1 rounded px-3 py-1.5 text-sm transition-colors',
-                mode === 'copy'
-                  ? 'bg-primary text-white'
-                  : 'bg-surface-2 text-text-muted hover:bg-surface-offset hover:text-text'
-              )}
-            >
-              Copy
-            </button>
-          </div>
-          <p className="mt-1 text-xs text-text-faint">
-            {mode === 'move'
-              ? 'Files are moved on disk; original photos update their folder.'
-              : 'Files are copied on disk; new photo records are created.'}
-          </p>
-        </div>
-
-        {/* Delete heap toggle */}
-        <div className="mb-4 flex items-center gap-2">
-          <input
-            id="delete-heap"
-            type="checkbox"
-            checked={deleteHeap}
-            onChange={(e) => setDeleteHeap(e.target.checked)}
-            className="h-4 w-4 rounded border-border bg-bg text-primary focus:ring-2 focus:ring-primary focus:ring-offset-0"
-          />
-          <label htmlFor="delete-heap" className="text-sm text-text">
-            Delete heap after conversion
-          </label>
-        </div>
-
-        {convertMutation.isError && (
-          <div className="mb-3 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>{(convertMutation.error as any)?.message || 'Conversion failed'}</span>
-          </div>
-        )}
-
-        <div className="flex justify-end gap-2">
-          <button
-            onClick={onClose}
-            disabled={convertMutation.isPending}
-            className="rounded bg-surface-2 px-4 py-2 text-sm text-text hover:bg-surface-offset disabled:opacity-50"
-          >
-            Cancel
-          </button>
-          <button
-            onClick={() => convertMutation.mutate()}
-            disabled={!targetId || convertMutation.isPending}
-            className="rounded bg-primary px-4 py-2 text-sm font-medium text-white hover:bg-primary/90 disabled:opacity-50"
-          >
-            {convertMutation.isPending ? 'Converting…' : 'Convert'}
-          </button>
-        </div>
-      </div>
-    </div>
-  )
-}

frontend/src/components/heaps/HeapsPanel.tsx

@@ -1,321 +0,0 @@
-import { useState } from 'react'
-import {
-  ShoppingBasket,
-  Plus,
-  Target,
-  X,
-  ChevronDown,
-  ChevronRight,
-  FolderOutput,
-} 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, type Heap } from '../../services/api'
-import { useFilterStore } from '../../store/filterStore'
-import { toast } from '../ToastContainer'
-import { PHOTO_DRAG_MIME } from '../timeline/PhotoThumbnail'
-import { HeapConvertDialog } from './HeapConvertDialog'
-
-/**
- * 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 navigateToSection = useFilterStore((s) => s.navigateToSection)
-  const currentSection = useFilterStore((s) => s.currentSection)
-  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 [convertingHeap, setConvertingHeap] = useState<Heap | 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 viewing this heap, snap back to all-photos.
-      if (currentSection === `heap-${heapId}`) {
-        navigateToSection('all-photos', {})
-      }
-    },
-    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 = currentSection === `heap-${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={() =>
-                  navigateToSection(`heap-${heap.id}`, { heapId: 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()
-                    setConvertingHeap(heap)
-                  }}
-                  className="invisible rounded p-0.5 text-text-muted hover:bg-surface-offset hover:text-text group-hover:visible"
-                  title="Convert to folder…"
-                >
-                  <FolderOutput 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>
-      )}
-
-      <HeapConvertDialog
-        heap={convertingHeap}
-        onClose={() => setConvertingHeap(null)}
-      />
-    </div>
-  )
-}

frontend/src/components/layout/LeftSidebar.tsx

@@ -1,427 +0,0 @@
-import { useState } from 'react'
-import {
-  ChevronRight,
-  ChevronDown,
-  Folder,
-  Image,
-  Star,
-  Trash2,
-  HardDrive,
-  RefreshCw,
-  Copy,
-  Tag as TagIcon,
-  Layers2,
-} from 'lucide-react'
-import clsx from 'clsx'
-import { sourceFolders, library, photos as photosApi, type FolderTreeNode } from '../../services/api'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { toast } from '../ToastContainer'
-import { useFilterStore } from '../../store/filterStore'
-import { HeapsPanel } from '../heaps/HeapsPanel'
-import { PHOTO_DRAG_MIME } from '../timeline/PhotoThumbnail'
-import { useFolderTreeQuery } from '../../hooks/useFolderTreeQuery'
-import { useTagsQuery } from '../../hooks/useTagsQuery'
-
-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 [isScanning, setIsScanning] = useState(false)
-  // Inline rename state for source-root rows. Stores the id being edited
-  // and the draft name. Double-click a folder row to start.
-  const [renamingId, setRenamingId] = useState<string | null>(null)
-  const [renameDraft, setRenameDraft] = useState('')
-
-  const queryClient = useQueryClient()
-  const navigateToSection = useFilterStore((s) => s.navigateToSection)
-  const currentSection = useFilterStore((s) => s.currentSection)
-  const { data: allTags = [] } = useTagsQuery()
-  const [dropTargetId, setDropTargetId] = useState<string | null>(null)
-
-  // Bulk discard mutation for the drag-onto-Discarded interaction.
-  const discardDropMutation = useMutation({
-    mutationFn: (photoIds: string[]) => photosApi.bulkDiscard(photoIds),
-    onSuccess: (_data, photoIds) => {
-      toast.success(
-        'Discarded',
-        `${photoIds.length} photo${photoIds.length > 1 ? 's' : ''}`
-      )
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-    },
-    onError: (e: any) =>
-      toast.error('Discard failed', e?.message || 'Unknown error'),
-  })
-
-  // Bulk move mutation for the drag-onto-folder interaction.
-  const moveDropMutation = useMutation({
-    mutationFn: ({ targetId, photoIds }: { targetId: string; photoIds: string[] }) =>
-      photosApi.move(photoIds, targetId),
-    onSuccess: (data) => {
-      const moved = data?.moved ?? 0
-      const errCount = (data?.errors?.length ?? 0)
-      if (moved > 0) {
-        toast.success(
-          'Moved',
-          `${moved} photo${moved > 1 ? 's' : ''}${errCount ? ` (${errCount} skipped)` : ''}`
-        )
-      } else if (errCount > 0) {
-        toast.error('Move failed', `${errCount} file${errCount > 1 ? 's' : ''} could not be moved`)
-      }
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-    },
-    onError: (e: any) =>
-      toast.error('Move failed', e?.response?.data?.detail || e.message || 'Unknown error'),
-  })
-
-  // Bulk copy mutation — Alt-drag uses this instead of move.
-  const copyDropMutation = useMutation({
-    mutationFn: ({ targetId, photoIds }: { targetId: string; photoIds: string[] }) =>
-      photosApi.copy(photoIds, targetId),
-    onSuccess: (data) => {
-      const copied = data?.copied ?? 0
-      const errCount = data?.errors?.length ?? 0
-      if (copied > 0) {
-        toast.success(
-          'Copied',
-          `${copied} photo${copied > 1 ? 's' : ''}${errCount ? ` (${errCount} skipped)` : ''}`
-        )
-      } else if (errCount > 0) {
-        toast.error('Copy failed', `${errCount} file${errCount > 1 ? 's' : ''} could not be copied`)
-      }
-      queryClient.invalidateQueries({ queryKey: ['photos'] })
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-    },
-    onError: (e: any) =>
-      toast.error('Copy failed', e?.response?.data?.detail || e.message || 'Unknown error'),
-  })
-
-  // Reads the dragged ids out of a drop event payload.
-  const readDragIds = (e: React.DragEvent): string[] | null => {
-    const raw = e.dataTransfer.getData(PHOTO_DRAG_MIME)
-    if (!raw) return null
-    try {
-      const parsed = JSON.parse(raw) as string[]
-      return Array.isArray(parsed) && parsed.length > 0 ? parsed : null
-    } catch {
-      return null
-    }
-  }
-
-  // Map a library tree id to a section navigation. Each "virtual node" in
-  // the library tree is its own section, with its own remembered filter
-  // state. The preset is the section's intrinsic filter (the thing that
-  // makes it that section); user-added filters from the FilterBar layer
-  // on top and are saved when the user navigates away.
-  const applyLibraryNode = (id: string) => {
-    switch (id) {
-      case 'all-photos':
-        navigateToSection('all-photos', {})
-        break
-      case 'rated':
-        navigateToSection('rated', { ratingMin: 1 })
-        break
-      case 'discarded':
-        navigateToSection('discarded', { flag: 'discarded' })
-        break
-      case 'duplicates':
-        navigateToSection('duplicates', { duplicates: true })
-        break
-      case 'tags':
-        navigateToSection('tags', { groupBy: 'tag' })
-        break
-      default:
-        if (id.startsWith('folder-')) {
-          const folderId = id.slice('folder-'.length)
-          navigateToSection(`folder-${folderId}`, { folderId })
-        }
-    }
-  }
-
-  // Fetch the recursive folder tree (one root per active source root).
-  const { data: folderTree = [] } = useFolderTreeQuery()
-
-  const renameMutation = useMutation({
-    mutationFn: ({ id, name }: { id: string; name: string }) =>
-      sourceFolders.rename(id, name),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['folders'] })
-      queryClient.invalidateQueries({ queryKey: ['folders', 'tree'] })
-    },
-    onError: (e: any) =>
-      toast.error('Rename failed', e?.response?.data?.detail || e.message || 'Unknown error'),
-  })
-
-  // 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 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)
-  }
-
-  // Recursively map a backend FolderTreeNode into our generic TreeItem.
-  const folderNodeToTreeItem = (node: FolderTreeNode): TreeItem => ({
-    id: `folder-${node.id}`,
-    label: node.name,
-    icon: <Folder className="h-4 w-4" />,
-    count: node.photo_count,
-    type: 'folder',
-    children: node.children.length > 0
-      ? node.children.map(folderNodeToTreeItem)
-      : undefined,
-  })
-
-  // Total tag count for the badge on the Tags entry.
-  const tagsTotalCount = allTags.reduce((sum, t) => sum + (t.photo_count || 0), 0)
-
-  const libraryTree: TreeItem[] = [
-    {
-      id: 'library',
-      label: 'Views',
-      icon: <Layers2 className="h-4 w-4" />,
-      children: [
-        { id: 'all-photos', label: 'All Photos', icon: <Image className="h-4 w-4" />, count: 0 },
-        { id: 'rated', label: 'Rated', icon: <Star className="h-4 w-4" />, count: 0 },
-        { id: 'tags', label: 'Tags', icon: <TagIcon className="h-4 w-4" />, count: tagsTotalCount },
-        { id: 'duplicates', label: 'Duplicates', icon: <Copy 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: <HardDrive className="h-4 w-4" />,
-      children: folderTree.map(folderNodeToTreeItem),
-    },
-  ]
-
-  // 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.
-  // Active highlight is now driven entirely by currentSection. Each
-  // library node and folder row maps 1:1 to a section id.
-  const isItemActive = (id: string): boolean => {
-    if (id.startsWith('folder-')) {
-      return currentSection === id
-    }
-    return currentSection === id
-  }
-
-  // Which tree items accept photo drops, and what each does on drop.
-  const isDropTarget = (id: string): boolean => {
-    return id === 'discarded' || id.startsWith('folder-')
-  }
-
-  const handleDrop = (id: string, ids: string[], copy: boolean) => {
-    if (id === 'discarded') {
-      discardDropMutation.mutate(ids)
-      return
-    }
-    if (id.startsWith('folder-')) {
-      const targetId = id.slice('folder-'.length)
-      if (copy) {
-        copyDropMutation.mutate({ targetId, photoIds: ids })
-      } else {
-        moveDropMutation.mutate({ targetId, photoIds: ids })
-      }
-    }
-  }
-
-  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)
-    const acceptsDrop = isDropTarget(item.id)
-    const isDropHover = dropTargetId === 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',
-            isDropHover && (item.id === 'discarded'
-              ? 'ring-2 ring-reject bg-reject/10'
-              : 'ring-2 ring-primary bg-primary/10'),
-            depth > 0 && 'text-[13px]'
-          )}
-          style={{ paddingLeft: `${8 + depth * 16}px` }}
-          onClick={() => {
-            if (renamingId === item.id) return
-            // Folder rows are always filterable, parent or leaf — clicking
-            // anywhere on the row applies the filter and the chevron
-            // (separate button below) handles expansion. Other group
-            // headers (Library, Folders) just toggle expansion since
-            // they have no associated section.
-            if (item.id.startsWith('folder-')) {
-              applyLibraryNode(item.id)
-            } else if (hasChildren) {
-              toggleExpanded(item.id)
-            } else {
-              applyLibraryNode(item.id)
-            }
-          }}
-          onDoubleClick={
-            item.id.startsWith('folder-')
-              ? (e) => {
-                e.stopPropagation()
-                setRenamingId(item.id)
-                setRenameDraft(item.label)
-              }
-              : undefined
-          }
-          onDragOver={acceptsDrop ? (e) => {
-            if (e.dataTransfer.types.includes(PHOTO_DRAG_MIME)) {
-              e.preventDefault()
-              // Alt held → copy (only meaningful for folder targets;
-              // discarding doesn't copy).
-              const wantCopy = e.altKey && item.id.startsWith('folder-')
-              e.dataTransfer.dropEffect = wantCopy ? 'copy' : 'move'
-              if (dropTargetId !== item.id) setDropTargetId(item.id)
-            }
-          } : undefined}
-          onDragLeave={acceptsDrop ? (e) => {
-            if (!e.currentTarget.contains(e.relatedTarget as Node)) {
-              if (dropTargetId === item.id) setDropTargetId(null)
-            }
-          } : undefined}
-          onDrop={acceptsDrop ? (e) => {
-            e.preventDefault()
-            setDropTargetId(null)
-            const ids = readDragIds(e)
-            if (ids) handleDrop(item.id, ids, e.altKey)
-          } : undefined}
-        >
-          {/* 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 (or inline rename input for folder rows) */}
-          {renamingId === item.id ? (
-            <input
-              autoFocus
-              type="text"
-              value={renameDraft}
-              onChange={(e) => setRenameDraft(e.target.value)}
-              onClick={(e) => e.stopPropagation()}
-              onBlur={() => {
-                const next = renameDraft.trim()
-                const id = item.id.slice('folder-'.length)
-                if (next && next !== item.label) {
-                  renameMutation.mutate({ id, name: next })
-                }
-                setRenamingId(null)
-              }}
-              onKeyDown={(e) => {
-                if (e.key === 'Enter') {
-                  e.currentTarget.blur()
-                } else if (e.key === 'Escape') {
-                  setRenamingId(null)
-                }
-              }}
-              className="flex-1 rounded border border-border bg-bg px-1 py-0 text-[13px] text-text focus:border-primary focus:outline-none"
-            />
-          ) : (
-            <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>
-          )}
-
-        </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">
-      {/* Tree View */}
-      <div className="flex-1 overflow-y-auto py-2">
-        {libraryTree.map((item) => renderTreeItem(item))}
-        <HeapsPanel />
-      </div>
-
-      {/* Bottom Actions */}
-      {folderTree.length > 0 && (
-        <div className="border-t border-border p-3">
-          <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>
-      )}
-    </div>
-  )
-}

frontend/src/components/layout/RightSidebar.tsx

@@ -1,837 +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 { useTagsQuery, TAGS_QUERY_KEY } from '../../hooks/useTagsQuery'
-import { tags as tagsApi, type Tag } from '../../services/api'
-import { toast } from '../ToastContainer'
-
-interface PhotoTagSummary {
-  id: string
-  name: string
-  color: string | null
-}
-
-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
-  tags?: PhotoTagSummary[]
-}
-
-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', 'tags'])
-  )
-
-  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'] })
-    },
-  })
-
-  // Bulk equivalents — used when more than one photo is selected so the
-  // rating / color / discard buttons apply to the whole selection.
-  const invalidatePhotoQueries = () => {
-    queryClient.invalidateQueries({ queryKey: ['photo'] })
-    queryClient.invalidateQueries({ queryKey: ['photos'] })
-  }
-  const bulkRatingMutation = useMutation({
-    mutationFn: ({ ids, rating }: { ids: string[]; rating: number }) =>
-      photosApi.bulkSetRating(ids, rating),
-    onSuccess: invalidatePhotoQueries,
-  })
-  const bulkColorMutation = useMutation({
-    mutationFn: ({ ids, color }: { ids: string[]; color: string | null }) =>
-      photosApi.bulkSetColor(ids, color),
-    onSuccess: invalidatePhotoQueries,
-  })
-  const bulkDiscardMutation = useMutation({
-    mutationFn: (ids: string[]) => photosApi.bulkDiscard(ids),
-    onSuccess: invalidatePhotoQueries,
-  })
-  const bulkRestoreMutation = useMutation({
-    mutationFn: (ids: string[]) => photosApi.bulkRestore(ids),
-    onSuccess: invalidatePhotoQueries,
-  })
-
-  // 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: ({ ids, remove }: { ids: string[]; remove: boolean }) => {
-      if (!activeHeap || ids.length === 0) return Promise.resolve(null)
-      return remove
-        ? heapsApi.removePhotos(activeHeap.id, ids)
-        : heapsApi.addPhotos(activeHeap.id, ids)
-    },
-    // Optimistic flip so the badge / button label update instantly.
-    onMutate: ({ ids, remove }) => {
-      if (!activeHeap || ids.length === 0) 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) ids.forEach((id) => set.delete(id))
-      else ids.forEach((id) => set.add(id))
-      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],
-        })
-      }
-    },
-  })
-
-  // ── Tags state + mutations ──────────────────────────────────────────
-  const { data: allTags = [] } = useTagsQuery()
-  const [tagInput, setTagInput] = useState('')
-
-  const invalidateTagsAndPhoto = () => {
-    queryClient.invalidateQueries({ queryKey: TAGS_QUERY_KEY })
-    queryClient.invalidateQueries({ queryKey: ['photo', activePhotoId] })
-    queryClient.invalidateQueries({ queryKey: ['photos'] })
-  }
-
-  const addTagMutation = useMutation({
-    mutationFn: async (name: string) => {
-      // Idempotent create — backend returns existing row if name matches.
-      const created = await tagsApi.create(name)
-      if (activePhotoId) {
-        await tagsApi.addToPhoto(activePhotoId, [created.id])
-      }
-      return created
-    },
-    onSuccess: () => invalidateTagsAndPhoto(),
-    onError: (e: any) =>
-      toast.error('Add tag failed', e?.message || 'Unknown error'),
-  })
-
-  const attachExistingTagMutation = useMutation({
-    mutationFn: (tagId: string) =>
-      tagsApi.addToPhoto(activePhotoId!, [tagId]),
-    onSuccess: () => invalidateTagsAndPhoto(),
-    onError: (e: any) =>
-      toast.error('Add tag failed', e?.message || 'Unknown error'),
-  })
-
-  const removeTagMutation = useMutation({
-    mutationFn: (tagId: string) =>
-      tagsApi.removeFromPhoto(activePhotoId!, tagId),
-    onSuccess: () => invalidateTagsAndPhoto(),
-    onError: (e: any) =>
-      toast.error('Remove tag failed', e?.message || 'Unknown error'),
-  })
-
-  // 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 })
-  }
-
-  // Apply a rating / color / discard to the current selection. Falls back
-  // to the single-photo path when only one photo is selected so the
-  // RightSidebar matches the keyboard shortcut behaviour exactly.
-  const applyRating = (value: number) => {
-    if (selectedPhotos.length > 1) {
-      bulkRatingMutation.mutate({ ids: selectedPhotos, rating: value })
-    } else {
-      updateMutation.mutate({ rating: value })
-    }
-  }
-  const setColor = (label: ColorLabel | null) => {
-    if (selectedPhotos.length > 1) {
-      bulkColorMutation.mutate({ ids: selectedPhotos, color: label })
-    } else {
-      updateMutation.mutate({ color_label: label })
-    }
-  }
-  const applyDiscard = (next: boolean) => {
-    if (selectedPhotos.length > 1) {
-      if (next) bulkDiscardMutation.mutate(selectedPhotos)
-      else bulkRestoreMutation.mutate(selectedPhotos)
-    } else {
-      updateMutation.mutate({ is_discarded: next })
-    }
-  }
-
-  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 */}
-      {photo && (
-        <div className="space-y-3 border-b border-border p-4">
-          {multipleSelected && (
-            <p className="text-xs text-text-muted">
-              Rating, color, and flag apply to all {selectedPhotos.length} selected.
-            </p>
-          )}
-
-          {/* Per-photo fields — only meaningful for a single selection */}
-          {!multipleSelected && (
-            <>
-              <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>
-
-              <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>
-
-              <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={() => applyRating(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={() => {
-                  const ids = selectedPhotos.length > 0
-                    ? selectedPhotos
-                    : activePhotoId ? [activePhotoId] : []
-                  if (!activeHeap || ids.length === 0) return
-                  // If every selected photo is already a member, remove
-                  // them; otherwise add the missing ones. Mirrors the
-                  // P keyboard shortcut behaviour exactly.
-                  const allMembers = ids.every((id) => activeHeapMembers.has(id))
-                  heapMutation.mutate({ ids, remove: allMembers })
-                }}
-                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={() => applyDiscard(!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>
-
-            {/* Tags */}
-            <Section
-              title="Tags"
-              expanded={expandedSections.has('tags')}
-              onToggle={() => toggleSection('tags')}
-            >
-              <TagsEditor
-                photoTags={photo.tags ?? []}
-                allTags={allTags}
-                tagInput={tagInput}
-                onTagInputChange={setTagInput}
-                onAttachExisting={(id) => attachExistingTagMutation.mutate(id)}
-                onCreateAndAttach={(name) => {
-                  addTagMutation.mutate(name)
-                  setTagInput('')
-                }}
-                onRemove={(id) => removeTagMutation.mutate(id)}
-              />
-            </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>
-  )
-}
-
-interface TagsEditorProps {
-  photoTags: PhotoTagSummary[]
-  allTags: Tag[]
-  tagInput: string
-  onTagInputChange: (value: string) => void
-  onAttachExisting: (id: string) => void
-  onCreateAndAttach: (name: string) => void
-  onRemove: (id: string) => void
-}
-
-function TagsEditor({
-  photoTags,
-  allTags,
-  tagInput,
-  onTagInputChange,
-  onAttachExisting,
-  onCreateAndAttach,
-  onRemove,
-}: TagsEditorProps) {
-  const trimmed = tagInput.trim()
-  const lowerTrimmed = trimmed.toLowerCase()
-  const photoTagIds = new Set(photoTags.map((t) => t.id))
-
-  // Suggestions: tags whose name contains the input AND that aren't
-  // already on the photo. Capped at 6 to keep the dropdown short.
-  const suggestions = trimmed
-    ? allTags
-        .filter(
-          (t) =>
-            !photoTagIds.has(t.id) &&
-            t.name.toLowerCase().includes(lowerTrimmed)
-        )
-        .slice(0, 6)
-    : []
-
-  const exactMatch = trimmed
-    ? allTags.find((t) => t.name.toLowerCase() === lowerTrimmed)
-    : null
-
-  const handleSubmit = () => {
-    if (!trimmed) return
-    if (exactMatch) {
-      if (!photoTagIds.has(exactMatch.id)) {
-        onAttachExisting(exactMatch.id)
-      }
-      onTagInputChange('')
-    } else {
-      onCreateAndAttach(trimmed)
-    }
-  }
-
-  return (
-    <div className="space-y-2">
-      {/* Existing tag chips */}
-      {photoTags.length > 0 ? (
-        <div className="flex flex-wrap gap-1">
-          {photoTags.map((tag) => (
-            <span
-              key={tag.id}
-              className="flex items-center gap-1 rounded bg-surface-2 px-2 py-0.5 text-xs text-text"
-              style={tag.color ? { backgroundColor: `${tag.color}33`, color: tag.color } : undefined}
-            >
-              {tag.name}
-              <button
-                onClick={() => onRemove(tag.id)}
-                className="rounded p-0.5 opacity-60 hover:bg-surface-offset hover:opacity-100"
-                title="Remove tag"
-              >
-                <X className="h-3 w-3" />
-              </button>
-            </span>
-          ))}
-        </div>
-      ) : (
-        <div className="text-xs text-text-faint">No tags</div>
-      )}
-
-      {/* Add tag input + suggestions */}
-      <div className="relative">
-        <input
-          type="text"
-          value={tagInput}
-          onChange={(e) => onTagInputChange(e.target.value)}
-          onKeyDown={(e) => {
-            if (e.key === 'Enter') {
-              e.preventDefault()
-              handleSubmit()
-            } else if (e.key === 'Escape') {
-              onTagInputChange('')
-            }
-          }}
-          placeholder="Add tag…"
-          className="w-full rounded border border-border bg-bg px-2 py-1 text-xs text-text placeholder-text-faint focus:border-primary focus:outline-none"
-        />
-        {suggestions.length > 0 && (
-          <div className="mt-1 rounded border border-border bg-bg shadow-md">
-            {suggestions.map((s) => (
-              <button
-                key={s.id}
-                onClick={() => {
-                  onAttachExisting(s.id)
-                  onTagInputChange('')
-                }}
-                className="block w-full px-2 py-1 text-left text-xs text-text hover:bg-surface-2"
-              >
-                {s.name}
-              </button>
-            ))}
-          </div>
-        )}
-        {trimmed && !exactMatch && (
-          <button
-            onClick={handleSubmit}
-            className="mt-1 w-full rounded border border-dashed border-primary/50 px-2 py-1 text-left text-xs text-primary hover:bg-primary/10"
-          >
-            + Create "{trimmed}"
-          </button>
-        )}
-      </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,98 +0,0 @@
-import { useState, useEffect, useRef } from 'react'
-import { Search, X, ShoppingBasket } from 'lucide-react'
-import { useFilterStore } 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 [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])
-
-  // 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 — logo + active heap pill */}
-      <div className="flex items-center gap-3">
-        <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 — 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 — reserved for future actions */}
-      <div className="flex items-center gap-2" />
-    </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,232 +0,0 @@
-import { useState, useEffect, useCallback, useRef } from 'react'
-import { Star, ShoppingBasket, Trash2, RefreshCw, Check, Copy } 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_duplicate && (
-          <div
-            className="flex h-5 w-5 items-center justify-center rounded-full bg-black/60 text-white shadow-md"
-            title="Duplicate (matches another photo's hash)"
-          >
-            <Copy 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,512 +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 the flat header|row item array the virtualizer renders.
- *
- * Three modes:
- *  - groupBy='tag': one bucket per unique tag (plus an "Untagged" bucket
- *    for photos with no tags). A photo with N tags appears in N buckets.
- *  - groupBy='date' AND sortBy is a date field: month buckets (existing).
- *  - otherwise: one un-headered stream.
- */
-function buildItems(
-  photos: Photo[],
-  columns: number,
-  sortBy: string,
-  groupBy: 'date' | 'tag'
-): TimelineItem[] {
-  if (photos.length === 0) return []
-
-  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,
-      })
-    }
-  }
-
-  // ── Tag grouping ──────────────────────────────────────────────────────
-  if (groupBy === 'tag') {
-    // Bucket by tag name. A photo with multiple tags lands in multiple
-    // buckets. Photos with no tags go into "Untagged".
-    const tagBuckets = new Map<string, PhotoCell[]>()
-    const untagged: PhotoCell[] = []
-
-    photos.forEach((photo, globalIndex) => {
-      const cell: PhotoCell = { photo, globalIndex }
-      const tags = photo.tags ?? []
-      if (tags.length === 0) {
-        untagged.push(cell)
-      } else {
-        for (const t of tags) {
-          const arr = tagBuckets.get(t.name) ?? []
-          arr.push(cell)
-          tagBuckets.set(t.name, arr)
-        }
-      }
-    })
-
-    // Sort tag groups alphabetically; Untagged goes at the end.
-    const sortedTagNames = Array.from(tagBuckets.keys()).sort((a, b) =>
-      a.localeCompare(b)
-    )
-
-    let bucketIndex = 0
-    for (const name of sortedTagNames) {
-      items.push({
-        type: 'header',
-        key: `tag::${bucketIndex}::${name}`,
-        label: name,
-        height: HEADER_HEIGHT,
-      })
-      pushRowsForGroup(`tag::${bucketIndex}::${name}`, tagBuckets.get(name)!)
-      bucketIndex++
-    }
-    if (untagged.length > 0) {
-      items.push({
-        type: 'header',
-        key: `tag::${bucketIndex}::__untagged`,
-        label: 'Untagged',
-        height: HEADER_HEIGHT,
-      })
-      pushRowsForGroup(`tag::${bucketIndex}::untagged`, untagged)
-    }
-    return items
-  }
-
-  // ── Date grouping (existing) ──────────────────────────────────────────
-  const isDateSort = sortBy === 'taken_at' || sortBy === 'added_at'
-
-  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,
-    activePhotoId,
-    lastSelectedIndex,
-    rangeStartIndex,
-    selectPhoto,
-    togglePhotoSelection,
-    clearSelection,
-    openPreview,
-  } = usePhotoStore()
-
-  const sortBy = useFilterStore((s) => s.sortBy)
-  const groupBy = useFilterStore((s) => s.groupBy)
-
-  // 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 group headers and rows of
-  // photos. Date headers appear when sorted by a date field; tag headers
-  // appear when groupBy === 'tag' (overrides date grouping).
-  const items = useMemo(
-    () => buildItems(photos, columns, sortBy, groupBy),
-    [photos, columns, sortBy, groupBy]
-  )
-
-  // 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)
-  }, [])
-
-  // Photo rows in visual order — drops the header items so navigation
-  // walks the grid as the user sees it. Each row has cells of length
-  // [1..columns], the last row of a group can be short, and a single
-  // photo with multiple tags will appear in multiple rows.
-  const photoRows = useMemo(
-    () => items.filter((it): it is Extract<TimelineItem, { type: 'row' }> => it.type === 'row'),
-    [items]
-  )
-
-  // Locate the active photo in the visual grid. Returns the FIRST
-  // (rowIndex, colIndex) where its id appears, since a tag-grouped view
-  // can repeat a photo across groups. Returns null when there's no
-  // active photo or it isn't currently rendered.
-  const findActiveCell = (): { row: number; col: number } | null => {
-    if (!activePhotoId) return null
-    for (let r = 0; r < photoRows.length; r++) {
-      const row = photoRows[r]
-      const c = row.cells.findIndex((cell) => cell.photo.id === activePhotoId)
-      if (c >= 0) return { row: r, col: c }
-    }
-    return null
-  }
-
-  // Handle keyboard shortcuts for photo navigation. Operates on the
-  // grouped grid the user sees, so a half-full last row of a group
-  // doesn't make ArrowDown skip into the wrong place.
-  useEffect(() => {
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (photoRows.length === 0) return
-      const target = e.target as HTMLElement | null
-      if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA')) {
-        return
-      }
-
-      const move = (dr: number, dc: number) => {
-        const current = findActiveCell() ?? { row: 0, col: -1 }
-        let nextRow = current.row
-        let nextCol = current.col + dc
-
-        if (dc !== 0) {
-          // Wrap left/right across row boundaries.
-          while (nextCol < 0 && nextRow > 0) {
-            nextRow -= 1
-            nextCol = photoRows[nextRow].cells.length - 1
-          }
-          while (
-            nextRow < photoRows.length &&
-            nextCol >= photoRows[nextRow].cells.length
-          ) {
-            if (nextRow === photoRows.length - 1) {
-              nextCol = photoRows[nextRow].cells.length - 1
-              break
-            }
-            nextRow += 1
-            nextCol = 0
-          }
-          if (nextCol < 0) nextCol = 0
-        }
-
-        if (dr !== 0) {
-          nextRow += dr
-          if (nextRow < 0) nextRow = 0
-          if (nextRow >= photoRows.length) nextRow = photoRows.length - 1
-          // Clamp the column to the destination row's actual width so
-          // moving down into a half-full row lands on its last cell
-          // instead of nothing.
-          const rowLen = photoRows[nextRow].cells.length
-          if (nextCol >= rowLen) nextCol = rowLen - 1
-          if (nextCol < 0) nextCol = 0
-        }
-
-        const dest = photoRows[nextRow]?.cells[nextCol]
-        if (!dest) return
-        if (e.shiftKey) {
-          selectRange(dest.globalIndex)
-        } else {
-          selectPhoto(dest.photo.id, dest.globalIndex)
-        }
-      }
-
-      switch (e.key) {
-        case 'ArrowUp':
-          e.preventDefault()
-          move(-1, 0)
-          break
-        case 'ArrowDown':
-          e.preventDefault()
-          move(1, 0)
-          break
-        case 'ArrowLeft':
-          e.preventDefault()
-          move(0, -1)
-          break
-        case 'ArrowRight':
-          e.preventDefault()
-          move(0, 1)
-          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
-  }, [photoRows, photos, selectedPhotos, activePhotoId])
-
-  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,151 +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 tagIds = sp.get('tag_ids')
-  if (tagIds) {
-    const ids = tagIds.split(',').map((t) => t.trim()).filter(Boolean)
-    if (ids.length > 0) out.tagIds = ids
-  }
-
-  if (sp.get('duplicates') === 'true') out.duplicates = true
-
-  const groupBy = sp.get('group')
-  if (groupBy === 'date' || groupBy === 'tag') out.groupBy = groupBy
-
-  const section = sp.get('section')
-  if (section) (out as any).currentSection = section
-
-  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 & { currentSection?: string }) {
-  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.tagIds.length > 0) sp.set('tag_ids', f.tagIds.join(','))
-  if (f.duplicates) sp.set('duplicates', 'true')
-  if (f.groupBy !== 'date') sp.set('group', f.groupBy)
-  if (f.currentSection && f.currentSection !== 'all-photos')
-    sp.set('section', f.currentSection)
-  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/useFolderTreeQuery.ts

@@ -1,26 +0,0 @@
-import { useQuery } from '@tanstack/react-query'
-import { sourceFolders, type FolderTreeNode } from '../services/api'
-
-export const FOLDER_TREE_QUERY_KEY = ['folders', 'tree'] as const
-
-export function useFolderTreeQuery() {
-  return useQuery<FolderTreeNode[]>({
-    queryKey: FOLDER_TREE_QUERY_KEY,
-    queryFn: sourceFolders.tree,
-    staleTime: 30_000,
-  })
-}
-
-/** Walk the tree to find a node by id. Used for chip name lookups. */
-export function findFolderInTree(
-  tree: FolderTreeNode[] | undefined,
-  id: string
-): FolderTreeNode | null {
-  if (!tree) return null
-  for (const node of tree) {
-    if (node.id === id) return node
-    const child = findFolderInTree(node.children, id)
-    if (child) return child
-  }
-  return null
-}

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,280 +0,0 @@
-import { useHotkeys } from 'react-hotkeys-hook'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { usePhotoStore } from '../store/photoStore'
-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 invalidatePhotoQueries = () => {
-    queryClient.invalidateQueries({ queryKey: ['photo'] })
-    queryClient.invalidateQueries({ queryKey: ['photos'] })
-  }
-
-  const bulkRatingMutation = useMutation({
-    mutationFn: ({ ids, rating }: { ids: string[]; rating: number }) =>
-      photosApi.bulkSetRating(ids, rating),
-    onSuccess: invalidatePhotoQueries,
-    onError: (e: any) => toast.error('Bulk rating failed', e.message || 'Unknown error'),
-  })
-
-  const bulkColorMutation = useMutation({
-    mutationFn: ({ ids, color }: { ids: string[]; color: string | null }) =>
-      photosApi.bulkSetColor(ids, color),
-    onSuccess: invalidatePhotoQueries,
-    onError: (e: any) => toast.error('Bulk color failed', e.message || 'Unknown error'),
-  })
-
-  const bulkDiscardMutation = useMutation({
-    mutationFn: (ids: string[]) => photosApi.bulkDiscard(ids),
-    onSuccess: invalidatePhotoQueries,
-    onError: (e: any) => toast.error('Bulk discard failed', e.message || 'Unknown error'),
-  })
-
-  const bulkRestoreMutation = useMutation({
-    mutationFn: (ids: string[]) => photosApi.bulkRestore(ids),
-    onSuccess: invalidatePhotoQueries,
-    onError: (e: any) => toast.error('Bulk restore failed', e.message || 'Unknown error'),
-  })
-
-  /** The set of photo ids the next culling action should apply to.
-   *  - Multi-selection → all selected photos
-   *  - Single selection → that one photo
-   *  - No selection but an activePhotoId set (last clicked) → that one
-   *  - Otherwise → empty
-   */
-  const cullTargets = (): string[] => {
-    const state = usePhotoStore.getState()
-    if (state.selectedPhotos.length > 0) return state.selectedPhotos
-    if (state.activePhotoId) return [state.activePhotoId]
-    return []
-  }
-
-  /** Apply a partial PhotoUpdate to the cull targets. Picks the right
-   *  bulk endpoint when there are 2+ photos so a single API call covers
-   *  the whole selection. */
-  const updateActive = (data: PhotoUpdate) => {
-    const ids = cullTargets()
-    if (ids.length === 0) return
-
-    if (ids.length === 1) {
-      updateMutation.mutate({ id: ids[0], data })
-      return
-    }
-
-    // Multi-selection — fan out to the right bulk endpoint per field.
-    if (data.rating !== undefined) {
-      bulkRatingMutation.mutate({ ids, rating: data.rating })
-    }
-    if (data.color_label !== undefined) {
-      bulkColorMutation.mutate({ ids, color: data.color_label })
-    }
-    if (data.is_discarded === true) {
-      bulkDiscardMutation.mutate(ids)
-    } else if (data.is_discarded === false) {
-      bulkRestoreMutation.mutate(ids)
-    }
-  }
-
-  // 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)
-
-  // Search focus (/ or Cmd/Ctrl+F).
-  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,67 +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 tagIds = useFilterStore((s) => s.tagIds)
-  const duplicates = useFilterStore((s) => s.duplicates)
-  const groupBy = useFilterStore((s) => s.groupBy)
-  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,
-        tagIds,
-        duplicates,
-        groupBy,
-        sortBy,
-        sortOrder,
-      }),
-    [q, dateFrom, dateTo, mediaTypes, ratingMin, colorLabel, flag, heapId, folderId, tagIds, duplicates, groupBy, 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/hooks/useTagsQuery.ts

@@ -1,12 +0,0 @@
-import { useQuery } from '@tanstack/react-query'
-import { tags as tagsApi, type Tag } from '../services/api'
-
-export const TAGS_QUERY_KEY = ['tags'] as const
-
-export function useTagsQuery() {
-  return useQuery<Tag[]>({
-    queryKey: TAGS_QUERY_KEY,
-    queryFn: tagsApi.list,
-    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,310 +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. Source roots are config-driven now (PHOTO_DIRS in
-// .env → bootstrap on backend startup), so the UI only reads them and
-// optionally renames the display label.
-export interface FolderTreeNode {
-  id: string
-  name: string
-  path: string
-  photo_count: number
-  children: FolderTreeNode[]
-}
-
-export const sourceFolders = {
-  list: async () => {
-    const response = await api.get('/folders')
-    return response.data
-  },
-
-  /** Recursive folder tree, one root per active source root. */
-  tree: async (): Promise<FolderTreeNode[]> => {
-    const response = await api.get('/folders/tree')
-    return response.data
-  },
-
-  scan: async (folderId: string) => {
-    const response = await api.post(`/folders/${folderId}/scan`)
-    return response.data
-  },
-
-  /** Rename the display label only — the on-disk path is controlled by
-   *  the docker mount and cannot be changed from the UI. */
-  rename: async (folderId: string, name: string) => {
-    const response = await api.patch(`/folders/${folderId}`, { name })
-    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
-  },
-
-  /** Bulk discard — matches the backend BulkAction schema. */
-  bulkDiscard: async (photoIds: string[]) => {
-    const response = await api.post('/photos/bulk', {
-      ids: photoIds,
-      action: 'discard',
-    })
-    return response.data
-  },
-
-  /** Bulk restore from discarded. */
-  bulkRestore: async (photoIds: string[]) => {
-    const response = await api.post('/photos/bulk', {
-      ids: photoIds,
-      action: 'restore',
-    })
-    return response.data
-  },
-
-  /** Bulk set rating (0-5). */
-  bulkSetRating: async (photoIds: string[], rating: number) => {
-    const response = await api.post('/photos/bulk', {
-      ids: photoIds,
-      action: 'set_rating',
-      value: rating,
-    })
-    return response.data
-  },
-
-  /** Bulk set color label (or null to clear). */
-  bulkSetColor: async (photoIds: string[], color: string | null) => {
-    const response = await api.post('/photos/bulk', {
-      ids: photoIds,
-      action: 'set_color',
-      value: color,
-    })
-    return response.data
-  },
-
-  /** Move photos into a target folder (or source root). Returns
-   *  { moved, errors[] }. */
-  move: async (photoIds: string[], targetId: string) => {
-    const response = await api.post('/photos/move', {
-      photo_ids: photoIds,
-      target_id: targetId,
-    })
-    return response.data as { status: string; moved: number; errors: Array<{ id: string; error: string }> }
-  },
-
-  /** Copy photos into a target folder. Originals are unaffected; new
-   *  rows are created with is_duplicate=true. */
-  copy: async (photoIds: string[], targetId: string) => {
-    const response = await api.post('/photos/copy', {
-      photo_ids: photoIds,
-      target_id: targetId,
-    })
-    return response.data as { status: string; copied: number; errors: Array<{ id: string; error: string }> }
-  },
-
-  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
-  },
-
-  /** Convert a heap into a folder by moving (or copying) every member
-   *  photo into the target directory. Optionally creates a subfolder
-   *  inside the target by name. */
-  convert: async (
-    heapId: string,
-    body: {
-      target_id: string
-      mode: 'move' | 'copy'
-      delete_heap: boolean
-      subfolder_name?: string | null
-    }
-  ) => {
-    const response = await api.post(`/heaps/${heapId}/convert`, body)
-    return response.data as {
-      status: string
-      mode: 'move' | 'copy'
-      moved: number
-      copied: number
-      errors: Array<{ id: string; error: string }>
-      heap_deleted: boolean
-    }
-  },
-}
-
-// Tags API
-export interface Tag {
-  id: string
-  name: string
-  color: string | null
-  photo_count: number
-}
-
-export const tags = {
-  list: async (): Promise<Tag[]> => {
-    const response = await api.get('/tags')
-    return response.data
-  },
-
-  create: async (name: string, color?: string): Promise<Tag> => {
-    const response = await api.post('/tags', { name, color })
-    return response.data
-  },
-
-  update: async (tagId: string, data: { name?: string; color?: string }): Promise<Tag> => {
-    const response = await api.patch(`/tags/${tagId}`, data)
-    return response.data
-  },
-
-  delete: async (tagId: string): Promise<void> => {
-    await api.delete(`/tags/${tagId}`)
-  },
-
-  /** Add one or more tags to a photo. */
-  addToPhoto: async (photoId: string, tagIds: string[]) => {
-    const response = await api.post(`/photos/${photoId}/tags`, { tag_ids: tagIds })
-    return response.data
-  },
-
-  /** Remove a tag from a photo. */
-  removeFromPhoto: async (photoId: string, tagId: string): Promise<void> => {
-    await api.delete(`/photos/${photoId}/tags/${tagId}`)
-  },
-}
-
-// 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,233 +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 type GroupBy = 'date' | 'tag'
-
-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
-  /** Restrict to photos that have ALL of these tag ids (AND semantics). */
-  tagIds: string[]
-  /** When true, restrict to photos flagged as duplicates by the scanner. */
-  duplicates: boolean
-  /** Visual grouping mode. 'date' groups by month when sortBy is a date
-   *  field; 'tag' groups by photo tag membership. Independent of filters. */
-  groupBy: GroupBy
-  sortBy: SortField
-  sortOrder: SortOrder
-}
-
-/** Identifies which "section" of the app the user is currently viewing.
- *  Sections each carry their own filter state — switching to one restores
- *  whatever filters were active there last time, switching away saves the
- *  current state under the section being left. */
-export const ALL_PHOTOS_SECTION = 'all-photos'
-
-interface FilterStore extends FilterState {
-  /** The active section id. Changes via navigateToSection. */
-  currentSection: string
-  /** Per-section snapshot of filter state, in-memory. Restored on return. */
-  sectionFilters: Record<string, FilterState>
-  /** Per-section "intrinsic" filters — the preset that defines what makes
-   *  a section that section (e.g. flag=discarded for the discarded
-   *  section). Used by clearAll to reset within a section without
-   *  navigating away. */
-  sectionPresets: Record<string, Partial<FilterState>>
-
-  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
-  setTagIds: (ids: string[]) => void
-  toggleTagId: (id: string) => void
-  setDuplicates: (v: boolean) => void
-  setGroupBy: (mode: GroupBy) => void
-  setSortBy: (field: SortField) => void
-  setSortOrder: (order: SortOrder) => void
-  toggleSortOrder: () => void
-
-  /** Navigate to a section. Saves the current section's filter state into
-   *  the in-memory map under the OLD section id, then loads the saved
-   *  state for the destination — or, if none exists, applies the preset
-   *  overrides on top of INITIAL_FILTERS. The preset is also stored so
-   *  clearAll inside the section resets correctly. */
-  navigateToSection: (
-    sectionId: string,
-    presetOverrides?: Partial<FilterState>
-  ) => void
-
-  hydrate: (partial: Partial<FilterState> & { currentSection?: string }) => void
-  /** Reset filters within the CURRENT section back to its preset. Doesn't
-   *  navigate. For an explicit "go to all photos" use navigateToSection. */
-  clearAll: () => void
-}
-
-export const INITIAL_FILTERS: FilterState = {
-  q: '',
-  dateFrom: null,
-  dateTo: null,
-  mediaTypes: [],
-  ratingMin: 0,
-  colorLabel: null,
-  flag: 'any',
-  heapId: null,
-  folderId: null,
-  tagIds: [],
-  duplicates: false,
-  groupBy: 'date',
-  sortBy: 'taken_at',
-  sortOrder: 'desc',
-}
-
-/** Pull the FilterState slice out of the full store, dropping the
- *  control fields. Used when snapshotting current filters into the
- *  per-section map. */
-function snapshotFilters(s: FilterState): FilterState {
-  return {
-    q: s.q,
-    dateFrom: s.dateFrom,
-    dateTo: s.dateTo,
-    mediaTypes: [...s.mediaTypes],
-    ratingMin: s.ratingMin,
-    colorLabel: s.colorLabel,
-    flag: s.flag,
-    heapId: s.heapId,
-    folderId: s.folderId,
-    tagIds: [...s.tagIds],
-    duplicates: s.duplicates,
-    groupBy: s.groupBy,
-    sortBy: s.sortBy,
-    sortOrder: s.sortOrder,
-  }
-}
-
-export const useFilterStore = create<FilterStore>((set) => ({
-  ...INITIAL_FILTERS,
-  currentSection: ALL_PHOTOS_SECTION,
-  sectionFilters: {},
-  sectionPresets: { [ALL_PHOTOS_SECTION]: {} },
-
-  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 }),
-  setTagIds: (tagIds) => set({ tagIds }),
-  toggleTagId: (id) =>
-    set((s) => ({
-      tagIds: s.tagIds.includes(id)
-        ? s.tagIds.filter((t) => t !== id)
-        : [...s.tagIds, id],
-    })),
-  setDuplicates: (duplicates) => set({ duplicates }),
-  setGroupBy: (groupBy) => set({ groupBy }),
-  setSortBy: (sortBy) => set({ sortBy }),
-  setSortOrder: (sortOrder) => set({ sortOrder }),
-  toggleSortOrder: () =>
-    set((s) => ({ sortOrder: s.sortOrder === 'desc' ? 'asc' : 'desc' })),
-
-  navigateToSection: (sectionId, presetOverrides = {}) =>
-    set((s) => {
-      // Snapshot the current section's filters before switching.
-      const updatedSectionFilters = {
-        ...s.sectionFilters,
-        [s.currentSection]: snapshotFilters(s),
-      }
-      // Remember this section's intrinsic preset (last write wins, which
-      // is fine — sections are uniquely identified by id).
-      const updatedSectionPresets = {
-        ...s.sectionPresets,
-        [sectionId]: presetOverrides,
-      }
-      // Restore the destination section's saved state, or apply the
-      // preset on top of fresh defaults if it's never been visited.
-      const saved = updatedSectionFilters[sectionId]
-      const next: FilterState = saved
-        ? saved
-        : { ...INITIAL_FILTERS, ...presetOverrides }
-
-      return {
-        ...next,
-        currentSection: sectionId,
-        sectionFilters: updatedSectionFilters,
-        sectionPresets: updatedSectionPresets,
-      }
-    }),
-
-  hydrate: (partial) => set(partial),
-  clearAll: () =>
-    set((s) => {
-      const preset = s.sectionPresets[s.currentSection] ?? {}
-      return { ...INITIAL_FILTERS, ...preset }
-    }),
-}))
-
-/** 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
-  if (f.tagIds.length > 0) params.tag_ids = f.tagIds.join(',')
-  if (f.duplicates) params.is_duplicate = 'true'
-  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 ||
-    f.tagIds.length > 0 ||
-    f.duplicates
-  )
-}

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,23 +0,0 @@
-export interface PhotoTagSummary {
-  id: string
-  name: string
-  color: string | null
-}
-
-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
-  is_duplicate: boolean
-  file_hash: string
-  thumb_small?: string
-  thumb_medium?: string
-  thumb_large?: string
-  tags?: PhotoTagSummary[]
-}

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,24 +0,0 @@
-# Mulita configuration file
-#
-# Source roots and discard handling are owned by the database — manage them
-# from the UI (left sidebar → "+ Add Source Folder") or via the API. Only
-# operational tuning lives here.
-
-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
-
-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,44 @@
+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.
+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
+		}
+		if !pp.validateSession(c.Request.Context(), token) {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid session"})
+			return
+		}
+		c.Set("token", token)
+		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
+}

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. PhotoUID is the row key; both
+// payload fields are nullable so the sparse "no rating / no colour" state
+// round-trips cleanly. The Node prototype kept this in a JSON file; we
+// migrate to MariaDB here so the M4 sharing work has a real table to
+// extend.
+type Mark struct {
+	PhotoUID  string    `gorm:"primaryKey;size:64;column:photo_uid" 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_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_marks.go

@@ -0,0 +1,206 @@
+package main
+
+import (
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+// validColors is the four-color palette mule-image always shipped. The
+// empty string is the explicit "clear color" sentinel.
+var validColors = map[string]struct{}{
+	"red":    {},
+	"orange": {},
+	"yellow": {},
+	"green":  {},
+}
+
+// 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 entire `marks` table 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) (map[string]map[string]any, error) {
+	var rows []Mark
+	if err := db.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)
+		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 = ?", uid).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 string, patch *markPatch) (map[string]any, error) {
+	var m Mark
+	err := db.Where("photo_uid = ?", uid).First(&m).Error
+	if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, err
+	}
+	m.PhotoUID = uid
+	keep := patch.apply(&m)
+	m.UpdatedAt = time.Now().UTC()
+	if !keep {
+		// Drop the row entirely so a re-fetch returns {}.
+		if err := db.Where("photo_uid = ?", uid).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, &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
+		}
+		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, &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_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,120 @@
+// 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"
+)
+
+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)
+
+	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))
+	}
+
+	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,119 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"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
+}
+
+// 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()
+		}
+	}()
+}

web/.gitignore

@@ -0,0 +1,23 @@
+node_modules
+
+# Output
+.output
+.vercel
+.netlify
+.wrangler
+/.svelte-kit
+/build
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.*
+!.env.example
+!.env.test
+
+# Vite
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*

web/.npmrc

@@ -0,0 +1 @@
+engine-strict=true

web/README.md

@@ -0,0 +1,42 @@
+# sv
+
+Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
+
+## Creating a project
+
+If you're seeing this, you've probably already done this step. Congrats!
+
+```sh
+# create a new project
+npx sv create my-app
+```
+
+To recreate this project with the same configuration:
+
+```sh
+# recreate this project
+npx sv@0.15.3 create --template minimal --types ts --install npm web
+```
+
+## Developing
+
+Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+
+```sh
+npm run dev
+
+# or start the server and open the app in a new browser tab
+npm run dev -- --open
+```
+
+## Building
+
+To create a production version of your app:
+
+```sh
+npm run build
+```
+
+You can preview the production build with `npm run preview`.
+
+> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.

web/components.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://shadcn-svelte.com/schema.json",
+  "style": "default",
+  "tailwind": {
+    "css": "src/app.css",
+    "baseColor": "zinc"
+  },
+  "aliases": {
+    "components": "$lib/components",
+    "utils": "$lib/utils",
+    "ui": "$lib/components/ui",
+    "hooks": "$lib/hooks",
+    "lib": "$lib"
+  },
+  "typescript": true,
+  "registry": "https://shadcn-svelte.com/registry"
+}