SmartGallery

Open-source, AI-powered event photo discovery using face recognition and Google Drive.

SmartGallery helps photographers turn an event folder into a searchable photo gallery. Photographers connect a Google Drive folder, SmartGallery indexes the faces in its images, and guests submit a selfie to find the event photos in which they appear.

Connect a Drive folder, index event photos in the background, and share a private selfie-search link with guests.

Important

The complete photographer workflow requires Supabase Auth with Google sign-in, a Google Cloud OAuth application with the Google Drive read-only scope, PostgreSQL with pgvector, and Redis. Local development mode can exercise the dashboard and database without Supabase, but it cannot browse or synchronize Google Drive without real Google OAuth access.

Why SmartGallery?

• Selfie-based photo search: guests find relevant event photos without browsing thousands of images.
• Google Drive workflow: photographers continue organizing and owning their original files in Drive.
• Automatic face indexing: Celery workers detect faces and store searchable embeddings in PostgreSQL with pgvector.
• Multi-event dashboard: create, synchronize, archive, restore, and share event galleries.
• Privacy controls: explicit search consent, in-memory selfie processing, configurable retention, rate limiting, and short-lived photo access tokens.
• Self-hostable stack: Next.js, FastAPI, InsightFace, PostgreSQL, pgvector, Redis, and Celery.

How it works

flowchart LR
    A[Photographer signs in with Google] --> B[Selects a Google Drive folder]
    B --> C[Celery imports and indexes faces]
    C --> D[(PostgreSQL + pgvector)]
    E[Guest opens event link] --> F[Submits selfie with consent]
    F --> G[FastAPI creates a face embedding]
    G --> D
    D --> H[Matching event photos]
    H --> I[Short-lived view and download access]

Loading

Original photos stay in the photographer's Google Drive. SmartGallery stores file metadata and face embeddings, processes guest selfies in memory, and proxies authorized photo results through expiring, event-bound access tokens.

Core features

Area	Capabilities
Photographer	Google sign-in, Drive folder picker, event management, sync and reindex controls
Guest	Public event link, camera or file selfie, consent flow, matched gallery and downloads
Face search	InsightFace detection and embeddings, pgvector similarity search, configurable threshold
Background jobs	Drive polling, batch indexing, retry handling, and retention cleanup with Celery
Security	Supabase JWT validation, encrypted OAuth tokens, upload validation, rate limiting, signed photo access
Privacy	No stored selfies, configurable search-record retention, deletion controls, privacy notice

Technology stack

Layer	Technology
Web application	Next.js 16, React 18, TypeScript, Tailwind CSS
API	Python 3.11+, FastAPI, SQLAlchemy, Alembic
Face recognition	InsightFace, ONNX Runtime, OpenCV
Database	PostgreSQL with pgvector; Supabase recommended for hosted deployments
Authentication	Supabase Auth with Google OAuth
Photo source	Google Drive API v3
Jobs and cache	Celery and Redis

Requirements for full functionality

SmartGallery's production workflow depends on the following services:

1. Supabase
   • PostgreSQL database with the pgvector extension.
   • Supabase Auth with the Google provider enabled.
   • Project URL, public anonymous key, service-role key, and JWT configuration.
2. Google Cloud
   • Google Drive API enabled.
   • OAuth 2.0 web client connected to the Supabase callback URL.
   • openid, email, profile, and https://www.googleapis.com/auth/drive.readonly scopes.
   • Offline access and consent so Drive refresh tokens are available.
3. Redis
   • Celery broker and result backend for synchronization and face-indexing jobs.

Follow the cloud setup guide for the complete configuration, redirect URLs, environment variables, migrations, and verification checklist.

Quick start

Prerequisites: Node.js 20.9 or newer, Python 3.11 or newer, and Git. Docker Desktop is optional for the isolated local database setup.

1. Clone and install the backend

git clone https://github.com/sayan365/smartgallery.git
cd smartgallery/backend
python -m venv .venv

Activate the virtual environment:

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS or Linux
source .venv/bin/activate

Install the application and development dependencies:

python -m pip install -r requirements-dev.txt

2. Choose an infrastructure setup

For the complete application, copy backend/.env.example to backend/.env, configure Supabase, Google OAuth, and Redis, then apply the migrations:

cd backend
alembic upgrade head

For an isolated Windows development database without Supabase, start Docker Desktop and run this command from the repository root:

.\scripts\setup-local.ps1

The script starts loopback-only PostgreSQL/pgvector and Redis containers, applies all migrations, and generates ignored local development credentials. This mode supports local dashboard and database testing but not Google Drive operations.

3. Start the API and workers

Run each command in a separate terminal from backend/:

python -m uvicorn app.main:app --reload --port 8000
celery -A app.worker.celery_app worker --loglevel=info
celery -A app.worker.celery_app beat --loglevel=info

4. Start the frontend

cd frontend
npm ci

For a full Supabase deployment, copy frontend/.env.example to frontend/.env.local and enter the project URL and anonymous key. The local setup script creates a development-only configuration automatically.

npm run dev

Open:

• Web application: http://localhost:3000
• Photographer dashboard: http://localhost:3000/admin
• API health check: http://localhost:8000/api/health
• API documentation in development: http://localhost:8000/docs

Project structure

smartgallery/
|-- backend/              FastAPI API, Celery jobs, migrations, and tests
|-- frontend/             Next.js public gallery and photographer dashboard
|-- docs/                 Architecture, requirements, API, and deployment guides
|-- scripts/              Local development automation
|-- compose.yaml          Local PostgreSQL/pgvector and Redis services
`-- README.md

Testing

cd backend
pytest tests -q -p no:cacheprovider

cd ../frontend
npm run lint
npm run typecheck
npm run build

CI runs the backend security tests, frontend linting, TypeScript checks, production build, and dependency audits for every pull request and push to main.

Security and privacy

Face recognition and contact-data collection may be regulated in your jurisdiction. Before allowing real users, deployers must establish an appropriate legal basis, obtain required consent, publish an operator-specific privacy notice, and configure a suitable retention period.

SmartGallery includes secure defaults, but no default configuration makes a deployment automatically compliant. Read:

• Security policy and vulnerability reporting
• Privacy and biometric-data considerations
• Deployment configuration guide

Never commit environment files, Supabase service-role keys, Google OAuth secrets, real event photos, selfies, face embeddings, or guest contact information.

Documentation

Guide	Description
Documentation index	All architecture, product, and technical documents
Cloud setup	Supabase, Google OAuth, Redis, and deployment configuration
Architecture	Components, data flow, and design decisions
Google Drive integration	OAuth scopes and Drive synchronization
Database schema	PostgreSQL tables, indexes, and pgvector fields
API reference	Authentication, events, search, and photo endpoints

Frequently asked questions

Is Supabase required?

The current production authentication implementation uses Supabase Auth. The application also requires PostgreSQL with pgvector; that database may be hosted by Supabase or another compatible provider. A guarded local-development login is available only through the local setup script.

Is Google OAuth required?

Yes, for the complete photographer workflow. Google sign-in establishes the photographer's identity, and the Drive read-only scope allows SmartGallery to browse and synchronize event photos. Without Google Drive permission, local dashboard and database testing still work, but photo import and indexing do not.

Do event guests need accounts?

No. Guests open a public event URL, provide the required consent and a selfie, and receive matching results. Photographer administration remains authenticated.

Are selfies or original photos stored by SmartGallery?

Guest selfies are processed in memory and are not persisted. Original photos remain in Google Drive; the application stores Drive metadata and face embeddings needed for search.

Contributing

Contributions are welcome. Read CONTRIBUTING.md before opening an issue or pull request, and follow the Code of Conduct.

For security vulnerabilities, use the private reporting process in SECURITY.md instead of opening a public issue.

License

SmartGallery is released under the MIT License.