# shahir-47/grab-pic architecture

> Architecture diagram of the GitHub repository shahir-47/grab-pic, 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/shahir-47/grab-pic
- Repository: https://github.com/shahir-47/grab-pic

## Overview

GrabPic lets event hosts create albums and upload photos, then lets guests use a shared link and selfie to find matching photos. The documented flow queues uploaded photos for face processing; guest searches return matching photo IDs, which the API turns into signed viewing URLs. The graph retains the major album-management, upload, access-control, face-processing, search and download capabilities. Several backend and frontend integrations are documented in the README but their implementation was not sampled, so those edges cite the README.

Main entry points: [`api/src/main/java/com/grabpic/api/controller/AlbumController.java`](https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/controller/AlbumController.java) (Album endpoints), [`grab-pic-web/lib/api.ts`](https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/lib/api.ts) (API client), [`grab-pic-web/app/albums/[id]/guest/page.tsx`](https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/albums/%5Bid%5D/guest/page.tsx) (Guest search), [`api/src/main/java/com/grabpic/api/service/S3StorageService.java`](https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/service/S3StorageService.java) (Storage URL service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Next.js app<br/>[page.tsx]"]
  node_hostalbums["Host albums<br/>[page.tsx]"]
  node_albummanage["Album management<br/>[page.tsx]"]
  node_albumview["Album viewing<br/>[page.tsx]"]
  node_guestsearch["Guest search<br/>[page.tsx]"]
  node_authpages["Sign-in and signup<br/>[page.tsx]"]
  node_apihelper["API client<br/>[api.ts]"]
  node_download["ZIP download<br/>[download.ts]"]
end

subgraph group_api["Album API"]
  node_albumapi["Album endpoints"]
  node_albumrepo["Album repository"]
  node_photorepo["Photo repository"]
  node_albumdata["Album and photo models<br/>[SharedAlbum.java]"]
  node_s3service["Storage URL service"]
  node_queueservice["Processing queue client<br/>[SqsService.java]"]
  node_turnstile["Captcha verification"]
end

subgraph group_processing["Face processing"]
  node_worker["Face worker<br/>[main.py]"]
  node_searchapi["Selfie search API<br/>[api.py]"]
end

subgraph group_services["External services"]
  node_auth["Supabase Auth"]
  node_database[("PostgreSQL and pgvector")]
  node_s3[("AWS S3")]
  node_sqs["AWS SQS"]
  node_captchaext["Cloudflare Turnstile"]
  node_cloudfront["CloudFront"]
end

node_host(("Album host"))
node_guest(("Album guest"))

node_host -->|"opens app"| node_webapp
node_guest -->|"opens shared link"| node_guestsearch
node_host -->|"signs in"| node_authpages
node_authpages -->|"authenticates"| node_auth
node_host -->|"manages albums"| node_hostalbums
node_hostalbums -.->|"requests albums"| node_apihelper
node_albummanage -.->|"manages photos"| node_apihelper
node_albumview -.->|"loads photos"| node_apihelper
node_guestsearch -.->|"searches album"| node_apihelper
node_guestsearch -.->|"downloads matches"| node_download
node_apihelper -->|"proxies API calls"| node_albumapi
node_albumapi -->|"reads and writes"| node_albumrepo
node_albumapi -->|"reads and writes"| node_photorepo
node_albumrepo -->|"persists albums"| node_database
node_photorepo -->|"persists photos"| node_database
node_albumapi -->|"signs upload and view URLs"| node_s3service
node_s3service -->|"presigns and manages objects"| node_s3
node_s3service -.->|"signs view URLs"| node_cloudfront
node_albumapi -->|"queues photo jobs"| node_queueservice
node_queueservice -->|"sends jobs"| node_sqs
node_sqs -->|"delivers jobs"| node_worker
node_worker -->|"downloads photos"| node_s3
node_worker -->|"stores face embeddings"| node_database
node_guestsearch -->|"submits selfie"| node_searchapi
node_searchapi -->|"queries face matches"| node_database
node_albumapi -->|"routes search calls"| node_searchapi
node_albumapi -->|"checks captcha"| node_turnstile
node_turnstile -->|"verifies token"| node_captchaext
node_albumapi -->|"validates JWT"| node_auth
node_albumapi -->|"maps album and photo data"| node_albumdata

click node_webapp "https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/page.tsx"
click node_hostalbums "https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/dashboard/page.tsx"
click node_albummanage "https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/dashboard/albums/%5Bid%5D/page.tsx"
click node_albumview "https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/dashboard/albums/%5Bid%5D/view/page.tsx"
click node_guestsearch "https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/albums/%5Bid%5D/guest/page.tsx"
click node_authpages "https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/login/page.tsx"
click node_apihelper "https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/lib/api.ts"
click node_download "https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/lib/download.ts"
click node_albumapi "https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/controller/AlbumController.java"
click node_albumrepo "https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/repository/SharedAlbumRepository.java"
click node_photorepo "https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/repository/PhotoRepository.java"
click node_albumdata "https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/model/SharedAlbum.java"
click node_s3service "https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/service/S3StorageService.java"
click node_queueservice "https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/service/SqsService.java"
click node_turnstile "https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/service/TurnstileService.java"
click node_worker "https://github.com/shahir-47/grab-pic/blob/main/ai-face-worker/main.py"
click node_searchapi "https://github.com/shahir-47/grab-pic/blob/main/ai-face-worker/api.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_webapp,node_hostalbums,node_albummanage,node_albumview,node_guestsearch,node_authpages,node_apihelper,node_download toneBlue
class node_albumapi,node_albumrepo,node_photorepo,node_albumdata,node_s3service,node_queueservice,node_turnstile toneAmber
class node_worker,node_searchapi toneMint
class node_auth,node_database,node_s3,node_sqs,node_captchaext,node_cloudfront toneRose
class node_host,node_guest toneIndigo
```

## Components

### Web application

- [Next.js app](https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/page.tsx): `grab-pic-web/app/page.tsx`
- [Host albums](https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/dashboard/page.tsx): `grab-pic-web/app/dashboard/page.tsx`
- [Album management](https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/dashboard/albums/%5Bid%5D/page.tsx): `grab-pic-web/app/dashboard/albums/[id]/page.tsx`
- [Album viewing](https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/dashboard/albums/%5Bid%5D/view/page.tsx): `grab-pic-web/app/dashboard/albums/[id]/view/page.tsx`
- [Guest search](https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/albums/%5Bid%5D/guest/page.tsx): `grab-pic-web/app/albums/[id]/guest/page.tsx`
- [Sign-in and signup](https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/app/login/page.tsx): `grab-pic-web/app/login/page.tsx`
- [API client](https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/lib/api.ts): `grab-pic-web/lib/api.ts`
- [ZIP download](https://github.com/shahir-47/grab-pic/blob/main/grab-pic-web/lib/download.ts): `grab-pic-web/lib/download.ts`

### Album API

- [Album endpoints](https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/controller/AlbumController.java): `api/src/main/java/com/grabpic/api/controller/AlbumController.java`
- [Album repository](https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/repository/SharedAlbumRepository.java): `api/src/main/java/com/grabpic/api/repository/SharedAlbumRepository.java`
- [Photo repository](https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/repository/PhotoRepository.java): `api/src/main/java/com/grabpic/api/repository/PhotoRepository.java`
- [Album and photo models](https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/model/SharedAlbum.java): `api/src/main/java/com/grabpic/api/model/SharedAlbum.java`
- [Storage URL service](https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/service/S3StorageService.java): `api/src/main/java/com/grabpic/api/service/S3StorageService.java`
- [Processing queue client](https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/service/SqsService.java): `api/src/main/java/com/grabpic/api/service/SqsService.java`
- [Captcha verification](https://github.com/shahir-47/grab-pic/blob/main/api/src/main/java/com/grabpic/api/service/TurnstileService.java): `api/src/main/java/com/grabpic/api/service/TurnstileService.java`

### Face processing

- [Face worker](https://github.com/shahir-47/grab-pic/blob/main/ai-face-worker/main.py): `ai-face-worker/main.py`
- [Selfie search API](https://github.com/shahir-47/grab-pic/blob/main/ai-face-worker/api.py): `ai-face-worker/api.py`

### External services

- **Supabase Auth**
- **PostgreSQL and pgvector**
- **AWS S3**
- **AWS SQS**
- **Cloudflare Turnstile**
- **CloudFront**

### Other components

- **Album host**
- **Album guest**

## Connections

- Album host → Next.js app: opens app (evidence: `README.md`)
- Album guest → Guest search: opens shared link (evidence: `README.md`)
- Album host → Sign-in and signup: signs in (evidence: `README.md`)
- Sign-in and signup → Supabase Auth: authenticates (evidence: `README.md`)
- Album host → Host albums: manages albums (evidence: `README.md`)
- Host albums → API client: requests albums
- Album management → API client: manages photos
- Album viewing → API client: loads photos
- Guest search → API client: searches album
- Guest search → ZIP download: downloads matches
- API client → Album endpoints: proxies API calls (evidence: `README.md`)
- Album endpoints → Album repository: reads and writes (evidence: `api/src/main/java/com/grabpic/api/controller/AlbumController.java`)
- Album endpoints → Photo repository: reads and writes (evidence: `api/src/main/java/com/grabpic/api/controller/AlbumController.java`)
- Album repository → PostgreSQL and pgvector: persists albums (evidence: `README.md`)
- Photo repository → PostgreSQL and pgvector: persists photos (evidence: `README.md`)
- Album endpoints → Storage URL service: signs upload and view URLs (evidence: `api/src/main/java/com/grabpic/api/controller/AlbumController.java`)
- Storage URL service → AWS S3: presigns and manages objects (evidence: `api/src/main/java/com/grabpic/api/service/S3StorageService.java`)
- Storage URL service → CloudFront: signs view URLs (evidence: `api/src/main/java/com/grabpic/api/service/S3StorageService.java`)
- Album endpoints → Processing queue client: queues photo jobs (evidence: `api/src/main/java/com/grabpic/api/controller/AlbumController.java`)
- Processing queue client → AWS SQS: sends jobs (evidence: `api/src/main/java/com/grabpic/api/service/SqsService.java`)
- AWS SQS → Face worker: delivers jobs (evidence: `README.md`)
- Face worker → AWS S3: downloads photos (evidence: `README.md`)
- Face worker → PostgreSQL and pgvector: stores face embeddings (evidence: `README.md`)
- Guest search → Selfie search API: submits selfie (evidence: `README.md`)
- Selfie search API → PostgreSQL and pgvector: queries face matches (evidence: `README.md`)
- Album endpoints → Selfie search API: routes search calls (evidence: `README.md`)
- Album endpoints → Captcha verification: checks captcha (evidence: `api/src/main/java/com/grabpic/api/controller/AlbumController.java`)
- Captcha verification → Cloudflare Turnstile: verifies token (evidence: `api/src/main/java/com/grabpic/api/service/TurnstileService.java`)
- Album endpoints → Supabase Auth: validates JWT (evidence: `README.md`)
- Album endpoints → Album and photo models: maps album and photo data (evidence: `api/src/main/java/com/grabpic/api/controller/AlbumController.java`)
