# yashoswalyo/picshare architecture

> Architecture diagram of the GitHub repository yashoswalyo/picshare, 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/yashoswalyo/picshare
- Repository: https://github.com/yashoswalyo/picshare

## Overview

PICSHARE is an event-photo sharing platform: admins manage events and photo processing, while guests submit a selfie to find a curated gallery. The backend covers event and guest records, Drive photo sync, face indexing and matching, and gallery delivery; a separate worker runs recovery and scheduled jobs. The README documents the user-facing capabilities, while sampled backend excerpts establish several internal calls. Frontend-to-API wiring and unsampled job details are not shown, so those links are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/yashoswalyo/picshare/blob/main/backend/app/main.py) (FastAPI Application), [`backend/app/services/db.py`](https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/db.py) (SQLite Database), [`backend/app/api/guests.py`](https://github.com/yashoswalyo/picshare/blob/main/backend/app/api/guests.py) (Guest Requests and Matches), [`backend/app/api/photos.py`](https://github.com/yashoswalyo/picshare/blob/main/backend/app/api/photos.py) (Photo Upload and Sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Guest and Admin UI"]
  node_home["Home Experience<br/>[home-client.tsx]"]
  node_event_browse["Event Listing"]
  node_admin_ui["Admin Dashboard"]
  node_guest_upload["Guest Selfie Upload"]
  node_guest_gallery["Guest Gallery"]
end

subgraph group_api["Backend API"]
  node_auth_api["Admin Authentication<br/>[auth.py]"]
  node_event_api["Event Management<br/>[events.py]"]
  node_photo_api["Photo Upload and Sync<br/>[photos.py]"]
  node_guest_api["Guest Requests and Matches<br/>[guests.py]"]
  node_app_entry["FastAPI Application<br/>[main.py]"]
end

subgraph group_processing["Photo and Matching Services"]
  node_database[("SQLite Database<br/>[db.py]")]
  node_drive_service["Google Drive Service<br/>[drive_service.py]"]
  node_face_service["Face Recognition<br/>[face_service.py]"]
  node_thumbnails["Thumbnail Generation"]
end

subgraph group_operations["Background Operations"]
  node_cron_worker["Cron Worker<br/>[cron_worker.py]"]
  node_recovery["Recovery Tasks<br/>[recovery.py]"]
  node_cron_jobs["Scheduled Jobs<br/>[cron_jobs.py]"]
end

node_visitor(("Admin or Guest"))
node_google_drive["Google Drive"]

node_visitor -->|"browses"| node_home
node_visitor -->|"finds events"| node_event_browse
node_visitor -->|"manages events"| node_admin_ui
node_visitor -->|"submits selfie"| node_guest_upload
node_guest_upload -->|"views matches"| node_guest_gallery
node_app_entry -->|"registers route"| node_auth_api
node_app_entry -->|"registers route"| node_event_api
node_app_entry -->|"registers route"| node_photo_api
node_app_entry -->|"registers route"| node_guest_api
node_app_entry -->|"opens connection"| node_database
node_auth_api -.->|"serves route"| node_app_entry
node_event_api -->|"reads and writes"| node_database
node_photo_api -->|"reads and writes"| node_database
node_photo_api -->|"syncs and retrieves"| node_drive_service
node_photo_api -->|"generates thumbnails"| node_thumbnails
node_guest_api -->|"reads and writes"| node_database
node_guest_api -->|"extracts and compares"| node_face_service
node_guest_api -->|"downloads originals"| node_drive_service
node_guest_api -->|"returns photo URLs"| node_photo_api
node_drive_service -->|"syncs files"| node_google_drive
node_cron_worker -->|"opens connection"| node_database
node_cron_worker -->|"runs recovery"| node_recovery
node_cron_worker -->|"starts jobs"| node_cron_jobs
node_recovery -->|"accesses records"| node_database

click node_home "https://github.com/yashoswalyo/picshare/blob/main/frontend/src/components/home-client.tsx"
click node_event_browse "https://github.com/yashoswalyo/picshare/blob/main/frontend/src/components/events-list-client.tsx"
click node_admin_ui "https://github.com/yashoswalyo/picshare/blob/main/frontend/src/components/admin-dashboard-client.tsx"
click node_guest_upload "https://github.com/yashoswalyo/picshare/blob/main/frontend/src/components/guest-upload-client.tsx"
click node_guest_gallery "https://github.com/yashoswalyo/picshare/blob/main/frontend/src/components/guest-gallery-client.tsx"
click node_auth_api "https://github.com/yashoswalyo/picshare/blob/main/backend/app/api/auth.py"
click node_event_api "https://github.com/yashoswalyo/picshare/blob/main/backend/app/api/events.py"
click node_photo_api "https://github.com/yashoswalyo/picshare/blob/main/backend/app/api/photos.py"
click node_guest_api "https://github.com/yashoswalyo/picshare/blob/main/backend/app/api/guests.py"
click node_app_entry "https://github.com/yashoswalyo/picshare/blob/main/backend/app/main.py"
click node_database "https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/db.py"
click node_drive_service "https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/drive_service.py"
click node_face_service "https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/face_service.py"
click node_thumbnails "https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/thumbnail_service.py"
click node_cron_worker "https://github.com/yashoswalyo/picshare/blob/main/backend/cron_worker.py"
click node_recovery "https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/recovery.py"
click node_cron_jobs "https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/cron_jobs.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_event_browse,node_admin_ui,node_guest_upload,node_guest_gallery toneBlue
class node_auth_api,node_event_api,node_photo_api,node_guest_api,node_app_entry toneAmber
class node_database,node_drive_service,node_face_service,node_thumbnails toneMint
class node_cron_worker,node_recovery,node_cron_jobs toneRose
class node_visitor,node_google_drive toneIndigo
```

## Components

### Guest and Admin UI

- [Home Experience](https://github.com/yashoswalyo/picshare/blob/main/frontend/src/components/home-client.tsx): `frontend/src/components/home-client.tsx`
- [Event Listing](https://github.com/yashoswalyo/picshare/blob/main/frontend/src/components/events-list-client.tsx): `frontend/src/components/events-list-client.tsx`
- [Admin Dashboard](https://github.com/yashoswalyo/picshare/blob/main/frontend/src/components/admin-dashboard-client.tsx): `frontend/src/components/admin-dashboard-client.tsx`
- [Guest Selfie Upload](https://github.com/yashoswalyo/picshare/blob/main/frontend/src/components/guest-upload-client.tsx): `frontend/src/components/guest-upload-client.tsx`
- [Guest Gallery](https://github.com/yashoswalyo/picshare/blob/main/frontend/src/components/guest-gallery-client.tsx): `frontend/src/components/guest-gallery-client.tsx`

### Backend API

- [Admin Authentication](https://github.com/yashoswalyo/picshare/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Event Management](https://github.com/yashoswalyo/picshare/blob/main/backend/app/api/events.py): `backend/app/api/events.py`
- [Photo Upload and Sync](https://github.com/yashoswalyo/picshare/blob/main/backend/app/api/photos.py): `backend/app/api/photos.py`
- [Guest Requests and Matches](https://github.com/yashoswalyo/picshare/blob/main/backend/app/api/guests.py): `backend/app/api/guests.py`
- [FastAPI Application](https://github.com/yashoswalyo/picshare/blob/main/backend/app/main.py): `backend/app/main.py`

### Photo and Matching Services

- [SQLite Database](https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/db.py): `backend/app/services/db.py`
- [Google Drive Service](https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/drive_service.py): `backend/app/services/drive_service.py`
- [Face Recognition](https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/face_service.py): `backend/app/services/face_service.py`
- [Thumbnail Generation](https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/thumbnail_service.py): `backend/app/services/thumbnail_service.py`

### Background Operations

- [Cron Worker](https://github.com/yashoswalyo/picshare/blob/main/backend/cron_worker.py): `backend/cron_worker.py`
- [Recovery Tasks](https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/recovery.py): `backend/app/services/recovery.py`
- [Scheduled Jobs](https://github.com/yashoswalyo/picshare/blob/main/backend/app/services/cron_jobs.py): `backend/app/services/cron_jobs.py`

### Other components

- **Admin or Guest**
- **Google Drive**

## Connections

- Admin or Guest → Home Experience: browses (evidence: `README.md`)
- Admin or Guest → Event Listing: finds events (evidence: `README.md`)
- Admin or Guest → Admin Dashboard: manages events (evidence: `README.md`)
- Admin or Guest → Guest Selfie Upload: submits selfie (evidence: `README.md`)
- Guest Selfie Upload → Guest Gallery: views matches (evidence: `README.md`)
- FastAPI Application → Admin Authentication: registers route (evidence: `backend/app/main.py`)
- FastAPI Application → Event Management: registers route (evidence: `backend/app/main.py`)
- FastAPI Application → Photo Upload and Sync: registers route (evidence: `backend/app/main.py`)
- FastAPI Application → Guest Requests and Matches: registers route (evidence: `backend/app/main.py`)
- FastAPI Application → SQLite Database: opens connection (evidence: `backend/app/main.py`)
- Admin Authentication → FastAPI Application: serves route (evidence: `backend/app/main.py`)
- Event Management → SQLite Database: reads and writes (evidence: `backend/app/api/events.py`)
- Photo Upload and Sync → SQLite Database: reads and writes (evidence: `backend/app/api/photos.py`)
- Photo Upload and Sync → Google Drive Service: syncs and retrieves (evidence: `backend/app/api/photos.py`)
- Photo Upload and Sync → Thumbnail Generation: generates thumbnails (evidence: `backend/app/api/photos.py`)
- Guest Requests and Matches → SQLite Database: reads and writes (evidence: `backend/app/api/guests.py`)
- Guest Requests and Matches → Face Recognition: extracts and compares (evidence: `backend/app/api/guests.py`)
- Guest Requests and Matches → Google Drive Service: downloads originals (evidence: `backend/app/api/guests.py`)
- Guest Requests and Matches → Photo Upload and Sync: returns photo URLs (evidence: `backend/app/api/guests.py`)
- Google Drive Service → Google Drive: syncs files (evidence: `backend/app/services/drive_service.py`)
- Cron Worker → SQLite Database: opens connection (evidence: `backend/cron_worker.py`)
- Cron Worker → Recovery Tasks: runs recovery (evidence: `backend/cron_worker.py`)
- Cron Worker → Scheduled Jobs: starts jobs (evidence: `backend/cron_worker.py`)
- Recovery Tasks → SQLite Database: accesses records (evidence: `backend/app/services/recovery.py`)
