# luckwoon02/picshare architecture

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

- Interactive diagram: https://gitdiagram.com/luckwoon02/picshare
- Repository: https://github.com/luckwoon02/picshare

## Overview

PICSHARE lets admins manage protected events and upload photos, then lets guests submit a selfie to find matching event photos. The backend coordinates event/photo processing and guest matching, using SQLite for records, S3 for images and Rekognition for face indexing and search; the frontend provides admin and guest portals. The README documents the product flows, while some implementation excerpts are partial or absent, so uncertain frontend-to-API links are shown as unverified rather than asserted.

Main entry points: [`backend/app/main.py`](https://github.com/luckwoon02/picshare/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/services/db.py`](https://github.com/luckwoon02/picshare/blob/main/backend/app/services/db.py) (SQLite records), [`backend/app/api/photos.py`](https://github.com/luckwoon02/picshare/blob/main/backend/app/api/photos.py) (Photo processing), [`backend/app/api/events.py`](https://github.com/luckwoon02/picshare/blob/main/backend/app/api/events.py) (Event management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web portals"]
  node_admin_ui["Admin portal"]
  node_guest_ui["Guest portal"]
  node_gallery_ui["Guest gallery"]
  node_events_ui["Event listing"]
end

subgraph group_api["API workflows"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth["Admin authentication<br/>[auth.py]"]
  node_events["Event management<br/>[events.py]"]
  node_photos["Photo processing<br/>[photos.py]"]
  node_guests["Guest matching<br/>[guests.py]"]
end

subgraph group_services["Backend services"]
  node_config["Settings<br/>[config.py]"]
  node_thumbnails["Thumbnail generation"]
  node_rekognition["Face recognition"]
  node_s3["Photo storage service<br/>[s3_service.py]"]
end

subgraph group_state["Storage and recovery"]
  node_database[("SQLite records<br/>[db.py]")]
  node_worker["Recovery worker<br/>[cron_worker.py]"]
  node_recovery["Recovery tasks<br/>[recovery.py]"]
end

node_admin(("Admin"))
node_guest(("Guest"))
node_aws_s3[("AWS S3")]
node_aws_rekognition{{"AWS Rekognition"}}

node_admin -->|"manages events"| node_admin_ui
node_guest -->|"submits selfie"| node_guest_ui
node_guest_ui -->|"views matches"| node_gallery_ui
node_guest -->|"browses events"| node_events_ui
node_admin_ui -.->|"uses API"| node_api_app
node_guest_ui -.->|"uses API"| node_api_app
node_gallery_ui -.->|"requests gallery"| node_api_app
node_events_ui -.->|"requests events"| node_api_app
node_api_app -->|"registers router"| node_auth
node_api_app -->|"registers router"| node_events
node_api_app -->|"registers router"| node_photos
node_api_app -->|"registers router"| node_guests
node_api_app -->|"opens connection"| node_database
node_auth -->|"reads settings"| node_config
node_events -->|"reads and writes"| node_database
node_events -->|"deletes collection"| node_rekognition
node_events -->|"checks and deletes storage"| node_s3
node_photos -->|"reads and writes"| node_database
node_photos -->|"stores and serves photos"| node_s3
node_photos -->|"indexes faces"| node_rekognition
node_photos -->|"generates thumbnails"| node_thumbnails
node_guests -->|"reads and writes"| node_database
node_guests -->|"searches selfie"| node_rekognition
node_guests -->|"creates gallery URLs"| node_s3
node_s3 -->|"uploads and signs URLs"| node_aws_s3
node_rekognition -->|"indexes and searches faces"| node_aws_rekognition
node_worker -->|"connects to"| node_database
node_worker -->|"runs tasks"| node_recovery
node_recovery -->|"repairs records"| node_database

click node_admin_ui "https://github.com/luckwoon02/picshare/blob/main/frontend/src/components/admin-dashboard-client.tsx"
click node_guest_ui "https://github.com/luckwoon02/picshare/blob/main/frontend/src/components/guest-upload-client.tsx"
click node_gallery_ui "https://github.com/luckwoon02/picshare/blob/main/frontend/src/components/guest-gallery-client.tsx"
click node_events_ui "https://github.com/luckwoon02/picshare/blob/main/frontend/src/components/events-list-client.tsx"
click node_api_app "https://github.com/luckwoon02/picshare/blob/main/backend/app/main.py"
click node_auth "https://github.com/luckwoon02/picshare/blob/main/backend/app/api/auth.py"
click node_events "https://github.com/luckwoon02/picshare/blob/main/backend/app/api/events.py"
click node_photos "https://github.com/luckwoon02/picshare/blob/main/backend/app/api/photos.py"
click node_guests "https://github.com/luckwoon02/picshare/blob/main/backend/app/api/guests.py"
click node_config "https://github.com/luckwoon02/picshare/blob/main/backend/app/core/config.py"
click node_thumbnails "https://github.com/luckwoon02/picshare/blob/main/backend/app/services/thumbnail_service.py"
click node_rekognition "https://github.com/luckwoon02/picshare/blob/main/backend/app/services/rekognition_service.py"
click node_s3 "https://github.com/luckwoon02/picshare/blob/main/backend/app/services/s3_service.py"
click node_database "https://github.com/luckwoon02/picshare/blob/main/backend/app/services/db.py"
click node_worker "https://github.com/luckwoon02/picshare/blob/main/backend/cron_worker.py"
click node_recovery "https://github.com/luckwoon02/picshare/blob/main/backend/app/services/recovery.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_admin_ui,node_guest_ui,node_gallery_ui,node_events_ui toneBlue
class node_api_app,node_auth,node_events,node_photos,node_guests,node_aws_s3 toneAmber
class node_config,node_thumbnails,node_rekognition,node_s3 toneMint
class node_database,node_worker,node_recovery toneRose
class node_admin,node_guest,node_aws_rekognition toneIndigo
```

## Components

### Web portals

- [Admin portal](https://github.com/luckwoon02/picshare/blob/main/frontend/src/components/admin-dashboard-client.tsx): `frontend/src/components/admin-dashboard-client.tsx`
- [Guest portal](https://github.com/luckwoon02/picshare/blob/main/frontend/src/components/guest-upload-client.tsx): `frontend/src/components/guest-upload-client.tsx`
- [Guest gallery](https://github.com/luckwoon02/picshare/blob/main/frontend/src/components/guest-gallery-client.tsx): `frontend/src/components/guest-gallery-client.tsx`
- [Event listing](https://github.com/luckwoon02/picshare/blob/main/frontend/src/components/events-list-client.tsx): `frontend/src/components/events-list-client.tsx`

### API workflows

- [FastAPI app](https://github.com/luckwoon02/picshare/blob/main/backend/app/main.py): `backend/app/main.py`
- [Admin authentication](https://github.com/luckwoon02/picshare/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Event management](https://github.com/luckwoon02/picshare/blob/main/backend/app/api/events.py): `backend/app/api/events.py`
- [Photo processing](https://github.com/luckwoon02/picshare/blob/main/backend/app/api/photos.py): `backend/app/api/photos.py`
- [Guest matching](https://github.com/luckwoon02/picshare/blob/main/backend/app/api/guests.py): `backend/app/api/guests.py`

### Backend services

- [Settings](https://github.com/luckwoon02/picshare/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [Thumbnail generation](https://github.com/luckwoon02/picshare/blob/main/backend/app/services/thumbnail_service.py): `backend/app/services/thumbnail_service.py`
- [Face recognition](https://github.com/luckwoon02/picshare/blob/main/backend/app/services/rekognition_service.py): `backend/app/services/rekognition_service.py`
- [Photo storage service](https://github.com/luckwoon02/picshare/blob/main/backend/app/services/s3_service.py): `backend/app/services/s3_service.py`

### Storage and recovery

- [SQLite records](https://github.com/luckwoon02/picshare/blob/main/backend/app/services/db.py): `backend/app/services/db.py`
- [Recovery worker](https://github.com/luckwoon02/picshare/blob/main/backend/cron_worker.py): `backend/cron_worker.py`
- [Recovery tasks](https://github.com/luckwoon02/picshare/blob/main/backend/app/services/recovery.py): `backend/app/services/recovery.py`

### Other components

- **Admin**
- **Guest**
- **AWS S3**
- **AWS Rekognition**

## Connections

- Admin → Admin portal: manages events (evidence: `README.md`)
- Guest → Guest portal: submits selfie (evidence: `README.md`)
- Guest portal → Guest gallery: views matches (evidence: `README.md`)
- Guest → Event listing: browses events (evidence: `README.md`)
- Admin portal → FastAPI app: uses API
- Guest portal → FastAPI app: uses API
- Guest gallery → FastAPI app: requests gallery
- Event listing → FastAPI app: requests events
- FastAPI app → Admin authentication: registers router (evidence: `backend/app/main.py`)
- FastAPI app → Event management: registers router (evidence: `backend/app/main.py`)
- FastAPI app → Photo processing: registers router (evidence: `backend/app/main.py`)
- FastAPI app → Guest matching: registers router (evidence: `backend/app/main.py`)
- FastAPI app → SQLite records: opens connection (evidence: `backend/app/main.py`)
- Admin authentication → Settings: reads settings (evidence: `backend/app/api/auth.py`)
- Event management → SQLite records: reads and writes (evidence: `backend/app/api/events.py`)
- Event management → Face recognition: deletes collection (evidence: `backend/app/api/events.py`)
- Event management → Photo storage service: checks and deletes storage (evidence: `backend/app/api/events.py`)
- Photo processing → SQLite records: reads and writes (evidence: `backend/app/api/photos.py`)
- Photo processing → Photo storage service: stores and serves photos (evidence: `backend/app/api/photos.py`)
- Photo processing → Face recognition: indexes faces (evidence: `backend/app/api/photos.py`)
- Photo processing → Thumbnail generation: generates thumbnails (evidence: `backend/app/api/photos.py`)
- Guest matching → SQLite records: reads and writes (evidence: `backend/app/api/guests.py`)
- Guest matching → Face recognition: searches selfie (evidence: `backend/app/api/guests.py`)
- Guest matching → Photo storage service: creates gallery URLs (evidence: `backend/app/api/guests.py`)
- Photo storage service → AWS S3: uploads and signs URLs (evidence: `backend/app/services/s3_service.py`)
- Face recognition → AWS Rekognition: indexes and searches faces (evidence: `backend/app/services/rekognition_service.py`)
- Recovery worker → SQLite records: connects to (evidence: `backend/cron_worker.py`)
- Recovery worker → Recovery tasks: runs tasks (evidence: `backend/cron_worker.py`)
- Recovery tasks → SQLite records: repairs records (evidence: `backend/app/services/recovery.py`)
