📸 PhotoFinder V2 — Enterprise Lens

Find any face. Find any object. Across millions of photos. In milliseconds.

PhotoFinder V2 (Enterprise Lens) is a production-grade visual search platform. Upload your photo library once, and from then on you can search it by face, by object, or by scene — using nothing but a query image. It's built for event photographers, archivists, and anyone drowning in a photo library that's too large for human eyes.

The system runs a two-lane AI pipeline — faces go through ArcFace + AdaFace (512-D embeddings, fused for accuracy), objects go through SigLIP + DINOv2 + YOLOv11-seg. Vectors live in Pinecone, images live in Cloudinary, identity clusters live in Supabase, and the whole stack is wired up so users bring their own keys (BYOK) — no central data lake, no privacy compromise.

---

🌐 Live Demo & Links

---

👋 About the Author

Hi, I'm Adarsh — the engineer behind Enterprise Lens. I built this project to push two-lane biometric retrieval onto a free-tier infra stack and prove it can hold its own against far more expensive setups.

---

✨ What It Does

• Face Search — Upload a face photo, get every image of that person from your library back, sorted by similarity. Multi-angle search lets you upload front/left/right shots and fuses the embeddings server-side for one super-accurate query.
• Object Search — Find every photo containing a red sedan, a Labrador, a guitar, etc., using a query image of the object.
• People View — HDBSCAN automatically clusters your library by identity. You get an "album per person" view; rename clusters ("Mom", "Sarah") and they stick.
• File Explorer — Browse and manage your Cloudinary library by folder/category. Lightbox preview, scroll-to-zoom, click-to-close.
• Bring Your Own Keys — Users sign in with Google (Supabase Auth) and provide their own Pinecone + Cloudinary credentials. The backend never stores your photos or vectors centrally.
• Admin Panel — Privileged users get a system-wide dashboard for monitoring uploads, jobs, and logs.
• Blog & Docs — In-app engineering blog explaining design decisions (two-lane architecture, FAISS → Pinecone migration, sub-10ms latency at 50M vectors).

---

🏗 Architecture

┌─────────────────────────────────┐         ┌──────────────────────────────────┐
│   Frontend  (React 19 + Vite)   │         │       Backend  (FastAPI)         │
│                                 │  HTTPS  │                                  │
│   • Hosted on Vercel            │ ──────► │   • Hosted on Hugging Face Spaces│
│   • Source on GitLab            │  CORS   │   • Docker image (Python 3.10)   │
│   • Supabase Auth (Google PKCE) │         │   • CPU-only inference (2 vCPU)  │
└─────────────────────────────────┘         └──────────────────────────────────┘
                                                          │
                ┌─────────────────────────────────────────┼──────────────────────────────────────┐
                │                                         │                                      │
                ▼                                         ▼                                      ▼
    ┌────────────────────┐                  ┌────────────────────────┐               ┌────────────────────┐
    │  AI Models (CPU)   │                  │  Vector DB — Pinecone  │               │  Object Storage    │
    │                    │                  │                        │               │  Cloudinary CDN    │
    │  • SCRFD detector  │                  │  • faces-arcface (512) │               │                    │
    │  • ArcFace-R100    │                  │  • faces-adaface (512) │               │  • Image hosting   │
    │  • AdaFace         │                  │  • enterprise-objects  │               │  • Auto thumbnails │
    │  • SigLIP-B/16     │                  │    (fused 768-D)       │               │  • Folder browsing │
    │  • DINOv2-base     │                  │  Per-user keys (BYOK)  │               │  Per-user URL      │
    │  • YOLOv11-seg     │                  └────────────────────────┘               └────────────────────┘
    │  ONNX-quantised    │
    └────────────────────┘                  ┌────────────────────────┐               ┌────────────────────┐
                                            │  Supabase (Postgres)   │               │  Upstash Redis     │
                                            │                        │               │                    │
                                            │  • user_settings       │               │  • Job queue       │
                                            │  • face_clusters       │               │  • Inference cache │
                                            │    (HDBSCAN output)    │               │  • Rate limiting   │
                                            │  • Auth + admin flags  │               │  REST API (HTTP)   │
                                            └────────────────────────┘               └────────────────────┘

Two-Lane Inference

When an image arrives, we don't run one model. We run two parallel pipelines with separate semaphores so face detection and object embedding don't fight for the same CPU cores:

1. Face lane — SCRFD detects faces → align to ArcFace's 5-point template → embed with ArcFace-R100 → embed with AdaFace → store both 512-D vectors in two Pinecone indexes. At query time we score-fuse (0.6 × ArcFace + 0.4 × AdaFace, NIST-FRVT standard).
2. Object lane — YOLOv11-seg crops salient regions → SigLIP-B/16 + DINOv2-base run in parallel on each crop → concatenate to 768-D → store in Pinecone.

After indexing, HDBSCAN clusters all face vectors per user and writes the cluster IDs back to Supabase. Result: the "People View" tab and cluster-aware search — when a face matches with high confidence, we expand the result set to include every image already known to belong to that identity cluster (near-100% recall on well-indexed people).

---

🚀 Quick Start (For Users)

1. Visit photofinderv2.vercel.app.
2. Sign in with Google.
3. Paste your Pinecone API key and your Cloudinary Environment URL in the onboarding modal. (Free-tier accounts work fine — both providers have generous free plans.)
4. Click Verify & Save. The backend will create the required indexes (faces-arcface, faces-adaface, enterprise-objects) on your Pinecone project automatically.
5. Go to Upload → drag in some photos. Use Google Drive picker for bulk imports.
6. Hop over to Search → drop a query image → done.

Privacy note: your keys are encrypted at rest in Supabase and only ever leave the browser to talk to your own Pinecone/Cloudinary projects. The backend is stateless w.r.t. your data — it acts as an inference proxy.

---

🧑‍💻 Local Development

This monorepo holds both codebases. See the per-folder READMEs for full instructions:

• frontend/README.md — React 19 + Vite SPA (deployed to Vercel)
• backend/README.md — FastAPI inference service (mirrored to Hugging Face Spaces)

TL;DR:

# Frontend
cd frontend
npm install
cp .env.local.example .env.local        # then fill in your Supabase keys
npm run dev                              # http://localhost:5173

# Backend
cd ../backend
cp .env.example .env                     # then fill in your secrets
docker build -t enterprise-lens .
docker run -p 7860:7860 --env-file .env enterprise-lens

---

🛠 Tech Stack

---

📂 Repo Layout

photofinderv2/
├── frontend/                      # React 19 SPA — see frontend/README.md
│   ├── src/
│   │   ├── App.jsx                # Tab router + auth state
│   │   ├── components/            # home, search, upload, people, explorer, settings, admin, blog, docs
│   │   ├── context/               # GlobalDBContext (encrypted key storage)
│   │   ├── hooks/                 # useDrivePicker, useLogger, useTheme, useSound, useReveal
│   │   ├── utils/                 # api.js, constants.js, soundEngine, helpers
│   │   ├── supabaseClient.js      # PKCE-mode Supabase client
│   │   └── App.css                # Theme tokens + global styles
│   ├── package.json               # Vite + React 19, no Tailwind
│   ├── vite.config.js
│   └── .env.local.example         # Copy to .env.local and fill in
│
├── backend/                       # FastAPI inference service — see backend/README.md
│   ├── main.py                    # FastAPI app + lifespan (model loading, semaphores)
│   ├── src/
│   │   ├── api/                   # Routers — system, search, upload, explorer, people, jobs, danger
│   │   ├── core/                  # config, security (BYOK key parsing), logging
│   │   ├── services/              # ai_manager, db_client, clustering, jobs, cache, onnx_models
│   │   └── common/                # Shared utilities
│   ├── scripts/                   # convert_to_onnx.py, calibrate_threshold.py, …
│   ├── Dockerfile                 # Python 3.10-slim — builds ONNX models at image build
│   ├── requirements.txt
│   └── .env.example               # Copy to .env and fill in
│
├── .gitlab-ci.yml                 # CI — HF Spaces warmup ping
├── LICENSE                        # MIT
└── README.md                      # ← you are here

The backend (FastAPI) lives in backend/ and is mirrored to Hugging Face Spaces for deployment. See backend/README.md for endpoint docs and deployment instructions.

---

📜 License

MIT — feel free to fork, learn, and remix.

---

🙏 Credits

Built by Adarsh during a deep-dive into modern face/object retrieval. Special thanks to the maintainers of InsightFace, AdaFace, SigLIP, DINOv2, and Ultralytics — without their open weights, none of this would be free.

Got questions, ideas, or want to collaborate? Email me at [email protected].