# shanki21/pixdrive architecture

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

- Interactive diagram: https://gitdiagram.com/shanki21/pixdrive
- Repository: https://github.com/shanki21/pixdrive

## Overview

Pixdrive is a cloud-backed photo gallery and lightweight drive. Owners authenticate by OTP, manage galleries and media in the dashboard, then share public or PIN-protected galleries for visitors to view, download, review, and generate visits; QR access and custom domains extend sharing. The graph preserves billing, analytics, and settings as supporting capabilities. API and library links are limited to relationships shown in excerpts, the source index, or README; several feature routes are represented by their exact directories because their implementations were not sampled.

Main entry points: [`src/app/api/galleries`](https://github.com/shanki21/pixdrive/tree/main/src/app/api/galleries) (Gallery management API), [`src/lib/prisma.ts`](https://github.com/shanki21/pixdrive/blob/main/src/lib/prisma.ts) (PostgreSQL data), [`src/app/api/disk`](https://github.com/shanki21/pixdrive/tree/main/src/app/api/disk) (Public gallery API), [`src/modules/user/controller.ts`](https://github.com/shanki21/pixdrive/blob/main/src/modules/user/controller.ts) (OTP authentication API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_dashboard["Owner dashboard"]
  node_drive_ui["Drive management UI"]
  node_public_gallery["Shared gallery view"]
  node_studio["Studio photo requests"]
  node_auth_ui["Login and signup"]
end

subgraph group_gallery["Gallery workflows"]
  node_gallery_api["Gallery management API"]
  node_disk_api["Public gallery API"]
  node_photo_api["Photo management API"]
  node_review_api["Reviews and comments"]
  node_visit_api["Visit analytics API"]
  node_qr_api["QR generation API"]
  node_domain_api["Custom domain API"]
end

subgraph group_identity["Identity and access"]
  node_auth_api["OTP authentication API<br/>[controller.ts]"]
  node_auth_service["OTP account service<br/>[service.ts]"]
  node_auth_repository["User repository<br/>[repository.ts]"]
  node_session["Session handling<br/>[session.ts]"]
  node_otp_store["OTP persistence<br/>[otp-store.ts]"]
end

subgraph group_platform["Platform services"]
  node_config["Gallery settings<br/>[gallery-config.ts]"]
  node_pin_access["PIN access control"]
  node_api_wrapper["API error handling<br/>[withApiHandler.ts]"]
  node_rate_limit["Rate limiting<br/>[rate-limit.ts]"]
  node_throttle["IP throttling<br/>[ip-throttle.ts]"]
  node_retry["Retrying HTTP client<br/>[fetchWithRetry.ts]"]
  node_database[("PostgreSQL data<br/>[prisma.ts]")]
  node_media_storage["Image storage<br/>[storage.ts]"]
  node_cloudinary["Cloudinary assets<br/>[cloudinary.ts]"]
  node_r2["R2 storage<br/>[r2.ts]"]
end

subgraph group_commerce["Billing and insights"]
  node_billing_api["Billing API"]
  node_billing["Plans and entitlements<br/>[billing.ts]"]
  node_analytics_api["Analytics API<br/>[route.ts]"]
  node_product_analytics["Product analytics"]
  node_stripe["Stripe payments<br/>[stripe.ts]"]
end

node_owners(("Gallery owners"))
node_visitors(("Gallery visitors"))

node_owners -->|"sign in"| node_auth_ui
node_owners -->|"manage galleries"| node_dashboard
node_dashboard -->|"renders"| node_drive_ui
node_drive_ui -.->|"manages"| node_gallery_api
node_visitors -->|"open shared link"| node_public_gallery
node_public_gallery -.->|"loads gallery"| node_disk_api
node_visitors -->|"request photos"| node_studio
node_auth_ui -.->|"requests OTP"| node_auth_api
node_auth_api -->|"verifies OTP"| node_auth_service
node_auth_service -->|"loads user"| node_auth_repository
node_auth_service -->|"checks code"| node_otp_store
node_auth_api -->|"sets cookie"| node_session
node_gallery_api -->|"reads identity"| node_session
node_gallery_api -->|"checks allowance"| node_billing
node_gallery_api -->|"normalizes settings"| node_config
node_gallery_api -->|"reads and writes"| node_database
node_disk_api -->|"verifies PIN"| node_pin_access
node_disk_api -->|"limits unlocks"| node_throttle
node_disk_api -->|"fetches download assets"| node_retry
node_disk_api -.->|"loads gallery data"| node_database
node_photo_api -.->|"stores media"| node_media_storage
node_media_storage -->|"uses provider"| node_cloudinary
node_media_storage -->|"uses provider"| node_r2
node_review_api -.->|"persists reviews"| node_database
node_visit_api -.->|"records visits"| node_database
node_qr_api -->|"fetches with retry"| node_retry
node_domain_api -.->|"manages domains"| node_database
node_billing_api -->|"checks plans"| node_billing
node_billing_api -->|"starts checkout"| node_stripe
node_billing -->|"reads subscriptions"| node_database
node_analytics_api -->|"reads identity"| node_session
node_analytics_api -->|"queries metrics"| node_database
node_rate_limit -->|"checks requests"| node_throttle
node_throttle -->|"calls remote throttle"| node_retry
node_gallery_api -.->|"wraps handlers"| node_api_wrapper
node_auth_api -->|"wraps handlers"| node_api_wrapper
node_billing_api -->|"tracks events"| node_product_analytics

click node_dashboard "https://github.com/shanki21/pixdrive/tree/main/src/app/dashboard"
click node_drive_ui "https://github.com/shanki21/pixdrive/tree/main/src/components/drive"
click node_public_gallery "https://github.com/shanki21/pixdrive/tree/main/src/app/disk/%5Bslug%5D"
click node_studio "https://github.com/shanki21/pixdrive/tree/main/src/app/studio/%5BownerId%5D/%5Bslug%5D/get-photos"
click node_auth_ui "https://github.com/shanki21/pixdrive/tree/main/src/app/login"
click node_gallery_api "https://github.com/shanki21/pixdrive/tree/main/src/app/api/galleries"
click node_disk_api "https://github.com/shanki21/pixdrive/tree/main/src/app/api/disk"
click node_photo_api "https://github.com/shanki21/pixdrive/tree/main/src/app/api/photos"
click node_review_api "https://github.com/shanki21/pixdrive/tree/main/src/app/api/galleries/%5Bid%5D/reviews"
click node_visit_api "https://github.com/shanki21/pixdrive/tree/main/src/app/api/galleries/%5Bid%5D/visit"
click node_qr_api "https://github.com/shanki21/pixdrive/tree/main/src/app/api/qr"
click node_domain_api "https://github.com/shanki21/pixdrive/tree/main/src/app/api/custom-domains"
click node_auth_api "https://github.com/shanki21/pixdrive/blob/main/src/modules/user/controller.ts"
click node_auth_service "https://github.com/shanki21/pixdrive/blob/main/src/modules/user/service.ts"
click node_auth_repository "https://github.com/shanki21/pixdrive/blob/main/src/modules/user/repository.ts"
click node_session "https://github.com/shanki21/pixdrive/blob/main/src/lib/session.ts"
click node_config "https://github.com/shanki21/pixdrive/blob/main/src/lib/gallery-config.ts"
click node_pin_access "https://github.com/shanki21/pixdrive/blob/main/src/lib/gallery-pin-access.ts"
click node_api_wrapper "https://github.com/shanki21/pixdrive/blob/main/src/lib/withApiHandler.ts"
click node_rate_limit "https://github.com/shanki21/pixdrive/blob/main/src/lib/rate-limit.ts"
click node_throttle "https://github.com/shanki21/pixdrive/blob/main/src/lib/ip-throttle.ts"
click node_retry "https://github.com/shanki21/pixdrive/blob/main/src/lib/fetchWithRetry.ts"
click node_database "https://github.com/shanki21/pixdrive/blob/main/src/lib/prisma.ts"
click node_media_storage "https://github.com/shanki21/pixdrive/blob/main/src/lib/storage.ts"
click node_cloudinary "https://github.com/shanki21/pixdrive/blob/main/src/lib/cloudinary.ts"
click node_r2 "https://github.com/shanki21/pixdrive/blob/main/src/lib/r2.ts"
click node_otp_store "https://github.com/shanki21/pixdrive/blob/main/src/lib/otp-store.ts"
click node_billing_api "https://github.com/shanki21/pixdrive/tree/main/src/app/api/billing"
click node_billing "https://github.com/shanki21/pixdrive/blob/main/src/lib/billing.ts"
click node_analytics_api "https://github.com/shanki21/pixdrive/blob/main/src/app/api/analytics/route.ts"
click node_product_analytics "https://github.com/shanki21/pixdrive/blob/main/src/lib/product-analytics.ts"
click node_stripe "https://github.com/shanki21/pixdrive/blob/main/src/lib/stripe.ts"

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_dashboard,node_drive_ui,node_public_gallery,node_studio,node_auth_ui toneBlue
class node_gallery_api,node_disk_api,node_photo_api,node_review_api,node_visit_api,node_qr_api,node_domain_api toneAmber
class node_auth_api,node_auth_service,node_auth_repository,node_session,node_otp_store toneMint
class node_config,node_pin_access,node_api_wrapper,node_rate_limit,node_throttle,node_retry,node_database,node_media_storage,node_cloudinary,node_r2 toneRose
class node_billing_api,node_billing,node_analytics_api,node_product_analytics,node_stripe,node_owners,node_visitors toneIndigo
```

## Components

### User experience

- [Owner dashboard](https://github.com/shanki21/pixdrive/tree/main/src/app/dashboard): `src/app/dashboard`
- [Drive management UI](https://github.com/shanki21/pixdrive/tree/main/src/components/drive): `src/components/drive`
- [Shared gallery view](https://github.com/shanki21/pixdrive/tree/main/src/app/disk/%5Bslug%5D): `src/app/disk/[slug]`
- [Studio photo requests](https://github.com/shanki21/pixdrive/tree/main/src/app/studio/%5BownerId%5D/%5Bslug%5D/get-photos): `src/app/studio/[ownerId]/[slug]/get-photos`
- [Login and signup](https://github.com/shanki21/pixdrive/tree/main/src/app/login): `src/app/login`

### Gallery workflows

- [Gallery management API](https://github.com/shanki21/pixdrive/tree/main/src/app/api/galleries): `src/app/api/galleries`
- [Public gallery API](https://github.com/shanki21/pixdrive/tree/main/src/app/api/disk): `src/app/api/disk`
- [Photo management API](https://github.com/shanki21/pixdrive/tree/main/src/app/api/photos): `src/app/api/photos`
- [Reviews and comments](https://github.com/shanki21/pixdrive/tree/main/src/app/api/galleries/%5Bid%5D/reviews): `src/app/api/galleries/[id]/reviews`
- [Visit analytics API](https://github.com/shanki21/pixdrive/tree/main/src/app/api/galleries/%5Bid%5D/visit): `src/app/api/galleries/[id]/visit`
- [QR generation API](https://github.com/shanki21/pixdrive/tree/main/src/app/api/qr): `src/app/api/qr`
- [Custom domain API](https://github.com/shanki21/pixdrive/tree/main/src/app/api/custom-domains): `src/app/api/custom-domains`

### Identity and access

- [OTP authentication API](https://github.com/shanki21/pixdrive/blob/main/src/modules/user/controller.ts): `src/modules/user/controller.ts`
- [OTP account service](https://github.com/shanki21/pixdrive/blob/main/src/modules/user/service.ts): `src/modules/user/service.ts`
- [User repository](https://github.com/shanki21/pixdrive/blob/main/src/modules/user/repository.ts): `src/modules/user/repository.ts`
- [Session handling](https://github.com/shanki21/pixdrive/blob/main/src/lib/session.ts): `src/lib/session.ts`
- [OTP persistence](https://github.com/shanki21/pixdrive/blob/main/src/lib/otp-store.ts): `src/lib/otp-store.ts`

### Platform services

- [Gallery settings](https://github.com/shanki21/pixdrive/blob/main/src/lib/gallery-config.ts): `src/lib/gallery-config.ts`
- [PIN access control](https://github.com/shanki21/pixdrive/blob/main/src/lib/gallery-pin-access.ts): `src/lib/gallery-pin-access.ts`
- [API error handling](https://github.com/shanki21/pixdrive/blob/main/src/lib/withApiHandler.ts): `src/lib/withApiHandler.ts`
- [Rate limiting](https://github.com/shanki21/pixdrive/blob/main/src/lib/rate-limit.ts): `src/lib/rate-limit.ts`
- [IP throttling](https://github.com/shanki21/pixdrive/blob/main/src/lib/ip-throttle.ts): `src/lib/ip-throttle.ts`
- [Retrying HTTP client](https://github.com/shanki21/pixdrive/blob/main/src/lib/fetchWithRetry.ts): `src/lib/fetchWithRetry.ts`
- [PostgreSQL data](https://github.com/shanki21/pixdrive/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`
- [Image storage](https://github.com/shanki21/pixdrive/blob/main/src/lib/storage.ts): `src/lib/storage.ts`
- [Cloudinary assets](https://github.com/shanki21/pixdrive/blob/main/src/lib/cloudinary.ts): `src/lib/cloudinary.ts`
- [R2 storage](https://github.com/shanki21/pixdrive/blob/main/src/lib/r2.ts): `src/lib/r2.ts`

### Billing and insights

- [Billing API](https://github.com/shanki21/pixdrive/tree/main/src/app/api/billing): `src/app/api/billing`
- [Plans and entitlements](https://github.com/shanki21/pixdrive/blob/main/src/lib/billing.ts): `src/lib/billing.ts`
- [Analytics API](https://github.com/shanki21/pixdrive/blob/main/src/app/api/analytics/route.ts): `src/app/api/analytics/route.ts`
- [Product analytics](https://github.com/shanki21/pixdrive/blob/main/src/lib/product-analytics.ts): `src/lib/product-analytics.ts`
- [Stripe payments](https://github.com/shanki21/pixdrive/blob/main/src/lib/stripe.ts): `src/lib/stripe.ts`

### Other components

- **Gallery owners**
- **Gallery visitors**

## Connections

- Gallery owners → Login and signup: sign in (evidence: `README.md`)
- Gallery owners → Owner dashboard: manage galleries (evidence: `README.md`)
- Owner dashboard → Drive management UI: renders
- Drive management UI → Gallery management API: manages
- Gallery visitors → Shared gallery view: open shared link (evidence: `README.md`)
- Shared gallery view → Public gallery API: loads gallery
- Gallery visitors → Studio photo requests: request photos
- Login and signup → OTP authentication API: requests OTP
- OTP authentication API → OTP account service: verifies OTP (evidence: `src/modules/user/controller.ts`)
- OTP account service → User repository: loads user (evidence: `src/modules/user/service.ts`)
- OTP account service → OTP persistence: checks code (evidence: `src/modules/user/service.ts`)
- OTP authentication API → Session handling: sets cookie (evidence: `src/modules/user/controller.ts`)
- Gallery management API → Session handling: reads identity (evidence: `src/app/api/galleries/route.ts`)
- Gallery management API → Plans and entitlements: checks allowance (evidence: `src/app/api/galleries/route.ts`)
- Gallery management API → Gallery settings: normalizes settings (evidence: `src/app/api/galleries/route.ts`)
- Gallery management API → PostgreSQL data: reads and writes (evidence: `src/app/api/galleries/route.ts`)
- Public gallery API → PIN access control: verifies PIN (evidence: `src/app/api/disk/route.ts`)
- Public gallery API → IP throttling: limits unlocks (evidence: `src/app/api/disk/route.ts`)
- Public gallery API → Retrying HTTP client: fetches download assets (evidence: `src/app/api/disk/route.ts`)
- Public gallery API → PostgreSQL data: loads gallery data (evidence: `src/app/api/disk/route.ts`)
- Photo management API → Image storage: stores media
- Image storage → Cloudinary assets: uses provider (evidence: `src/lib/storage.ts`)
- Image storage → R2 storage: uses provider (evidence: `src/lib/storage.ts`)
- Reviews and comments → PostgreSQL data: persists reviews
- Visit analytics API → PostgreSQL data: records visits
- QR generation API → Retrying HTTP client: fetches with retry (evidence: `src/app/api/qr/route.ts`)
- Custom domain API → PostgreSQL data: manages domains (evidence: `src/app/api/custom-domains/route.ts`)
- Billing API → Plans and entitlements: checks plans (evidence: `src/app/api/billing/checkout/route.ts`)
- Billing API → Stripe payments: starts checkout (evidence: `src/app/api/billing/checkout/route.ts`)
- Plans and entitlements → PostgreSQL data: reads subscriptions (evidence: `src/lib/billing.ts`)
- Analytics API → Session handling: reads identity (evidence: `src/app/api/analytics/route.ts`)
- Analytics API → PostgreSQL data: queries metrics (evidence: `src/app/api/analytics/route.ts`)
- Rate limiting → IP throttling: checks requests (evidence: `src/lib/rate-limit.ts`)
- IP throttling → Retrying HTTP client: calls remote throttle (evidence: `src/lib/ip-throttle.ts`)
- Gallery management API → API error handling: wraps handlers (evidence: `src/app/api/galleries/route.ts`)
- OTP authentication API → API error handling: wraps handlers (evidence: `src/modules/user/controller.ts`)
- Billing API → Product analytics: tracks events (evidence: `src/app/api/billing/webhook/route.ts`)
