# aswin-haridas/bigshelf architecture

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

- Interactive diagram: https://gitdiagram.com/aswin-haridas/bigshelf
- Repository: https://github.com/aswin-haridas/bigshelf

## Overview

BigShelf is a photo library with a React frontend and FastAPI backend. Users can register or sign in, upload and browse photos, preview and delete them, and organize them into albums; the documented backend also provides session rotation, S3-backed media, and cleanup of queued deletions. The graph follows sampled frontend requests and authentication/session code, plus capabilities stated in the backend API description. Album and photo endpoint internals were not sampled, so their detailed wiring is not inferred.

Main entry points: [`frontend/src/App.tsx`](https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/App.tsx) (Route application), [`frontend/src/lib/api.ts`](https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/lib/api.ts) (HTTP client), [`backend/app/core/database.py`](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/core/database.py) (Database sessions and engine), [`backend/app/api/v1/endpoints/auth.py`](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/api/v1/endpoints/auth.py) (Authentication endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Route application<br/>[App.tsx]"]
  node_auth_ui["Login and registration"]
  node_auth_state["Authentication state<br/>[authStore.ts]"]
  node_home_ui["Photo library view<br/>[home.tsx]"]
  node_upload["Batch upload<br/>[useUpload.ts]"]
  node_preview["Photo preview<br/>[preview.tsx]"]
  node_albums_ui["Album view<br/>[albums.tsx]"]
  node_api_client["HTTP client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_router["Versioned API router<br/>[api.py]"]
  node_auth_endpoint["Authentication endpoints<br/>[auth.py]"]
  node_security["Token and password security<br/>[security.py]"]
  node_user_crud["User persistence<br/>[crud_user.py]"]
  node_session_crud["Session persistence<br/>[crud_session.py]"]
end

subgraph group_media["Photo organization"]
  node_photo_endpoint["Photo endpoints<br/>[photos.py]"]
  node_album_endpoint["Album endpoints<br/>[albums.py]"]
  node_photo_crud["Photo persistence<br/>[crud_photo.py]"]
  node_album_crud["Album persistence<br/>[crud_album.py]"]
  node_imaging["Image validation and thumbnails<br/>[imaging.py]"]
end

subgraph group_persistence["Persistence and cleanup"]
  node_database_layer["Database sessions and engine<br/>[database.py]"]
  node_sql_store[("Relational database")]
  node_s3["S3 storage client<br/>[s3.py]"]
  node_object_store[("S3-compatible object storage")]
  node_deletion_worker["Queued object cleanup<br/>[deletion_worker.py]"]
  node_deletion_model["Deletion queue records<br/>[deletion_queue.py]"]
end

node_person(("Library user"))

node_person -->|"uses"| node_app
node_app -->|"routes to"| node_auth_ui
node_app -->|"routes to"| node_home_ui
node_app -->|"routes to"| node_preview
node_app -->|"routes to"| node_albums_ui
node_auth_ui -->|"submits credentials"| node_auth_state
node_auth_state -->|"sends requests"| node_api_client
node_upload -->|"uploads batches"| node_api_client
node_preview -->|"deletes photo"| node_api_client
node_api_client -->|"sends API requests"| node_api_app
node_api_app -->|"includes router"| node_api_router
node_auth_endpoint -->|"looks up users"| node_user_crud
node_auth_endpoint -->|"manages sessions"| node_session_crud
node_auth_endpoint -->|"verifies and issues tokens"| node_security
node_session_crud -->|"queries sessions"| node_database_layer
node_user_crud -->|"queries users"| node_database_layer
node_photo_endpoint -->|"manages photo records"| node_photo_crud
node_photo_endpoint -->|"validates and transforms"| node_imaging
node_photo_endpoint -->|"stores and retrieves media"| node_s3
node_album_endpoint -->|"manages albums"| node_album_crud
node_database_layer -->|"reads and writes"| node_sql_store
node_s3 -->|"reads and writes objects"| node_object_store
node_deletion_worker -->|"loads queued keys"| node_deletion_model
node_deletion_worker -->|"deletes objects"| node_s3
node_deletion_worker -->|"commits queue changes"| node_database_layer

click node_app "https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/App.tsx"
click node_auth_ui "https://github.com/aswin-haridas/bigshelf/tree/main/frontend/src/modules/auth"
click node_auth_state "https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/stores/authStore.ts"
click node_home_ui "https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/modules/home/home.tsx"
click node_upload "https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/modules/home/useUpload.ts"
click node_preview "https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/modules/home/preview.tsx"
click node_albums_ui "https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/modules/albums/albums.tsx"
click node_api_client "https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/lib/api.ts"
click node_api_app "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/main.py"
click node_api_router "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/api/v1/api.py"
click node_auth_endpoint "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_photo_endpoint "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/api/v1/endpoints/photos.py"
click node_album_endpoint "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/api/v1/endpoints/albums.py"
click node_security "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/core/security.py"
click node_user_crud "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/crud/crud_user.py"
click node_session_crud "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/crud/crud_session.py"
click node_photo_crud "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/crud/crud_photo.py"
click node_album_crud "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/crud/crud_album.py"
click node_imaging "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/core/imaging.py"
click node_database_layer "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/core/database.py"
click node_s3 "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/core/s3.py"
click node_deletion_worker "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/services/deletion_worker.py"
click node_deletion_model "https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/models/deletion_queue.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_app,node_auth_ui,node_auth_state,node_home_ui,node_upload,node_preview,node_albums_ui,node_api_client,node_person toneBlue
class node_api_app,node_api_router,node_auth_endpoint,node_security,node_user_crud,node_session_crud toneAmber
class node_photo_endpoint,node_album_endpoint,node_photo_crud,node_album_crud,node_imaging toneMint
class node_database_layer,node_sql_store,node_s3,node_object_store,node_deletion_worker,node_deletion_model toneRose
```

## Components

### Web client

- [Route application](https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Login and registration](https://github.com/aswin-haridas/bigshelf/tree/main/frontend/src/modules/auth): `frontend/src/modules/auth`
- [Authentication state](https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/stores/authStore.ts): `frontend/src/stores/authStore.ts`
- [Photo library view](https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/modules/home/home.tsx): `frontend/src/modules/home/home.tsx`
- [Batch upload](https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/modules/home/useUpload.ts): `frontend/src/modules/home/useUpload.ts`
- [Photo preview](https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/modules/home/preview.tsx): `frontend/src/modules/home/preview.tsx`
- [Album view](https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/modules/albums/albums.tsx): `frontend/src/modules/albums/albums.tsx`
- [HTTP client](https://github.com/aswin-haridas/bigshelf/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and identity

- [FastAPI application](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/main.py): `backend/app/main.py`
- [Versioned API router](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/api/v1/api.py): `backend/app/api/v1/api.py`
- [Authentication endpoints](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [Token and password security](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [User persistence](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/crud/crud_user.py): `backend/app/crud/crud_user.py`
- [Session persistence](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/crud/crud_session.py): `backend/app/crud/crud_session.py`

### Photo organization

- [Photo endpoints](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/api/v1/endpoints/photos.py): `backend/app/api/v1/endpoints/photos.py`
- [Album endpoints](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/api/v1/endpoints/albums.py): `backend/app/api/v1/endpoints/albums.py`
- [Photo persistence](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/crud/crud_photo.py): `backend/app/crud/crud_photo.py`
- [Album persistence](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/crud/crud_album.py): `backend/app/crud/crud_album.py`
- [Image validation and thumbnails](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/core/imaging.py): `backend/app/core/imaging.py`

### Persistence and cleanup

- [Database sessions and engine](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- **Relational database**
- [S3 storage client](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/core/s3.py): `backend/app/core/s3.py`
- **S3-compatible object storage**
- [Queued object cleanup](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/services/deletion_worker.py): `backend/app/services/deletion_worker.py`
- [Deletion queue records](https://github.com/aswin-haridas/bigshelf/blob/main/backend/app/models/deletion_queue.py): `backend/app/models/deletion_queue.py`

### Other components

- **Library user**

## Connections

- Library user → Route application: uses
- Route application → Login and registration: routes to
- Route application → Photo library view: routes to
- Route application → Photo preview: routes to
- Route application → Album view: routes to
- Login and registration → Authentication state: submits credentials
- Authentication state → HTTP client: sends requests
- Batch upload → HTTP client: uploads batches
- Photo preview → HTTP client: deletes photo
- HTTP client → FastAPI application: sends API requests
- FastAPI application → Versioned API router: includes router
- Authentication endpoints → User persistence: looks up users
- Authentication endpoints → Session persistence: manages sessions
- Authentication endpoints → Token and password security: verifies and issues tokens
- Session persistence → Database sessions and engine: queries sessions
- User persistence → Database sessions and engine: queries users
- Photo endpoints → Photo persistence: manages photo records
- Photo endpoints → Image validation and thumbnails: validates and transforms
- Photo endpoints → S3 storage client: stores and retrieves media
- Album endpoints → Album persistence: manages albums
- Database sessions and engine → Relational database: reads and writes
- S3 storage client → S3-compatible object storage: reads and writes objects
- Queued object cleanup → Deletion queue records: loads queued keys
- Queued object cleanup → S3 storage client: deletes objects
- Queued object cleanup → Database sessions and engine: commits queue changes