# sayan365/smartgallery architecture

> Architecture diagram of the GitHub repository sayan365/smartgallery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sayan365/smartgallery
- Repository: https://github.com/sayan365/smartgallery

## Overview

SmartGallery turns a photographer’s Drive event folder into an indexed, shareable gallery, then lets guests search it with a consented selfie and retrieve matched photos through short-lived access. The graph separates the web experience, API workflows, indexing/search services, and persistence/security. Frontend-to-API links and some documented capabilities are based on the README; unsampled implementation details are not inferred beyond those documented relationships.

Main entry points: [`backend/app/services/indexing.py`](https://github.com/sayan365/smartgallery/blob/main/backend/app/services/indexing.py) (Photo indexing), [`backend/app/worker.py`](https://github.com/sayan365/smartgallery/blob/main/backend/app/worker.py) (Background worker), [`backend/app/services/drive.py`](https://github.com/sayan365/smartgallery/blob/main/backend/app/services/drive.py) (Drive integration), [`backend/app/main.py`](https://github.com/sayan365/smartgallery/blob/main/backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_home["Product home<br/>[page.tsx]"]
  node_dashboard["Event dashboard"]
  node_eventpage["Public event page<br/>[page.tsx]"]
  node_searchui["Selfie search"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API workflows"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Profile routes<br/>[auth.py]"]
  node_event_routes["Event management routes<br/>[events.py]"]
  node_public_routes["Public gallery routes<br/>[public.py]"]
end

subgraph group_services["Gallery services"]
  node_drive["Drive integration<br/>[drive.py]"]
  node_event_service["Event management<br/>[events.py]"]
  node_photographer_service["Photographer profiles<br/>[photographer.py]"]
  node_indexing["Photo indexing<br/>[indexing.py]"]
  node_face_engine["Face detection and embeddings<br/>[faces.py]"]
  node_public_search["Similarity search<br/>[public_search.py]"]
end

subgraph group_runtime["Jobs and persistence"]
  node_worker["Background worker<br/>[worker.py]"]
  node_models[("Gallery records<br/>[models.py]")]
  node_database["Database sessions<br/>[database.py]"]
end

subgraph group_security["Identity and privacy"]
  node_auth["Token authentication<br/>[auth.py]"]
  node_photo_access["Photo access tokens<br/>[photo_access.py]"]
  node_privacy["Retention cleanup<br/>[privacy.py]"]
end

node_photographer(("Photographer"))
node_guest(("Guest"))
node_photostore[("PostgreSQL + pgvector")]
node_drive_service["Google Drive"]
node_supabase["Supabase Auth"]
node_redis[("Redis")]

node_photographer -->|"opens gallery"| node_home
node_photographer -->|"manages events"| node_dashboard
node_guest -->|"opens event link"| node_eventpage
node_guest -->|"submits selfie"| node_searchui
node_dashboard -.->|"requests event operations"| node_api_client
node_searchui -.->|"submits search"| node_api_client
node_api_client -.->|"calls API"| node_api_app
node_api_app -->|"routes requests"| node_auth_routes
node_api_app -->|"routes requests"| node_event_routes
node_api_app -->|"routes requests"| node_public_routes
node_auth_routes -->|"validates identity"| node_auth
node_auth_routes -->|"upserts profile"| node_photographer_service
node_event_routes -->|"browses and syncs"| node_drive
node_event_routes -->|"manages events"| node_event_service
node_event_routes -->|"queues indexing"| node_indexing
node_public_routes -->|"looks up and searches"| node_public_search
node_public_routes -->|"downloads photo bytes"| node_drive
node_public_search -->|"embeds selfie"| node_face_engine
node_public_search -->|"creates access token"| node_photo_access
node_indexing -->|"downloads originals"| node_drive
node_indexing -->|"extracts faces"| node_face_engine
node_indexing -->|"enqueues photos"| node_worker
node_worker -->|"synchronizes folders"| node_drive
node_worker -->|"runs indexing jobs"| node_indexing
node_worker -->|"cleans expired sessions"| node_privacy
node_models -->|"uses declarative base"| node_database
node_database -->|"connects sessions"| node_photostore
node_auth -->|"verifies user"| node_supabase
node_worker -->|"uses broker"| node_redis
node_drive -->|"reads event photos"| node_drive_service
node_public_search -->|"queries embeddings"| node_photostore
node_indexing -.->|"stores embeddings"| node_photostore

click node_home "https://github.com/sayan365/smartgallery/blob/main/frontend/src/app/page.tsx"
click node_dashboard "https://github.com/sayan365/smartgallery/blob/main/frontend/src/components/admin-dashboard.tsx"
click node_eventpage "https://github.com/sayan365/smartgallery/blob/main/frontend/src/app/event/%5Bslug%5D/page.tsx"
click node_searchui "https://github.com/sayan365/smartgallery/blob/main/frontend/src/components/public-event-search.tsx"
click node_api_client "https://github.com/sayan365/smartgallery/blob/main/frontend/src/lib/api.ts"
click node_api_app "https://github.com/sayan365/smartgallery/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/sayan365/smartgallery/blob/main/backend/app/routers/auth.py"
click node_event_routes "https://github.com/sayan365/smartgallery/blob/main/backend/app/routers/events.py"
click node_public_routes "https://github.com/sayan365/smartgallery/blob/main/backend/app/routers/public.py"
click node_drive "https://github.com/sayan365/smartgallery/blob/main/backend/app/services/drive.py"
click node_event_service "https://github.com/sayan365/smartgallery/blob/main/backend/app/services/events.py"
click node_photographer_service "https://github.com/sayan365/smartgallery/blob/main/backend/app/services/photographer.py"
click node_indexing "https://github.com/sayan365/smartgallery/blob/main/backend/app/services/indexing.py"
click node_face_engine "https://github.com/sayan365/smartgallery/blob/main/backend/app/services/faces.py"
click node_public_search "https://github.com/sayan365/smartgallery/blob/main/backend/app/services/public_search.py"
click node_worker "https://github.com/sayan365/smartgallery/blob/main/backend/app/worker.py"
click node_models "https://github.com/sayan365/smartgallery/blob/main/backend/app/models.py"
click node_database "https://github.com/sayan365/smartgallery/blob/main/backend/app/database.py"
click node_auth "https://github.com/sayan365/smartgallery/blob/main/backend/app/auth.py"
click node_photo_access "https://github.com/sayan365/smartgallery/blob/main/backend/app/photo_access.py"
click node_privacy "https://github.com/sayan365/smartgallery/blob/main/backend/app/services/privacy.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_dashboard,node_eventpage,node_searchui,node_api_client toneBlue
class node_api_app,node_auth_routes,node_event_routes,node_public_routes,node_photostore,node_redis toneAmber
class node_drive,node_event_service,node_photographer_service,node_indexing,node_face_engine,node_public_search toneMint
class node_worker,node_models,node_database toneRose
class node_auth,node_photo_access,node_privacy,node_photographer,node_guest,node_drive_service,node_supabase toneIndigo
```

## Components

### Web experience

- [Product home](https://github.com/sayan365/smartgallery/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Event dashboard](https://github.com/sayan365/smartgallery/blob/main/frontend/src/components/admin-dashboard.tsx): `frontend/src/components/admin-dashboard.tsx`
- [Public event page](https://github.com/sayan365/smartgallery/blob/main/frontend/src/app/event/%5Bslug%5D/page.tsx): `frontend/src/app/event/[slug]/page.tsx`
- [Selfie search](https://github.com/sayan365/smartgallery/blob/main/frontend/src/components/public-event-search.tsx): `frontend/src/components/public-event-search.tsx`
- [API client](https://github.com/sayan365/smartgallery/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API workflows

- [FastAPI application](https://github.com/sayan365/smartgallery/blob/main/backend/app/main.py): `backend/app/main.py`
- [Profile routes](https://github.com/sayan365/smartgallery/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Event management routes](https://github.com/sayan365/smartgallery/blob/main/backend/app/routers/events.py): `backend/app/routers/events.py`
- [Public gallery routes](https://github.com/sayan365/smartgallery/blob/main/backend/app/routers/public.py): `backend/app/routers/public.py`

### Gallery services

- [Drive integration](https://github.com/sayan365/smartgallery/blob/main/backend/app/services/drive.py): `backend/app/services/drive.py`
- [Event management](https://github.com/sayan365/smartgallery/blob/main/backend/app/services/events.py): `backend/app/services/events.py`
- [Photographer profiles](https://github.com/sayan365/smartgallery/blob/main/backend/app/services/photographer.py): `backend/app/services/photographer.py`
- [Photo indexing](https://github.com/sayan365/smartgallery/blob/main/backend/app/services/indexing.py): `backend/app/services/indexing.py`
- [Face detection and embeddings](https://github.com/sayan365/smartgallery/blob/main/backend/app/services/faces.py): `backend/app/services/faces.py`
- [Similarity search](https://github.com/sayan365/smartgallery/blob/main/backend/app/services/public_search.py): `backend/app/services/public_search.py`

### Jobs and persistence

- [Background worker](https://github.com/sayan365/smartgallery/blob/main/backend/app/worker.py): `backend/app/worker.py`
- [Gallery records](https://github.com/sayan365/smartgallery/blob/main/backend/app/models.py): `backend/app/models.py`
- [Database sessions](https://github.com/sayan365/smartgallery/blob/main/backend/app/database.py): `backend/app/database.py`

### Identity and privacy

- [Token authentication](https://github.com/sayan365/smartgallery/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Photo access tokens](https://github.com/sayan365/smartgallery/blob/main/backend/app/photo_access.py): `backend/app/photo_access.py`
- [Retention cleanup](https://github.com/sayan365/smartgallery/blob/main/backend/app/services/privacy.py): `backend/app/services/privacy.py`

### Other components

- **Photographer**
- **Guest**
- **PostgreSQL + pgvector**
- **Google Drive**
- **Supabase Auth**
- **Redis**

## Connections

- Photographer → Product home: opens gallery (evidence: `README.md`)
- Photographer → Event dashboard: manages events (evidence: `README.md`)
- Guest → Public event page: opens event link (evidence: `README.md`)
- Guest → Selfie search: submits selfie (evidence: `README.md`)
- Event dashboard → API client: requests event operations
- Selfie search → API client: submits search
- API client → FastAPI application: calls API
- FastAPI application → Profile routes: routes requests (evidence: `backend/app/main.py`)
- FastAPI application → Event management routes: routes requests (evidence: `backend/app/main.py`)
- FastAPI application → Public gallery routes: routes requests (evidence: `backend/app/main.py`)
- Profile routes → Token authentication: validates identity (evidence: `backend/app/routers/auth.py`)
- Profile routes → Photographer profiles: upserts profile (evidence: `backend/app/routers/auth.py`)
- Event management routes → Drive integration: browses and syncs (evidence: `backend/app/routers/events.py`)
- Event management routes → Event management: manages events (evidence: `backend/app/routers/events.py`)
- Event management routes → Photo indexing: queues indexing (evidence: `backend/app/routers/events.py`)
- Public gallery routes → Similarity search: looks up and searches (evidence: `backend/app/routers/public.py`)
- Public gallery routes → Drive integration: downloads photo bytes (evidence: `backend/app/routers/public.py`)
- Similarity search → Face detection and embeddings: embeds selfie (evidence: `backend/app/services/public_search.py`)
- Similarity search → Photo access tokens: creates access token (evidence: `backend/app/services/public_search.py`)
- Photo indexing → Drive integration: downloads originals (evidence: `backend/app/services/indexing.py`)
- Photo indexing → Face detection and embeddings: extracts faces (evidence: `backend/app/services/indexing.py`)
- Photo indexing → Background worker: enqueues photos (evidence: `backend/app/services/indexing.py`)
- Background worker → Drive integration: synchronizes folders (evidence: `backend/app/worker.py`)
- Background worker → Photo indexing: runs indexing jobs (evidence: `backend/app/worker.py`)
- Background worker → Retention cleanup: cleans expired sessions (evidence: `backend/app/worker.py`)
- Gallery records → Database sessions: uses declarative base (evidence: `backend/app/models.py`)
- Database sessions → PostgreSQL + pgvector: connects sessions (evidence: `backend/app/database.py`)
- Token authentication → Supabase Auth: verifies user (evidence: `backend/app/auth.py`)
- Background worker → Redis: uses broker (evidence: `README.md`)
- Drive integration → Google Drive: reads event photos (evidence: `README.md`)
- Similarity search → PostgreSQL + pgvector: queries embeddings (evidence: `backend/app/services/public_search.py`)
- Photo indexing → PostgreSQL + pgvector: stores embeddings
