Delete backend

backend/.env.example

@@ -1,39 +0,0 @@
-# ── App ───────────────────────────────────────────────────────────────────────
-APP_NAME="KeyStone Photo Cloud"
-APP_VERSION="0.1.0"
-DEBUG=false
-ENVIRONMENT=production
-
-# ── Database (Supabase PostgreSQL) ────────────────────────────────────────────
-# Use the "Session Mode" connection string from Supabase Dashboard > Settings > Database
-DATABASE_URL=postgresql+asyncpg://postgres.YOURPROJECT:PASSWORD@aws-0-us-east-1.pooler.supabase.com:5432/postgres
-
-# ── Supabase ──────────────────────────────────────────────────────────────────
-SUPABASE_URL=https://YOURPROJECT.supabase.co
-SUPABASE_ANON_KEY=your-supabase-anon-key
-SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key
-# Found at: Supabase Dashboard → Settings → API → JWT Settings → JWT Secret
-SUPABASE_JWT_SECRET=your-supabase-jwt-secret
-
-# ── Hugging Face Bucket (S3-compatible) ───────────────────────────────────────
-HF_TOKEN=hf_your_token_here
-HF_DATASET_REPO=your-username/keystone-photos
-HF_BUCKET_NAME=keystone-photos
-
-# HF S3 credentials (generate at: https://huggingface.co/settings/tokens)
-HF_ACCESS_KEY_ID=your-hf-s3-access-key
-HF_SECRET_ACCESS_KEY=your-hf-s3-secret-key
-HF_S3_ENDPOINT=https://huggingface.co
-
-# ── Upload Limits ─────────────────────────────────────────────────────────────
-MAX_UPLOAD_SIZE_MB=50
-THUMBNAIL_SIZE=512
-THUMBNAIL_QUALITY=85
-
-# ── Rate Limiting ─────────────────────────────────────────────────────────────
-RATE_LIMIT_PER_MINUTE=60
-RATE_LIMIT_UPLOADS_PER_MINUTE=20
-
-# ── CORS ──────────────────────────────────────────────────────────────────────
-# Comma-separated list of allowed origins. Use * for development only.
-CORS_ORIGINS=*

backend/Dockerfile

@@ -1,39 +0,0 @@
-# KeyStone Backend – Dockerfile
-# Deployed on Hugging Face Spaces (Docker SDK)
-# Port 7860 is required by Hugging Face Spaces
-
-FROM python:3.11-slim
-
-# System dependencies for Pillow + python-magic
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    libmagic1 \
-    libmagic-dev \
-    libjpeg-dev \
-    zlib1g-dev \
-    libwebp-dev \
-    curl \
-    && rm -rf /var/lib/apt/lists/*
-
-WORKDIR /app
-
-# Install Python dependencies first (layer caching)
-COPY requirements.txt .
-RUN pip install --no-cache-dir --upgrade pip && \
-    pip install --no-cache-dir -r requirements.txt
-
-# Copy application code
-COPY . .
-
-# Create non-root user for security
-RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
-USER appuser
-
-# Hugging Face Spaces requires port 7860
-EXPOSE 7860
-
-# Health check
-HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
-    CMD curl -f http://localhost:7860/health || exit 1
-
-# Start FastAPI with uvicorn
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "2"]

backend/README.md

@@ -1,30 +0,0 @@
----
-title: KeyStone Photo Cloud API
-emoji: 📸
-colorFrom: purple
-colorTo: indigo
-sdk: docker
-pinned: false
-license: mit
-app_port: 7860
----
-
-# KeyStone Photo Cloud – Backend API
-
-Private Google Photos alternative backend. See the [full documentation](/docs) at `/docs`.
-
-## Endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | /health | Health check |
-| POST | /auth/verify | Verify Supabase JWT |
-| POST | /sync/start | Register device |
-| POST | /sync/check | Dedup hash check |
-| POST | /upload | Upload a photo |
-| GET | /photos | List photos |
-| GET | /photos/{id} | Get photo |
-| DELETE | /photos/{id} | Delete photo |
-| GET | /albums | List albums |
-| POST | /albums | Create album |
-| GET | /search | Search photos |

backend/alembic.ini

@@ -1,88 +0,0 @@
-# Alembic configuration file
-# See: https://alembic.sqlalchemy.org/en/latest/tutorial.html
-
-[alembic]
-# path to migration scripts
-script_location = alembic
-
-# template used to generate migration file names
-file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
-
-# timezone to use when rendering the date within the migration file
-# leave blank for current timezone
-# timezone =
-
-# max length of characters to apply to the
-# "slug" field
-truncate_slug_length = 40
-
-# set to 'true' to run the environment during
-# the 'revision' command, regardless of autogenerate
-# revision_environment = false
-
-# set to 'true' to allow .pyc and .pyo files without
-# a source .py file to be detected as revisions in the
-# versions/ directory
-# sourceless = false
-
-# version location specification; This defaults
-# to alembic/versions.  When using multiple version
-# directories, initial revisions must specify a --version-path.
-# version_path_separator = os  # Use os.pathsep. Default configuration
-# used for new projects.
-# version_path_separator = :
-# version_path_separator = ;
-# version_path_separator = space
-version_locations = %(here)s/alembic/versions
-
-# the output encoding used when revision files
-# are written from script.py.mako
-# output_encoding = utf-8
-
-sqlalchemy.url = driver://user:pass@localhost/dbname
-
-[post_write_hooks]
-# post_write_hooks defines scripts or Python functions that are run
-# on newly generated revision scripts.  See the documentation for further
-# detail and examples
-
-# format using "black" - use the console_scripts runner, against the "black" entrypoint
-# hooks = black
-# black.type = console_scripts
-# black.entrypoint = black
-# black.options = -l 79 REVISION_SCRIPT_FILENAME
-
-# Logging configuration
-[loggers]
-keys = root,sqlalchemy,alembic
-
-[handlers]
-keys = console
-
-[formatters]
-keys = generic
-
-[logger_root]
-level = WARN
-handlers = console
-qualname =
-
-[logger_sqlalchemy]
-level = WARN
-handlers =
-qualname = sqlalchemy.engine
-
-[logger_alembic]
-level = INFO
-handlers =
-qualname = alembic
-
-[handler_console]
-class = StreamHandler
-args = (sys.stderr,)
-level = NOTSET
-formatter = generic
-
-[formatter_generic]
-format = %(levelname)-5.5s [%(name)s] %(message)s
-datefmt = %H:%M:%S

backend/alembic/env.py

@@ -1,73 +0,0 @@
-"""
-Alembic Environment Configuration
-"""
-
-import asyncio
-import os
-from logging.config import fileConfig
-
-from sqlalchemy import pool
-from sqlalchemy.engine import Connection
-from sqlalchemy.ext.asyncio import async_engine_from_config
-
-from alembic import context
-
-# Load models so Alembic can detect them
-import sys
-sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
-
-from app.database import Base
-from app.models import User, Device, Photo, UploadJob, Album, AlbumPhoto  # noqa
-
-# Alembic Config object
-config = context.config
-
-# Override sqlalchemy.url from environment variable
-database_url = os.environ.get("DATABASE_URL", "")
-if database_url:
-    config.set_main_option("sqlalchemy.url", database_url)
-
-# Interpret the config file for logging
-if config.config_file_name is not None:
-    fileConfig(config.config_file_name)
-
-target_metadata = Base.metadata
-
-
-def run_migrations_offline() -> None:
-    url = config.get_main_option("sqlalchemy.url")
-    context.configure(
-        url=url,
-        target_metadata=target_metadata,
-        literal_binds=True,
-        dialect_opts={"paramstyle": "named"},
-    )
-    with context.begin_transaction():
-        context.run_migrations()
-
-
-def do_run_migrations(connection: Connection) -> None:
-    context.configure(connection=connection, target_metadata=target_metadata)
-    with context.begin_transaction():
-        context.run_migrations()
-
-
-async def run_async_migrations() -> None:
-    connectable = async_engine_from_config(
-        config.get_section(config.config_ini_section, {}),
-        prefix="sqlalchemy.",
-        poolclass=pool.NullPool,
-    )
-    async with connectable.connect() as connection:
-        await connection.run_sync(do_run_migrations)
-    await connectable.dispose()
-
-
-def run_migrations_online() -> None:
-    asyncio.run(run_async_migrations())
-
-
-if context.is_offline_mode():
-    run_migrations_offline()
-else:
-    run_migrations_online()

backend/alembic/versions/001_initial.py

@@ -1,141 +0,0 @@
-"""Initial migration – create all tables
-
-Revision ID: 001_initial
-Revises:
-Create Date: 2026-07-16
-"""
-
-from alembic import op
-import sqlalchemy as sa
-from sqlalchemy.dialects import postgresql
-
-revision = "001_initial"
-down_revision = None
-branch_labels = None
-depends_on = None
-
-
-def upgrade() -> None:
-    # ── users ─────────────────────────────────────────────────────────────────
-    op.create_table(
-        "users",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("supabase_id", sa.String(255), nullable=False),
-        sa.Column("email", sa.String(320), nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("is_active", sa.Boolean(), nullable=False, server_default="true"),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("supabase_id"),
-        sa.UniqueConstraint("email"),
-    )
-    op.create_index("ix_users_supabase_id", "users", ["supabase_id"])
-    op.create_index("ix_users_email", "users", ["email"])
-
-    # ── devices ───────────────────────────────────────────────────────────────
-    op.create_table(
-        "devices",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("device_name", sa.String(255), nullable=False),
-        sa.Column("platform", sa.String(50), nullable=False),
-        sa.Column("device_token", sa.String(512), nullable=True),
-        sa.Column("last_sync", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("registered_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index("ix_devices_user_id", "devices", ["user_id"])
-
-    # ── photos ────────────────────────────────────────────────────────────────
-    op.create_table(
-        "photos",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("sha256", sa.String(64), nullable=False),
-        sa.Column("filename", sa.String(512), nullable=False),
-        sa.Column("mime_type", sa.String(128), nullable=False),
-        sa.Column("bucket_path", sa.Text(), nullable=False),
-        sa.Column("thumbnail_path", sa.Text(), nullable=True),
-        sa.Column("preview_path", sa.Text(), nullable=True),
-        sa.Column("width", sa.Integer(), nullable=True),
-        sa.Column("height", sa.Integer(), nullable=True),
-        sa.Column("size", sa.BigInteger(), nullable=False),
-        sa.Column("taken_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("uploaded_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("deleted", sa.Boolean(), nullable=False, server_default="false"),
-        sa.Column("is_favorite", sa.Boolean(), nullable=False, server_default="false"),
-        sa.Column("ai_description", sa.Text(), nullable=True),
-        sa.Column("ai_tags", sa.Text(), nullable=True),
-        sa.Column("clip_embedding", sa.Text(), nullable=True),
-        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index("ix_photos_user_id", "photos", ["user_id"])
-    op.create_index("ix_photos_sha256", "photos", ["sha256"])
-
-    # ── upload_jobs ───────────────────────────────────────────────────────────
-    op.create_table(
-        "upload_jobs",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("photo_id", postgresql.UUID(as_uuid=True), nullable=True),
-        sa.Column("filename", sa.String(512), nullable=False),
-        sa.Column("sha256", sa.String(64), nullable=False),
-        sa.Column("status", sa.Enum(
-            "pending", "uploading", "processing", "completed", "failed", "duplicate",
-            name="uploadstatus"
-        ), nullable=False),
-        sa.Column("retries", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("max_retries", sa.Integer(), nullable=False, server_default="3"),
-        sa.Column("error_message", sa.Text(), nullable=True),
-        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("completed_at", sa.DateTime(timezone=True), nullable=True),
-        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["photo_id"], ["photos.id"], ondelete="SET NULL"),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index("ix_upload_jobs_user_id", "upload_jobs", ["user_id"])
-    op.create_index("ix_upload_jobs_sha256", "upload_jobs", ["sha256"])
-
-    # ── albums ────────────────────────────────────────────────────────────────
-    op.create_table(
-        "albums",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("name", sa.String(255), nullable=False),
-        sa.Column("description", sa.Text(), nullable=True),
-        sa.Column("cover_photo_id", postgresql.UUID(as_uuid=True), nullable=True),
-        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["cover_photo_id"], ["photos.id"], ondelete="SET NULL"),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index("ix_albums_user_id", "albums", ["user_id"])
-
-    # ── album_photos ──────────────────────────────────────────────────────────
-    op.create_table(
-        "album_photos",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("album_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("photo_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("added_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["album_id"], ["albums.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["photo_id"], ["photos.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("album_id", "photo_id", name="uq_album_photo"),
-    )
-    op.create_index("ix_album_photos_album_id", "album_photos", ["album_id"])
-    op.create_index("ix_album_photos_photo_id", "album_photos", ["photo_id"])
-
-
-def downgrade() -> None:
-    op.drop_table("album_photos")
-    op.drop_table("albums")
-    op.drop_table("upload_jobs")
-    op.drop_table("photos")
-    op.drop_table("devices")
-    op.drop_table("users")
-    op.execute("DROP TYPE IF EXISTS uploadstatus")

backend/app/config.py

@@ -1,76 +0,0 @@
-"""
-KeyStone – Application Configuration
-All settings are read from environment variables (or a .env file via python-dotenv).
-"""
-
-from functools import lru_cache
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-
-class Settings(BaseSettings):
-    model_config = SettingsConfigDict(
-        env_file=".env",
-        env_file_encoding="utf-8",
-        case_sensitive=False,
-        extra="ignore",
-    )
-
-    # ── App ──────────────────────────────────────────────────────────────────
-    app_name: str = "KeyStone Photo Cloud"
-    app_version: str = "0.1.0"
-    debug: bool = False
-    environment: str = "production"  # development | production
-
-    # ── Database (Supabase PostgreSQL) ───────────────────────────────────────
-    database_url: str = "postgresql+asyncpg://postgres:postgres@localhost:5432/keystone"
-
-    # ── Supabase ─────────────────────────────────────────────────────────────
-    supabase_url: str = "https://your-project.supabase.co"
-    supabase_anon_key: str = "your-supabase-anon-key"
-    supabase_service_role_key: str = "your-supabase-service-role-key"
-    supabase_jwt_secret: str = "your-supabase-jwt-secret"
-
-    # ── Hugging Face Bucket (S3-compatible) ──────────────────────────────────
-    hf_token: str = "hf_your_token_here"
-    hf_dataset_repo: str = "your-username/keystone-photos"
-    hf_endpoint_url: str = "https://huggingface.co"
-
-    # S3-compatible access (HF Datasets S3 gateway)
-    hf_s3_endpoint: str = "https://huggingface.co/datasets"
-    hf_access_key_id: str = "your-hf-access-key"
-    hf_secret_access_key: str = "your-hf-secret-key"
-    hf_bucket_name: str = "keystone-photos"
-
-    # ── Upload Settings ───────────────────────────────────────────────────────
-    max_upload_size_mb: int = 50
-    thumbnail_size: int = 512
-    thumbnail_quality: int = 85
-    allowed_mime_types: list[str] = [
-        "image/jpeg",
-        "image/png",
-        "image/gif",
-        "image/webp",
-        "image/heic",
-        "image/heif",
-        "image/tiff",
-    ]
-
-    # ── Rate Limiting ─────────────────────────────────────────────────────────
-    rate_limit_per_minute: int = 60
-    rate_limit_uploads_per_minute: int = 20
-
-    # ── CORS ─────────────────────────────────────────────────────────────────
-    cors_origins: list[str] = ["*"]
-
-    @property
-    def max_upload_size_bytes(self) -> int:
-        return self.max_upload_size_mb * 1024 * 1024
-
-    @property
-    def is_development(self) -> bool:
-        return self.environment == "development"
-
-
-@lru_cache
-def get_settings() -> Settings:
-    return Settings()

backend/app/database.py

@@ -1,49 +0,0 @@
-"""
-KeyStone – Async Database Session
-Uses SQLAlchemy 2.x async engine with asyncpg driver.
-"""
-
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
-from sqlalchemy.orm import DeclarativeBase
-
-from app.config import get_settings
-
-settings = get_settings()
-
-engine = create_async_engine(
-    settings.database_url,
-    echo=settings.debug,
-    pool_pre_ping=True,
-    pool_size=10,
-    max_overflow=20,
-)
-
-AsyncSessionLocal = async_sessionmaker(
-    bind=engine,
-    class_=AsyncSession,
-    expire_on_commit=False,
-)
-
-
-class Base(DeclarativeBase):
-    """Base class for all SQLAlchemy models."""
-    pass
-
-
-async def get_db() -> AsyncSession:  # type: ignore[return]
-    """FastAPI dependency that yields an async database session."""
-    async with AsyncSessionLocal() as session:
-        try:
-            yield session
-            await session.commit()
-        except Exception:
-            await session.rollback()
-            raise
-        finally:
-            await session.close()
-
-
-async def create_tables() -> None:
-    """Create all tables (for dev/testing; migrations handled by Alembic in prod)."""
-    async with engine.begin() as conn:
-        await conn.run_sync(Base.metadata.create_all)

backend/app/main.py

@@ -1,87 +0,0 @@
-"""
-KeyStone – FastAPI Application Entry Point
-"""
-
-from contextlib import asynccontextmanager
-
-from fastapi import FastAPI, Request, status
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import JSONResponse
-from fastapi.staticfiles import StaticFiles
-from slowapi import Limiter, _rate_limit_exceeded_handler
-from slowapi.errors import RateLimitExceeded
-from slowapi.util import get_remote_address
-
-from app.config import get_settings
-from app.database import create_tables
-from app.routers import auth, upload, gallery, albums, sync, search
-
-settings = get_settings()
-
-limiter = Limiter(key_func=get_remote_address)
-
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    """Application lifespan: startup / shutdown."""
-    # Startup
-    if settings.is_development:
-        await create_tables()
-    yield
-    # Shutdown – nothing special needed
-
-
-app = FastAPI(
-    title=settings.app_name,
-    version=settings.app_version,
-    description="Private Google Photos alternative – self-hosted on Hugging Face Spaces.",
-    docs_url="/docs",
-    redoc_url="/redoc",
-    lifespan=lifespan,
-)
-
-# ── Rate Limiter ──────────────────────────────────────────────────────────────
-app.state.limiter = limiter
-app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
-
-# ── CORS ──────────────────────────────────────────────────────────────────────
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=settings.cors_origins,
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-# ── Routers ───────────────────────────────────────────────────────────────────
-app.include_router(auth.router,    prefix="/auth",    tags=["Authentication"])
-app.include_router(sync.router,    prefix="/sync",    tags=["Sync"])
-app.include_router(upload.router,  prefix="/upload",  tags=["Upload"])
-app.include_router(gallery.router, prefix="/photos",  tags=["Gallery"])
-app.include_router(albums.router,  prefix="/albums",  tags=["Albums"])
-app.include_router(search.router,  prefix="/search",  tags=["Search"])
-
-# Serve Expo web build
-app.mount("/", StaticFiles(directory="web", html=True), name="web")
-
-# ── Health ────────────────────────────────────────────────────────────────────
-@app.get("/health", tags=["Health"])
-async def health(request: Request):
-    """Health check endpoint – returns app info and status."""
-    return {
-        "status": "ok",
-        "service": settings.app_name,
-        "version": settings.app_version,
-        "environment": settings.environment,
-    }
-
-
-# ── Global Exception Handler ──────────────────────────────────────────────────
-@app.exception_handler(Exception)
-async def global_exception_handler(request: Request, exc: Exception):
-    if settings.debug:
-        raise exc
-    return JSONResponse(
-        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-        content={"detail": "An unexpected error occurred."},
-    )

backend/app/middleware/__init__.py

@@ -1 +0,0 @@
-"""KeyStone – Middleware Package"""

backend/app/middleware/auth.py

@@ -1,81 +0,0 @@
-"""
-KeyStone – JWT Authentication Middleware
-Verifies Supabase-issued JWTs using the project's JWT secret.
-"""
-
-import logging
-from typing import Annotated
-
-import httpx
-from fastapi import Depends, HTTPException, status
-from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
-from jose import JWTError, jwt
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.config import get_settings
-from app.database import get_db
-from app.models.user import User
-
-logger = logging.getLogger(__name__)
-settings = get_settings()
-
-security = HTTPBearer()
-
-
-def _decode_jwt(token: str) -> dict:
-    """Decode and verify a Supabase JWT using the project JWT secret."""
-    try:
-        payload = jwt.decode(
-            token,
-            settings.supabase_jwt_secret,
-            algorithms=["HS256"],
-            options={"verify_aud": False},  # Supabase uses custom audience
-        )
-        return payload
-    except JWTError as exc:
-        logger.warning("JWT decode failed: %s", exc)
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Invalid or expired token.",
-            headers={"WWW-Authenticate": "Bearer"},
-        ) from exc
-
-
-async def get_current_user(
-    credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)],
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> User:
-    """
-    FastAPI dependency.
-    1. Decodes the Bearer JWT.
-    2. Extracts sub (Supabase user ID) and email.
-    3. Upserts the user in our database.
-    4. Returns the User ORM object.
-    """
-    payload = _decode_jwt(credentials.credentials)
-
-    supabase_id: str | None = payload.get("sub")
-    email: str | None = payload.get("email")
-
-    if not supabase_id:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Token missing subject claim.",
-        )
-
-    # Upsert user in local DB
-    result = await db.execute(select(User).where(User.supabase_id == supabase_id))
-    user = result.scalar_one_or_none()
-
-    if user is None:
-        user = User(supabase_id=supabase_id, email=email or "")
-        db.add(user)
-        await db.flush()
-        logger.info("New user created: supabase_id=%s", supabase_id)
-
-    return user
-
-
-# Convenient type alias for route dependencies
-CurrentUser = Annotated[User, Depends(get_current_user)]

backend/app/models/__init__.py

@@ -1,9 +0,0 @@
-"""KeyStone SQLAlchemy Models Package"""
-
-from app.models.user import User
-from app.models.device import Device
-from app.models.photo import Photo
-from app.models.upload_job import UploadJob
-from app.models.album import Album, AlbumPhoto
-
-__all__ = ["User", "Device", "Photo", "UploadJob", "Album", "AlbumPhoto"]

backend/app/models/album.py

@@ -1,71 +0,0 @@
-"""
-KeyStone – Album Model
-"""
-
-import uuid
-from datetime import datetime, timezone
-
-from sqlalchemy import String, DateTime, Text, ForeignKey, UniqueConstraint
-from sqlalchemy.dialects.postgresql import UUID
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-
-from app.database import Base
-
-
-class Album(Base):
-    __tablename__ = "albums"
-
-    id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
-    )
-    user_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
-    )
-    name: Mapped[str] = mapped_column(String(255), nullable=False)
-    description: Mapped[str | None] = mapped_column(Text, nullable=True)
-    cover_photo_id: Mapped[uuid.UUID | None] = mapped_column(
-        UUID(as_uuid=True), ForeignKey("photos.id", ondelete="SET NULL"), nullable=True
-    )
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )
-    updated_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True),
-        default=lambda: datetime.now(timezone.utc),
-        onupdate=lambda: datetime.now(timezone.utc),
-    )
-
-    # ── Relationships ─────────────────────────────────────────────────────────
-    user: Mapped["User"] = relationship("User", back_populates="albums")
-    album_photos: Mapped[list["AlbumPhoto"]] = relationship(
-        "AlbumPhoto", back_populates="album", cascade="all, delete-orphan"
-    )
-
-    def __repr__(self) -> str:
-        return f"<Album id={self.id} name={self.name}>"
-
-
-class AlbumPhoto(Base):
-    """Junction table between albums and photos."""
-
-    __tablename__ = "album_photos"
-    __table_args__ = (
-        UniqueConstraint("album_id", "photo_id", name="uq_album_photo"),
-    )
-
-    id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
-    )
-    album_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), ForeignKey("albums.id", ondelete="CASCADE"), nullable=False, index=True
-    )
-    photo_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), ForeignKey("photos.id", ondelete="CASCADE"), nullable=False, index=True
-    )
-    added_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )
-
-    # ── Relationships ─────────────────────────────────────────────────────────
-    album: Mapped["Album"] = relationship("Album", back_populates="album_photos")
-    photo: Mapped["Photo"] = relationship("Photo", back_populates="album_photos")

backend/app/models/device.py

@@ -1,36 +0,0 @@
-"""
-KeyStone – Device Model
-"""
-
-import uuid
-from datetime import datetime, timezone
-
-from sqlalchemy import String, DateTime, ForeignKey
-from sqlalchemy.dialects.postgresql import UUID
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-
-from app.database import Base
-
-
-class Device(Base):
-    __tablename__ = "devices"
-
-    id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
-    )
-    user_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
-    )
-    device_name: Mapped[str] = mapped_column(String(255), nullable=False)
-    platform: Mapped[str] = mapped_column(String(50), nullable=False)  # android | ios | web
-    device_token: Mapped[str | None] = mapped_column(String(512), nullable=True)  # push token
-    last_sync: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
-    registered_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )
-
-    # ── Relationships ─────────────────────────────────────────────────────────
-    user: Mapped["User"] = relationship("User", back_populates="devices")
-
-    def __repr__(self) -> str:
-        return f"<Device id={self.id} name={self.device_name} platform={self.platform}>"

backend/app/models/photo.py

@@ -1,64 +0,0 @@
-"""
-KeyStone – Photo Model
-"""
-
-import uuid
-from datetime import datetime, timezone
-
-from sqlalchemy import String, DateTime, Integer, Boolean, BigInteger, ForeignKey, Text
-from sqlalchemy.dialects.postgresql import UUID
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-
-from app.database import Base
-
-
-class Photo(Base):
-    __tablename__ = "photos"
-
-    id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
-    )
-    user_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
-    )
-
-    # ── File Identity ─────────────────────────────────────────────────────────
-    sha256: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
-    filename: Mapped[str] = mapped_column(String(512), nullable=False)
-    mime_type: Mapped[str] = mapped_column(String(128), nullable=False)
-
-    # ── Storage Paths ─────────────────────────────────────────────────────────
-    bucket_path: Mapped[str] = mapped_column(Text, nullable=False)         # originals/...
-    thumbnail_path: Mapped[str | None] = mapped_column(Text, nullable=True) # thumbnails/...
-    preview_path: Mapped[str | None] = mapped_column(Text, nullable=True)   # previews/...
-
-    # ── Image Metadata ────────────────────────────────────────────────────────
-    width: Mapped[int | None] = mapped_column(Integer, nullable=True)
-    height: Mapped[int | None] = mapped_column(Integer, nullable=True)
-    size: Mapped[int] = mapped_column(BigInteger, nullable=False)  # bytes
-
-    # ── Timestamps ────────────────────────────────────────────────────────────
-    taken_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )
-    uploaded_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )
-
-    # ── Soft Delete / Status ──────────────────────────────────────────────────
-    deleted: Mapped[bool] = mapped_column(Boolean, default=False)
-    is_favorite: Mapped[bool] = mapped_column(Boolean, default=False)
-
-    # ── AI Metadata (future) ──────────────────────────────────────────────────
-    ai_description: Mapped[str | None] = mapped_column(Text, nullable=True)
-    ai_tags: Mapped[str | None] = mapped_column(Text, nullable=True)       # JSON array as string
-    clip_embedding: Mapped[str | None] = mapped_column(Text, nullable=True) # JSON float array
-
-    # ── Relationships ─────────────────────────────────────────────────────────
-    user: Mapped["User"] = relationship("User", back_populates="photos")
-    album_photos: Mapped[list["AlbumPhoto"]] = relationship("AlbumPhoto", back_populates="photo", cascade="all, delete-orphan")
-    upload_jobs: Mapped[list["UploadJob"]] = relationship("UploadJob", back_populates="photo", lazy="select")
-
-    def __repr__(self) -> str:
-        return f"<Photo id={self.id} filename={self.filename} sha256={self.sha256[:8]}...>"

backend/app/models/upload_job.py

@@ -1,65 +0,0 @@
-"""
-KeyStone – UploadJob Model
-Tracks each upload attempt for retry logic and progress reporting.
-"""
-
-import uuid
-from datetime import datetime, timezone
-
-from sqlalchemy import String, DateTime, Integer, ForeignKey, Text, Enum
-from sqlalchemy.dialects.postgresql import UUID
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-import enum
-
-from app.database import Base
-
-
-class UploadStatus(str, enum.Enum):
-    PENDING = "pending"
-    UPLOADING = "uploading"
-    PROCESSING = "processing"
-    COMPLETED = "completed"
-    FAILED = "failed"
-    DUPLICATE = "duplicate"
-
-
-class UploadJob(Base):
-    __tablename__ = "upload_jobs"
-
-    id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
-    )
-    user_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
-    )
-    photo_id: Mapped[uuid.UUID | None] = mapped_column(
-        UUID(as_uuid=True), ForeignKey("photos.id", ondelete="SET NULL"), nullable=True
-    )
-
-    # ── Job Metadata ──────────────────────────────────────────────────────────
-    filename: Mapped[str] = mapped_column(String(512), nullable=False)
-    sha256: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
-    status: Mapped[UploadStatus] = mapped_column(
-        Enum(UploadStatus), default=UploadStatus.PENDING, nullable=False
-    )
-    retries: Mapped[int] = mapped_column(Integer, default=0)
-    max_retries: Mapped[int] = mapped_column(Integer, default=3)
-    error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
-
-    # ── Timestamps ────────────────────────────────────────────────────────────
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )
-    updated_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True),
-        default=lambda: datetime.now(timezone.utc),
-        onupdate=lambda: datetime.now(timezone.utc),
-    )
-    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
-
-    # ── Relationships ─────────────────────────────────────────────────────────
-    user: Mapped["User"] = relationship("User", back_populates="upload_jobs")
-    photo: Mapped["Photo | None"] = relationship("Photo", back_populates="upload_jobs")
-
-    def __repr__(self) -> str:
-        return f"<UploadJob id={self.id} filename={self.filename} status={self.status}>"

backend/app/models/user.py

@@ -1,35 +0,0 @@
-"""
-KeyStone – User Model
-"""
-
-import uuid
-from datetime import datetime, timezone
-
-from sqlalchemy import String, DateTime, Boolean
-from sqlalchemy.dialects.postgresql import UUID
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-
-from app.database import Base
-
-
-class User(Base):
-    __tablename__ = "users"
-
-    id: Mapped[uuid.UUID] = mapped_column(
-        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
-    )
-    supabase_id: Mapped[str] = mapped_column(String(255), unique=True, nullable=False, index=True)
-    email: Mapped[str] = mapped_column(String(320), unique=True, nullable=False, index=True)
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )
-    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
-
-    # ── Relationships ─────────────────────────────────────────────────────────
-    photos: Mapped[list["Photo"]] = relationship("Photo", back_populates="user", lazy="select")
-    devices: Mapped[list["Device"]] = relationship("Device", back_populates="user", lazy="select")
-    albums: Mapped[list["Album"]] = relationship("Album", back_populates="user", lazy="select")
-    upload_jobs: Mapped[list["UploadJob"]] = relationship("UploadJob", back_populates="user", lazy="select")
-
-    def __repr__(self) -> str:
-        return f"<User id={self.id} email={self.email}>"

backend/app/routers/__init__.py

@@ -1 +0,0 @@
-"""KeyStone – Routers Package"""

backend/app/routers/albums.py

@@ -1,154 +0,0 @@
-"""
-KeyStone – Albums Router
-GET  /albums              — list user's albums
-POST /albums              — create album
-GET  /albums/{id}/photos  — list photos in album
-POST /albums/{id}/photos  — add photos to album
-"""
-
-import uuid
-from typing import Annotated
-
-from fastapi import APIRouter, Depends, HTTPException, status
-from sqlalchemy import select, func
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.middleware.auth import CurrentUser
-from app.models.album import Album, AlbumPhoto
-from app.models.photo import Photo
-from app.schemas.album import AlbumCreate, AlbumOut, AlbumUpdate, AlbumWithPhotos, AddPhotosToAlbumRequest
-from app.schemas.photo import PhotoPage
-from app.routers.gallery import _enrich
-
-router = APIRouter()
-
-
-@router.get("", response_model=list[AlbumOut], summary="List all albums")
-async def list_albums(
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> list[AlbumOut]:
-    result = await db.execute(
-        select(Album).where(Album.user_id == current_user.id).order_by(Album.updated_at.desc())
-    )
-    albums = result.scalars().all()
-
-    out = []
-    for album in albums:
-        count_res = await db.execute(
-            select(func.count()).select_from(AlbumPhoto).where(AlbumPhoto.album_id == album.id)
-        )
-        photo_count = count_res.scalar_one()
-        a = AlbumOut.model_validate(album)
-        a.photo_count = photo_count
-        out.append(a)
-    return out
-
-
-@router.post("", response_model=AlbumOut, status_code=status.HTTP_201_CREATED, summary="Create an album")
-async def create_album(
-    body: AlbumCreate,
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> AlbumOut:
-    album = Album(user_id=current_user.id, name=body.name, description=body.description)
-    db.add(album)
-    await db.flush()
-    return AlbumOut.model_validate(album)
-
-
-@router.get("/{album_id}", response_model=AlbumWithPhotos, summary="Get album with photos")
-async def get_album(
-    album_id: uuid.UUID,
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> AlbumWithPhotos:
-    result = await db.execute(
-        select(Album).where(Album.id == album_id, Album.user_id == current_user.id)
-    )
-    album = result.scalar_one_or_none()
-    if not album:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Album not found.")
-
-    photos_res = await db.execute(
-        select(Photo)
-        .join(AlbumPhoto, AlbumPhoto.photo_id == Photo.id)
-        .where(AlbumPhoto.album_id == album_id, Photo.deleted == False)  # noqa
-    )
-    photos = photos_res.scalars().all()
-    a = AlbumWithPhotos.model_validate(album)
-    a.photos = [_enrich(p) for p in photos]
-    a.photo_count = len(photos)
-    return a
-
-
-@router.patch("/{album_id}", response_model=AlbumOut, summary="Update album metadata")
-async def update_album(
-    album_id: uuid.UUID,
-    body: AlbumUpdate,
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> AlbumOut:
-    result = await db.execute(
-        select(Album).where(Album.id == album_id, Album.user_id == current_user.id)
-    )
-    album = result.scalar_one_or_none()
-    if not album:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Album not found.")
-    if body.name is not None:
-        album.name = body.name
-    if body.description is not None:
-        album.description = body.description
-    if body.cover_photo_id is not None:
-        album.cover_photo_id = body.cover_photo_id
-    return AlbumOut.model_validate(album)
-
-
-@router.delete("/{album_id}", status_code=status.HTTP_204_NO_CONTENT, summary="Delete an album")
-async def delete_album(
-    album_id: uuid.UUID,
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> None:
-    result = await db.execute(
-        select(Album).where(Album.id == album_id, Album.user_id == current_user.id)
-    )
-    album = result.scalar_one_or_none()
-    if not album:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Album not found.")
-    await db.delete(album)
-
-
-@router.post("/{album_id}/photos", status_code=status.HTTP_200_OK, summary="Add photos to album")
-async def add_photos_to_album(
-    album_id: uuid.UUID,
-    body: AddPhotosToAlbumRequest,
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> dict:
-    result = await db.execute(
-        select(Album).where(Album.id == album_id, Album.user_id == current_user.id)
-    )
-    album = result.scalar_one_or_none()
-    if not album:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Album not found.")
-
-    added = 0
-    for photo_id in body.photo_ids:
-        # Verify photo belongs to user
-        p_res = await db.execute(
-            select(Photo).where(Photo.id == photo_id, Photo.user_id == current_user.id)
-        )
-        photo = p_res.scalar_one_or_none()
-        if not photo:
-            continue
-        # Check not already in album
-        ap_res = await db.execute(
-            select(AlbumPhoto).where(AlbumPhoto.album_id == album_id, AlbumPhoto.photo_id == photo_id)
-        )
-        if ap_res.scalar_one_or_none() is None:
-            db.add(AlbumPhoto(album_id=album_id, photo_id=photo_id))
-            added += 1
-
-    return {"added": added, "message": f"Added {added} photo(s) to album."}

backend/app/routers/auth.py

@@ -1,21 +0,0 @@
-"""
-KeyStone – Auth Router
-POST /auth/verify  — validates JWT and returns user profile
-"""
-
-from fastapi import APIRouter
-
-from app.middleware.auth import CurrentUser
-from app.schemas.user import UserOut
-
-router = APIRouter()
-
-
-@router.post("/verify", response_model=UserOut, summary="Verify JWT and return user profile")
-async def verify_token(current_user: CurrentUser) -> UserOut:
-    """
-    Validates the Bearer token (issued by Supabase) and returns the
-    authenticated user's profile. Also auto-creates the user record on
-    first login.
-    """
-    return UserOut.model_validate(current_user)

backend/app/routers/gallery.py

@@ -1,167 +0,0 @@
-"""
-KeyStone – Gallery Router
-GET    /photos          — paginated photo list (cursor-based)
-GET    /photos/{id}     — single photo
-DELETE /photos/{id}     — soft-delete
-PATCH  /photos/{id}/favorite — toggle favorite
-"""
-
-import uuid
-from typing import Annotated, Optional
-
-from fastapi import APIRouter, Depends, HTTPException, Query, status
-from sqlalchemy import select, func, desc
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.middleware.auth import CurrentUser
-from app.models.photo import Photo
-from app.schemas.photo import PhotoOut, PhotoPage, PhotoUpdate
-from app.services.storage import get_download_url
-
-router = APIRouter()
-
-
-def _enrich(photo: Photo) -> PhotoOut:
-    """Convert ORM model to schema, injecting public download URLs."""
-    data = PhotoOut.model_validate(photo)
-    # Rewrite paths to public URLs
-    if photo.bucket_path:
-        data.bucket_path = get_download_url(photo.bucket_path)
-    if photo.thumbnail_path:
-        data.thumbnail_path = get_download_url(photo.thumbnail_path)
-    if photo.preview_path:
-        data.preview_path = get_download_url(photo.preview_path)
-    return data
-
-
-@router.get(
-    "",
-    response_model=PhotoPage,
-    summary="List photos (paginated, newest first)",
-)
-async def list_photos(
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-    limit: int = Query(50, ge=1, le=200),
-    cursor: Optional[str] = Query(None, description="Opaque pagination cursor (photo ID)"),
-    favorites_only: bool = Query(False),
-) -> PhotoPage:
-    """
-    Returns a paginated list of photos for the authenticated user.
-    Uses cursor-based pagination for efficient infinite scroll.
-    """
-    query = (
-        select(Photo)
-        .where(Photo.user_id == current_user.id, Photo.deleted == False)  # noqa
-        .order_by(desc(Photo.uploaded_at))
-    )
-
-    if favorites_only:
-        query = query.where(Photo.is_favorite == True)  # noqa
-
-    if cursor:
-        try:
-            cursor_id = uuid.UUID(cursor)
-            # Get the uploaded_at of the cursor photo
-            cur_res = await db.execute(select(Photo.uploaded_at).where(Photo.id == cursor_id))
-            cursor_time = cur_res.scalar_one_or_none()
-            if cursor_time:
-                query = query.where(Photo.uploaded_at < cursor_time)
-        except (ValueError, Exception):
-            pass  # Invalid cursor – ignore and start from beginning
-
-    result = await db.execute(query.limit(limit + 1))
-    photos = result.scalars().all()
-
-    has_more = len(photos) > limit
-    photos = photos[:limit]
-
-    # Count total (non-deleted) for display
-    count_q = select(func.count()).where(Photo.user_id == current_user.id, Photo.deleted == False)  # noqa
-    total = (await db.execute(count_q)).scalar_one()
-
-    next_cursor = str(photos[-1].id) if has_more and photos else None
-
-    return PhotoPage(
-        items=[_enrich(p) for p in photos],
-        total=total,
-        next_cursor=next_cursor,
-        has_more=has_more,
-    )
-
-
-@router.get(
-    "/{photo_id}",
-    response_model=PhotoOut,
-    summary="Get a single photo by ID",
-)
-async def get_photo(
-    photo_id: uuid.UUID,
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> PhotoOut:
-    result = await db.execute(
-        select(Photo).where(
-            Photo.id == photo_id,
-            Photo.user_id == current_user.id,
-            Photo.deleted == False,  # noqa
-        )
-    )
-    photo = result.scalar_one_or_none()
-    if not photo:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Photo not found.")
-    return _enrich(photo)
-
-
-@router.delete(
-    "/{photo_id}",
-    status_code=status.HTTP_204_NO_CONTENT,
-    summary="Soft-delete a photo",
-)
-async def delete_photo(
-    photo_id: uuid.UUID,
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> None:
-    result = await db.execute(
-        select(Photo).where(Photo.id == photo_id, Photo.user_id == current_user.id)
-    )
-    photo = result.scalar_one_or_none()
-    if not photo:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Photo not found.")
-    photo.deleted = True
-
-
-@router.patch(
-    "/{photo_id}",
-    response_model=PhotoOut,
-    summary="Update photo metadata (favorite, etc.)",
-)
-async def update_photo(
-    photo_id: uuid.UUID,
-    body: PhotoUpdate,
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> PhotoOut:
-    result = await db.execute(
-        select(Photo).where(
-            Photo.id == photo_id,
-            Photo.user_id == current_user.id,
-            Photo.deleted == False,  # noqa
-        )
-    )
-    photo = result.scalar_one_or_none()
-    if not photo:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Photo not found.")
-
-    if body.is_favorite is not None:
-        photo.is_favorite = body.is_favorite
-    if body.deleted is not None:
-        photo.deleted = body.deleted
-    if body.ai_description is not None:
-        photo.ai_description = body.ai_description
-    if body.ai_tags is not None:
-        photo.ai_tags = body.ai_tags
-
-    return _enrich(photo)

backend/app/routers/search.py

@@ -1,67 +0,0 @@
-"""
-KeyStone – Search Router
-GET /search?q=  — text search across photos (AI-ready, text-based initially)
-"""
-
-from typing import Annotated, Optional
-
-from fastapi import APIRouter, Depends, Query
-from sqlalchemy import select, or_
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.middleware.auth import CurrentUser
-from app.models.photo import Photo
-from app.schemas.photo import PhotoPage
-from app.routers.gallery import _enrich
-
-router = APIRouter()
-
-
-@router.get("", response_model=PhotoPage, summary="Search photos by filename or AI tags")
-async def search_photos(
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-    q: str = Query(..., min_length=1, description="Search query"),
-    limit: int = Query(50, ge=1, le=200),
-    offset: int = Query(0, ge=0),
-) -> PhotoPage:
-    """
-    Text-based search across:
-    - filename
-    - ai_description
-    - ai_tags
-
-    CLIP-based semantic search will be added in Milestone 8 using the
-    clip_embedding column.
-    """
-    search_term = f"%{q.lower()}%"
-
-    query = (
-        select(Photo)
-        .where(
-            Photo.user_id == current_user.id,
-            Photo.deleted == False,  # noqa
-            or_(
-                Photo.filename.ilike(search_term),
-                Photo.ai_description.ilike(search_term),
-                Photo.ai_tags.ilike(search_term),
-            ),
-        )
-        .order_by(Photo.uploaded_at.desc())
-        .offset(offset)
-        .limit(limit + 1)
-    )
-
-    result = await db.execute(query)
-    photos = result.scalars().all()
-
-    has_more = len(photos) > limit
-    photos = photos[:limit]
-
-    return PhotoPage(
-        items=[_enrich(p) for p in photos],
-        total=len(photos),
-        next_cursor=None,
-        has_more=has_more,
-    )

backend/app/routers/sync.py

@@ -1,96 +0,0 @@
-"""
-KeyStone – Sync Router
-POST /sync/start  — register / update a device
-POST /sync/check  — check which hashes need uploading
-"""
-
-import logging
-from datetime import datetime, timezone
-from typing import Annotated
-
-from fastapi import APIRouter, Depends, status
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.database import get_db
-from app.middleware.auth import CurrentUser
-from app.models.device import Device
-from app.schemas.sync import (
-    SyncCheckRequest, SyncCheckResponse,
-    SyncStartRequest, SyncStartResponse,
-)
-from app.services.dedup import filter_missing_hashes
-
-logger = logging.getLogger(__name__)
-router = APIRouter()
-
-
-@router.post(
-    "/start",
-    response_model=SyncStartResponse,
-    status_code=status.HTTP_200_OK,
-    summary="Register or update a device for sync",
-)
-async def sync_start(
-    body: SyncStartRequest,
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> SyncStartResponse:
-    """
-    Register a device (or update its last_sync timestamp).
-    Called once at app launch before beginning a sync session.
-    """
-    # Find existing device by name + platform for this user
-    result = await db.execute(
-        select(Device).where(
-            Device.user_id == current_user.id,
-            Device.device_name == body.device_name,
-            Device.platform == body.platform,
-        )
-    )
-    device = result.scalar_one_or_none()
-
-    if device is None:
-        device = Device(
-            user_id=current_user.id,
-            device_name=body.device_name,
-            platform=body.platform,
-            device_token=body.device_token,
-        )
-        db.add(device)
-        await db.flush()
-        logger.info("Registered new device: %s (%s)", body.device_name, body.platform)
-    else:
-        device.last_sync = datetime.now(timezone.utc)
-        if body.device_token:
-            device.device_token = body.device_token
-
-    return SyncStartResponse(
-        device_id=device.id,
-        message="Device registered. Ready to sync.",
-        last_sync=device.last_sync,
-    )
-
-
-@router.post(
-    "/check",
-    response_model=SyncCheckResponse,
-    status_code=status.HTTP_200_OK,
-    summary="Check which photo hashes need uploading",
-)
-async def sync_check(
-    body: SyncCheckRequest,
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-) -> SyncCheckResponse:
-    """
-    Accepts a list of SHA256 hashes from the client's camera roll.
-    Returns only the hashes the server does NOT already have.
-    This enables the mobile client to skip uploading duplicates.
-    """
-    missing = await filter_missing_hashes(db, current_user.id, body.hashes)
-    return SyncCheckResponse(
-        missing_hashes=missing,
-        existing_count=len(body.hashes) - len(missing),
-        missing_count=len(missing),
-    )

backend/app/routers/upload.py

@@ -1,208 +0,0 @@
-"""
-KeyStone – Upload Router
-POST /upload        — single file upload
-POST /upload/batch  — batch metadata check (actual bytes uploaded per-file)
-"""
-
-import logging
-import uuid
-from datetime import datetime, timezone
-from typing import Annotated
-
-from fastapi import APIRouter, BackgroundTasks, Depends, File, Form, HTTPException, Request, UploadFile, status
-from slowapi import Limiter
-from slowapi.util import get_remote_address
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.config import get_settings
-from app.database import get_db
-from app.middleware.auth import CurrentUser
-from app.models.photo import Photo
-from app.models.upload_job import UploadJob, UploadStatus
-from app.schemas.upload import UploadResponse
-from app.services import dedup as dedup_svc
-from app.services import storage as storage_svc
-from app.services import thumbnail as thumb_svc
-
-logger = logging.getLogger(__name__)
-settings = get_settings()
-limiter = Limiter(key_func=get_remote_address)
-
-router = APIRouter()
-
-ALLOWED_MIME_TYPES = set(settings.allowed_mime_types)
-
-
-def _validate_file(file: UploadFile, file_bytes: bytes) -> None:
-    """Validate MIME type and file size."""
-    if file.content_type not in ALLOWED_MIME_TYPES:
-        raise HTTPException(
-            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
-            detail=f"Unsupported file type: {file.content_type}",
-        )
-    if len(file_bytes) > settings.max_upload_size_bytes:
-        raise HTTPException(
-            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
-            detail=f"File too large. Maximum size is {settings.max_upload_size_mb} MB.",
-        )
-
-
-async def _process_upload_background(
-    photo_id: uuid.UUID,
-    job_id: uuid.UUID,
-    file_bytes: bytes,
-    filename: str,
-    mime_type: str,
-    user_id: uuid.UUID,
-    sha256: str,
-    taken_at_str: str | None,
-    db: AsyncSession,
-) -> None:
-    """Background task: generate thumbnail and update photo record."""
-    try:
-        # Generate thumbnail
-        thumb_bytes, width, height = thumb_svc.generate_thumbnail(file_bytes)
-        thumb_path = await storage_svc.upload_thumbnail(thumb_bytes, user_id, photo_id)
-
-        # Update photo record
-        from sqlalchemy import select
-        result = await db.execute(select(Photo).where(Photo.id == photo_id))
-        photo = result.scalar_one_or_none()
-        if photo:
-            photo.thumbnail_path = thumb_path
-            photo.width = width
-            photo.height = height
-            await db.commit()
-
-        # Mark job complete
-        result = await db.execute(select(UploadJob).where(UploadJob.id == job_id))
-        job = result.scalar_one_or_none()
-        if job:
-            job.status = UploadStatus.COMPLETED
-            job.completed_at = datetime.now(timezone.utc)
-            await db.commit()
-
-    except Exception as exc:
-        logger.error("Background processing failed for photo %s: %s", photo_id, exc)
-        from sqlalchemy import select
-        result = await db.execute(select(UploadJob).where(UploadJob.id == job_id))
-        job = result.scalar_one_or_none()
-        if job:
-            job.status = UploadStatus.FAILED
-            job.error_message = str(exc)
-            job.retries += 1
-            await db.commit()
-
-
-@router.post(
-    "",
-    response_model=UploadResponse,
-    status_code=status.HTTP_201_CREATED,
-    summary="Upload a single photo",
-)
-@limiter.limit(f"{settings.rate_limit_uploads_per_minute}/minute")
-async def upload_photo(
-    request: Request,
-    background_tasks: BackgroundTasks,
-    current_user: CurrentUser,
-    db: Annotated[AsyncSession, Depends(get_db)],
-    file: UploadFile = File(..., description="The photo file to upload"),
-    sha256: str = Form(..., description="SHA256 hash of the file for integrity check"),
-    taken_at: str | None = Form(None, description="ISO 8601 timestamp when photo was taken"),
-) -> UploadResponse:
-    """
-    Upload a single photo file.
-
-    - Validates MIME type and file size
-    - Checks for duplicate SHA256 hash
-    - Stores original in HF Bucket
-    - Generates thumbnail in background
-    - Returns immediately with job ID
-    """
-    file_bytes = await file.read()
-    _validate_file(file, file_bytes)
-
-    # Verify SHA256 integrity
-    computed = dedup_svc.compute_sha256(file_bytes)
-    if computed != sha256:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="SHA256 mismatch – file may be corrupted.",
-        )
-
-    # Check for duplicate
-    existing = await dedup_svc.is_duplicate(db, current_user.id, sha256)
-    if existing:
-        return UploadResponse(
-            job_id=uuid.uuid4(),
-            photo_id=existing.id,
-            status=UploadStatus.DUPLICATE,
-            duplicate=True,
-            message="Photo already uploaded (duplicate SHA256).",
-        )
-
-    # Upload original to HF Bucket
-    photo_id = uuid.uuid4()
-    try:
-        bucket_path = await storage_svc.upload_original(
-            file_bytes, file.filename or "photo.jpg",
-            file.content_type or "image/jpeg",
-            current_user.id, photo_id,
-        )
-    except Exception as exc:
-        raise HTTPException(
-            status_code=status.HTTP_502_BAD_GATEWAY,
-            detail=f"Storage upload failed: {exc}",
-        )
-
-    # Get image dimensions
-    dims = thumb_svc.get_image_dimensions(file_bytes)
-    width, height = (dims if dims else (None, None))
-
-    # Create Photo record
-    photo = Photo(
-        id=photo_id,
-        user_id=current_user.id,
-        sha256=sha256,
-        filename=file.filename or "photo.jpg",
-        mime_type=file.content_type or "image/jpeg",
-        bucket_path=bucket_path,
-        size=len(file_bytes),
-        width=width,
-        height=height,
-        taken_at=datetime.fromisoformat(taken_at) if taken_at else None,
-    )
-    db.add(photo)
-
-    # Create UploadJob record
-    job = UploadJob(
-        user_id=current_user.id,
-        photo_id=photo_id,
-        filename=file.filename or "photo.jpg",
-        sha256=sha256,
-        status=UploadStatus.PROCESSING,
-    )
-    db.add(job)
-    await db.flush()
-
-    # Queue background thumbnail generation
-    background_tasks.add_task(
-        _process_upload_background,
-        photo_id=photo_id,
-        job_id=job.id,
-        file_bytes=file_bytes,
-        filename=file.filename or "photo.jpg",
-        mime_type=file.content_type or "image/jpeg",
-        user_id=current_user.id,
-        sha256=sha256,
-        taken_at_str=taken_at,
-        db=db,
-    )
-
-    return UploadResponse(
-        job_id=job.id,
-        photo_id=photo_id,
-        status=UploadStatus.PROCESSING,
-        duplicate=False,
-        message="Upload successful. Thumbnail being generated.",
-    )

backend/app/schemas/__init__.py

@@ -1,17 +0,0 @@
-"""
-KeyStone – Pydantic Schemas Package
-"""
-
-from app.schemas.user import UserOut, UserCreate
-from app.schemas.photo import PhotoOut, PhotoCreate, PhotoUpdate, PhotoPage
-from app.schemas.upload import UploadResponse, BatchUploadRequest, BatchUploadResponse
-from app.schemas.album import AlbumOut, AlbumCreate, AlbumUpdate
-from app.schemas.sync import SyncCheckRequest, SyncCheckResponse, SyncStartRequest, SyncStartResponse
-
-__all__ = [
-    "UserOut", "UserCreate",
-    "PhotoOut", "PhotoCreate", "PhotoUpdate", "PhotoPage",
-    "UploadResponse", "BatchUploadRequest", "BatchUploadResponse",
-    "AlbumOut", "AlbumCreate", "AlbumUpdate",
-    "SyncCheckRequest", "SyncCheckResponse", "SyncStartRequest", "SyncStartResponse",
-]

backend/app/schemas/album.py

@@ -1,42 +0,0 @@
-"""
-KeyStone – Album Schemas
-"""
-
-import uuid
-from datetime import datetime
-from typing import Optional
-from pydantic import BaseModel
-
-from app.schemas.photo import PhotoOut
-
-
-class AlbumCreate(BaseModel):
-    name: str
-    description: Optional[str] = None
-
-
-class AlbumUpdate(BaseModel):
-    name: Optional[str] = None
-    description: Optional[str] = None
-    cover_photo_id: Optional[uuid.UUID] = None
-
-
-class AlbumOut(BaseModel):
-    model_config = {"from_attributes": True}
-
-    id: uuid.UUID
-    user_id: uuid.UUID
-    name: str
-    description: Optional[str]
-    cover_photo_id: Optional[uuid.UUID]
-    created_at: datetime
-    updated_at: datetime
-    photo_count: int = 0
-
-
-class AlbumWithPhotos(AlbumOut):
-    photos: list[PhotoOut] = []
-
-
-class AddPhotosToAlbumRequest(BaseModel):
-    photo_ids: list[uuid.UUID]

backend/app/schemas/photo.py

@@ -1,59 +0,0 @@
-"""
-KeyStone – Photo Schemas
-"""
-
-import uuid
-from datetime import datetime
-from typing import Optional
-from pydantic import BaseModel
-
-
-class PhotoCreate(BaseModel):
-    sha256: str
-    filename: str
-    mime_type: str
-    bucket_path: str
-    thumbnail_path: Optional[str] = None
-    preview_path: Optional[str] = None
-    width: Optional[int] = None
-    height: Optional[int] = None
-    size: int
-    taken_at: Optional[datetime] = None
-
-
-class PhotoUpdate(BaseModel):
-    is_favorite: Optional[bool] = None
-    deleted: Optional[bool] = None
-    ai_description: Optional[str] = None
-    ai_tags: Optional[str] = None
-
-
-class PhotoOut(BaseModel):
-    model_config = {"from_attributes": True}
-
-    id: uuid.UUID
-    user_id: uuid.UUID
-    sha256: str
-    filename: str
-    mime_type: str
-    bucket_path: str
-    thumbnail_path: Optional[str]
-    preview_path: Optional[str]
-    width: Optional[int]
-    height: Optional[int]
-    size: int
-    taken_at: Optional[datetime]
-    created_at: datetime
-    uploaded_at: datetime
-    deleted: bool
-    is_favorite: bool
-    ai_description: Optional[str]
-    ai_tags: Optional[str]
-
-
-class PhotoPage(BaseModel):
-    """Paginated list of photos."""
-    items: list[PhotoOut]
-    total: int
-    next_cursor: Optional[str] = None
-    has_more: bool

backend/app/schemas/sync.py

@@ -1,33 +0,0 @@
-"""
-KeyStone – Sync Schemas
-"""
-
-import uuid
-from datetime import datetime
-from typing import Optional
-from pydantic import BaseModel
-
-
-class SyncCheckRequest(BaseModel):
-    """Client sends an array of SHA256 hashes; server replies with which are missing."""
-    hashes: list[str]
-    device_id: Optional[str] = None
-
-
-class SyncCheckResponse(BaseModel):
-    """Hashes that the server does NOT have yet (need uploading)."""
-    missing_hashes: list[str]
-    existing_count: int
-    missing_count: int
-
-
-class SyncStartRequest(BaseModel):
-    device_name: str
-    platform: str  # android | ios | web
-    device_token: Optional[str] = None
-
-
-class SyncStartResponse(BaseModel):
-    device_id: uuid.UUID
-    message: str
-    last_sync: Optional[datetime]

backend/app/schemas/upload.py

@@ -1,43 +0,0 @@
-"""
-KeyStone – Upload Schemas
-"""
-
-import uuid
-from datetime import datetime
-from typing import Optional
-from pydantic import BaseModel
-
-from app.models.upload_job import UploadStatus
-
-
-class UploadResponse(BaseModel):
-    """Returned after a successful upload."""
-    job_id: uuid.UUID
-    photo_id: Optional[uuid.UUID]
-    status: UploadStatus
-    duplicate: bool
-    message: str
-
-
-class BatchUploadItem(BaseModel):
-    sha256: str
-    filename: str
-
-
-class BatchUploadRequest(BaseModel):
-    files: list[BatchUploadItem]
-
-
-class BatchUploadResponseItem(BaseModel):
-    sha256: str
-    filename: str
-    status: UploadStatus
-    photo_id: Optional[uuid.UUID]
-    duplicate: bool
-
-
-class BatchUploadResponse(BaseModel):
-    results: list[BatchUploadResponseItem]
-    uploaded: int
-    skipped: int
-    failed: int

backend/app/schemas/user.py

@@ -1,22 +0,0 @@
-"""
-KeyStone – User Schemas
-"""
-
-import uuid
-from datetime import datetime
-from pydantic import BaseModel, EmailStr
-
-
-class UserCreate(BaseModel):
-    supabase_id: str
-    email: EmailStr
-
-
-class UserOut(BaseModel):
-    model_config = {"from_attributes": True}
-
-    id: uuid.UUID
-    supabase_id: str
-    email: str
-    created_at: datetime
-    is_active: bool

backend/app/services/__init__.py

@@ -1 +0,0 @@
-"""KeyStone – Services Package"""

backend/app/services/ai.py

@@ -1,120 +0,0 @@
-"""
-KeyStone – AI Services (Milestone 8 Scaffold)
-
-This module provides stub interfaces for all planned AI features.
-Each function is wired to FastAPI BackgroundTasks and ready to be
-filled with real model calls (CLIP, Tesseract, face_recognition, etc.).
-"""
-
-import logging
-from typing import Optional
-
-logger = logging.getLogger(__name__)
-
-
-async def generate_clip_embedding(image_bytes: bytes) -> Optional[list[float]]:
-    """
-    Generate a CLIP embedding vector for semantic image search.
-
-    TODO: Implement with:
-        from transformers import CLIPProcessor, CLIPModel
-        model = CLIPModel.from_pretrained("openai/clip-vit-base-patch32")
-        processor = CLIPProcessor.from_pretrained("openai/clip-vit-base-patch32")
-    """
-    logger.info("[AI] CLIP embedding requested (not yet implemented)")
-    return None
-
-
-async def run_ocr(image_bytes: bytes) -> Optional[str]:
-    """
-    Extract text from image using OCR.
-
-    TODO: Implement with pytesseract or easyocr:
-        import pytesseract
-        from PIL import Image
-        import io
-        img = Image.open(io.BytesIO(image_bytes))
-        return pytesseract.image_to_string(img)
-    """
-    logger.info("[AI] OCR requested (not yet implemented)")
-    return None
-
-
-async def detect_blur(image_bytes: bytes) -> Optional[float]:
-    """
-    Return a blur score (higher = sharper). Blur detection using Laplacian variance.
-
-    TODO: Implement with OpenCV:
-        import cv2
-        import numpy as np
-        arr = np.frombuffer(image_bytes, np.uint8)
-        img = cv2.imdecode(arr, cv2.IMREAD_GRAYSCALE)
-        return float(cv2.Laplacian(img, cv2.CV_64F).var())
-    """
-    logger.info("[AI] Blur detection requested (not yet implemented)")
-    return None
-
-
-async def generate_description(image_bytes: bytes) -> Optional[str]:
-    """
-    Generate a natural-language description for the photo.
-
-    TODO: Implement with a BLIP or LLaVA model:
-        from transformers import BlipProcessor, BlipForConditionalGeneration
-    """
-    logger.info("[AI] Description generation requested (not yet implemented)")
-    return None
-
-
-async def detect_faces(image_bytes: bytes) -> Optional[list[dict]]:
-    """
-    Detect and encode faces for clustering.
-
-    TODO: Implement with face_recognition or deepface:
-        import face_recognition
-        img = face_recognition.load_image_file(io.BytesIO(image_bytes))
-        return face_recognition.face_locations(img)
-    """
-    logger.info("[AI] Face detection requested (not yet implemented)")
-    return None
-
-
-async def auto_tag(image_bytes: bytes) -> list[str]:
-    """
-    Generate tags for the photo (objects, scene, etc.).
-
-    TODO: Implement with CLIP zero-shot classification:
-        candidate_labels = ["beach", "mountain", "food", "people", ...]
-    """
-    logger.info("[AI] Auto-tagging requested (not yet implemented)")
-    return []
-
-
-async def process_photo_ai(photo_id: str, image_bytes: bytes) -> dict:
-    """
-    Run the full AI processing pipeline on a photo.
-    Called as a background task after successful upload.
-
-    Returns a dict of all AI results to be stored in the Photo record.
-    """
-    results = {}
-
-    description = await generate_description(image_bytes)
-    if description:
-        results["ai_description"] = description
-
-    tags = await auto_tag(image_bytes)
-    if tags:
-        import json
-        results["ai_tags"] = json.dumps(tags)
-
-    embedding = await generate_clip_embedding(image_bytes)
-    if embedding:
-        import json
-        results["clip_embedding"] = json.dumps(embedding)
-
-    blur_score = await detect_blur(image_bytes)
-    if blur_score is not None:
-        logger.info("[AI] Photo %s blur score: %.2f", photo_id, blur_score)
-
-    return results

backend/app/services/dedup.py

@@ -1,63 +0,0 @@
-"""
-KeyStone – Deduplication Service
-Checks SHA256 hashes against existing photos to prevent duplicate uploads.
-"""
-
-import hashlib
-import logging
-import uuid
-from typing import Optional
-
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.models.photo import Photo
-
-logger = logging.getLogger(__name__)
-
-
-async def is_duplicate(
-    db: AsyncSession,
-    user_id: uuid.UUID,
-    sha256: str,
-) -> Optional[Photo]:
-    """
-    Check if a photo with the given SHA256 hash already exists for this user.
-    Returns the existing Photo if found, else None.
-    """
-    result = await db.execute(
-        select(Photo).where(
-            Photo.user_id == user_id,
-            Photo.sha256 == sha256,
-            Photo.deleted == False,  # noqa: E712
-        )
-    )
-    return result.scalar_one_or_none()
-
-
-async def filter_missing_hashes(
-    db: AsyncSession,
-    user_id: uuid.UUID,
-    hashes: list[str],
-) -> list[str]:
-    """
-    Given a list of SHA256 hashes, return only the ones NOT already stored
-    for this user. Used by the sync check endpoint.
-    """
-    if not hashes:
-        return []
-
-    result = await db.execute(
-        select(Photo.sha256).where(
-            Photo.user_id == user_id,
-            Photo.sha256.in_(hashes),
-            Photo.deleted == False,  # noqa: E712
-        )
-    )
-    existing_hashes = {row[0] for row in result.fetchall()}
-    return [h for h in hashes if h not in existing_hashes]
-
-
-def compute_sha256(data: bytes) -> str:
-    """Compute SHA256 hash of raw bytes."""
-    return hashlib.sha256(data).hexdigest()

backend/app/services/storage.py

@@ -1,131 +0,0 @@
-"""
-KeyStone – Storage Service
-Handles uploads to Hugging Face Dataset repository (S3-compatible).
-"""
-
-import io
-import logging
-import uuid
-from pathlib import PurePosixPath
-
-import boto3
-from botocore.config import Config
-from botocore.exceptions import BotoCoreError, ClientError
-
-from app.config import get_settings
-
-logger = logging.getLogger(__name__)
-settings = get_settings()
-
-
-def _get_s3_client():
-    """Create a boto3 S3 client pointed at Hugging Face's S3-compatible endpoint."""
-    return boto3.client(
-        "s3",
-        endpoint_url=f"https://huggingface.co/datasets/{settings.hf_dataset_repo}/resolve/main",
-        aws_access_key_id=settings.hf_token,
-        aws_secret_access_key=settings.hf_token,
-        config=Config(signature_version="v4"),
-        region_name="us-east-1",
-    )
-
-
-def _get_hf_client():
-    """Hugging Face Hub client for file uploads."""
-    try:
-        from huggingface_hub import HfApi
-        return HfApi(token=settings.hf_token)
-    except ImportError:
-        raise RuntimeError("huggingface_hub package is required for storage.")
-
-
-def _originals_path(user_id: str, photo_id: str, filename: str) -> str:
-    ext = PurePosixPath(filename).suffix.lower()
-    return f"dpv007/kystn/data/originals/{user_id}/{photo_id}{ext}"
-
-
-def _thumbnails_path(user_id: str, photo_id: str) -> str:
-    return f"dpv007/kystn/data/thumbnails/{user_id}/{photo_id}.jpg"
-
-
-def _previews_path(user_id: str, photo_id: str) -> str:
-    return f"dpv007/kystn/data/previews/{user_id}/{photo_id}.jpg"
-
-
-async def upload_original(
-    file_bytes: bytes,
-    filename: str,
-    mime_type: str,
-    user_id: uuid.UUID,
-    photo_id: uuid.UUID,
-) -> str:
-    """
-    Upload the original photo file to HF Dataset repository.
-    Returns the bucket path (relative key).
-    """
-    api = _get_hf_client()
-    path = _originals_path(str(user_id), str(photo_id), filename)
-
-    try:
-        api.upload_file(
-            path_or_fileobj=io.BytesIO(file_bytes),
-            path_in_repo=path,
-            repo_id=settings.hf_dataset_repo,
-            repo_type="dataset",
-            token=settings.hf_token,
-        )
-        logger.info("Uploaded original: %s", path)
-        return path
-    except Exception as exc:
-        logger.error("Failed to upload original %s: %s", filename, exc)
-        raise RuntimeError(f"Storage upload failed: {exc}") from exc
-
-
-async def upload_thumbnail(
-    thumbnail_bytes: bytes,
-    user_id: uuid.UUID,
-    photo_id: uuid.UUID,
-) -> str:
-    """Upload thumbnail to HF Dataset repository. Returns the bucket path."""
-    api = _get_hf_client()
-    path = _thumbnails_path(str(user_id), str(photo_id))
-
-    try:
-        api.upload_file(
-            path_or_fileobj=io.BytesIO(thumbnail_bytes),
-            path_in_repo=path,
-            repo_id=settings.hf_dataset_repo,
-            repo_type="dataset",
-            token=settings.hf_token,
-        )
-        logger.info("Uploaded thumbnail: %s", path)
-        return path
-    except Exception as exc:
-        logger.error("Failed to upload thumbnail: %s", exc)
-        raise RuntimeError(f"Thumbnail upload failed: {exc}") from exc
-
-
-def get_download_url(bucket_path: str) -> str:
-    """
-    Build a public download URL for a file in the HF Dataset repo.
-    Format: https://huggingface.co/datasets/{repo}/resolve/main/{path}
-    """
-    return (
-        f"https://huggingface.co/datasets/{settings.hf_dataset_repo}"
-        f"/resolve/main/{bucket_path}"
-    )
-
-
-async def delete_file(bucket_path: str) -> None:
-    """Delete a file from the HF Dataset repository."""
-    api = _get_hf_client()
-    try:
-        api.delete_file(
-            path_in_repo=bucket_path,
-            repo_id=settings.hf_dataset_repo,
-            repo_type="dataset",
-            token=settings.hf_token,
-        )
-        logger.info("Deleted file: %s", bucket_path)
-    except Exception as exc:
-        logger.warning("Failed to delete %s: %s", bucket_path, exc)

backend/app/services/thumbnail.py

@@ -1,77 +0,0 @@
-"""
-KeyStone – Thumbnail Generation Service
-Uses Pillow to generate resized JPEG thumbnails and previews.
-"""
-
-import io
-import logging
-from typing import Optional, Tuple
-
-from PIL import Image, ImageOps
-
-from app.config import get_settings
-
-logger = logging.getLogger(__name__)
-settings = get_settings()
-
-
-def _open_image(file_bytes: bytes) -> Image.Image:
-    img = Image.open(io.BytesIO(file_bytes))
-    # Auto-rotate based on EXIF orientation
-    img = ImageOps.exif_transpose(img)
-    # Convert to RGB (handles RGBA, palette, etc.)
-    if img.mode not in ("RGB", "L"):
-        img = img.convert("RGB")
-    return img
-
-
-def generate_thumbnail(
-    file_bytes: bytes,
-    size: int = 0,
-    quality: int = 0,
-) -> Tuple[bytes, int, int]:
-    """
-    Generate a square-cropped thumbnail.
-
-    Returns:
-        (jpeg_bytes, width, height) of the *original* image dimensions.
-    """
-    size = size or settings.thumbnail_size
-    quality = quality or settings.thumbnail_quality
-
-    img = _open_image(file_bytes)
-    orig_width, orig_height = img.size
-
-    # Thumbnail (preserves aspect ratio, fits within size×size)
-    thumb = img.copy()
-    thumb.thumbnail((size, size), Image.LANCZOS)
-
-    buf = io.BytesIO()
-    thumb.save(buf, format="JPEG", quality=quality, optimize=True)
-    return buf.getvalue(), orig_width, orig_height
-
-
-def generate_preview(
-    file_bytes: bytes,
-    max_dimension: int = 1920,
-    quality: int = 80,
-) -> bytes:
-    """
-    Generate a full-resolution preview (max 1920px on the long edge, JPEG).
-    Used for the lightbox view in the gallery.
-    """
-    img = _open_image(file_bytes)
-    img.thumbnail((max_dimension, max_dimension), Image.LANCZOS)
-    buf = io.BytesIO()
-    img.save(buf, format="JPEG", quality=quality, optimize=True)
-    return buf.getvalue()
-
-
-def get_image_dimensions(file_bytes: bytes) -> Optional[Tuple[int, int]]:
-    """Return (width, height) of image without fully decoding it."""
-    try:
-        img = Image.open(io.BytesIO(file_bytes))
-        return img.size
-    except Exception as exc:
-        logger.warning("Could not read image dimensions: %s", exc)
-        return None

backend/pytest.ini

@@ -1,3 +0,0 @@
-[pytest]
-asyncio_mode = auto
-testpaths = tests

backend/requirements.txt

@@ -1,38 +0,0 @@
-# ── Web Framework ─────────────────────────────────────────────────────────────
-fastapi==0.115.6
-uvicorn[standard]==0.32.1
-python-multipart==0.0.20
-
-# ── Database ──────────────────────────────────────────────────────────────────
-sqlalchemy[asyncio]==2.0.36
-asyncpg==0.30.0
-alembic==1.14.0
-
-# ── Configuration ─────────────────────────────────────────────────────────────
-pydantic
-email-validator==2.3.0
-pydantic-settings==2.7.0
-python-dotenv==1.0.1
-
-# ── Authentication ────────────────────────────────────────────────────────────
-python-jose[cryptography]==3.3.0
-httpx==0.28.1
-
-# ── Storage (S3-compatible / Hugging Face) ────────────────────────────────────
-boto3==1.35.88
-huggingface_hub==0.27.0
-
-# ── Image Processing ──────────────────────────────────────────────────────────
-Pillow==11.1.0
-
-# ── Rate Limiting ─────────────────────────────────────────────────────────────
-slowapi==0.1.9
-
-# ── Utilities ─────────────────────────────────────────────────────────────────
-python-magic==0.4.27
-aiofiles==24.1.0
-
-# ── Testing ───────────────────────────────────────────────────────────────────
-pytest==8.3.4
-pytest-asyncio==0.25.2
-httpx==0.28.1

backend/tests/__init__.py

@@ -1 +0,0 @@
-"""KeyStone – Tests Package"""

backend/tests/test_health.py

@@ -1,36 +0,0 @@
-"""
-KeyStone – Health Endpoint Tests
-"""
-
-import pytest
-from httpx import AsyncClient, ASGITransport
-
-
-@pytest.mark.asyncio
-async def test_health_endpoint():
-    """Health endpoint should return 200 with status=ok."""
-    from app.main import app
-
-    async with AsyncClient(
-        transport=ASGITransport(app=app), base_url="http://test"
-    ) as client:
-        response = await client.get("/health")
-
-    assert response.status_code == 200
-    data = response.json()
-    assert data["status"] == "ok"
-    assert "version" in data
-    assert "service" in data
-
-
-@pytest.mark.asyncio
-async def test_docs_available():
-    """Swagger docs should be accessible."""
-    from app.main import app
-
-    async with AsyncClient(
-        transport=ASGITransport(app=app), base_url="http://test"
-    ) as client:
-        response = await client.get("/docs")
-
-    assert response.status_code == 200