# rajeshdavidbabu/s3-upload-thing architecture

> Architecture diagram of the GitHub repository rajeshdavidbabu/s3-upload-thing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rajeshdavidbabu/s3-upload-thing
- Repository: https://github.com/rajeshdavidbabu/s3-upload-thing

## Overview

##### Project type and purpose
- This is a full-stack, self-hostable file-upload web application built on Next.js (the `/app` directory with React/TSX pages).
- It provides drag-and-drop uploads (Uppy uploader), paginated galleries, thumbnail generation, file downloads, and Google OAuth via NextAuth.
- Backend logic lives in Next.js API routes (`app/api/*`), a custom AWS Lambda for thumbnailing, and a PostgreSQL database accessed via Drizzle ORM.

##### File structure
Top-level directories:
- `app/` – Next.js 13 “app router” pages, layouts, and API routes.
- `app/page.tsx`, `app/layout.tsx` – root page and layout
- `app/(protected)` – dashboard, settings, usage pages behind authentication
- `app/api/auth/[...nextauth]/route.ts` – NextAuth handlers
- `app/api/files/[key]/route.ts`, `app/api/thumbnails/[key]/route.ts` – file fetch & thumbnail endpoints
- `components/` – shared UI building blocks (shadcn/ui wrappers, uploader components, general navigation, helpers).
- `db/` & `lib/db/` – Drizzle configuration, migration scripts, TypeScript schema, and data-access helpers (`db/api/*.ts`, `lib/db/action.ts`).
- `lib/s3/` – S3 upload/download logic.
- `lambda/` – standalone AWS Lambda function (zipped) that’s triggered (e.g., via S3 event) to generate thumbnails.
- `auth.ts` & `auth.config.ts` – NextAuth configuration.
- `config/` – site-level constants.
- Root config files: `next.config.mjs`, `tsconfig.json`, `tailwind.config.ts`, ESLint, PostCSS.

##### README insights
- Tech stack: Next.js, shadcn/ui, Uppy, AWS S3, Zod, Drizzle + PostgreSQL, NextAuth Google OAuth.
- Features: drag-drop, pagination, filters, thumbnails, downloads.
- Architecture section shows high-level upload/download flows.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Browser"
        direction TB
        User["User"]:::user
        Uppy["Uppy Uploader\ncomponents/uploader/uppy-uploader.tsx"]:::frontend
        FileGallery["File Gallery UI\ncomponents/uploader/file-gallery.tsx"]:::frontend
        FileItem["Individual File Item UI\ncomponents/uploader/file-item.tsx"]:::frontend
        Pagination["Pagination Bar\ncomponents/general/pagination-bar.tsx"]:::frontend
    end

    %% Server Layer
    subgraph "Next.js Server"
        direction TB
        RootPage["App Root Page\napp/page.tsx"]:::server
        Layout["App Layout\napp/layout.tsx"]:::server
        Protected["Protected Routes\napp/(protected)/*"]:::server
        NextAuthRoute["NextAuth API Route\napp/api/auth/[...nextauth]/route.ts"]:::api
        AuthConfig["Google OAuth Config\nauth.config.ts"]:::config
        AuthSetup["NextAuth Setup\nauth.ts"]:::config
        FilesAPI["File Upload & Download API\napp/api/files/[key]/route.ts"]:::api
        ThumbsAPI["Thumbnail Serve API\napp/api/thumbnails/[key]/route.ts"]:::api
        DrizzleSchema["Drizzle ORM Schema\ndb/schema.ts"]:::dbconfig
        DrizzleConfig["Drizzle Configuration\ndrizzle.config.ts"]:::dbconfig
        Migrations["Database Migrations\ndb/migrations/*"]:::dbconfig
        DBHelpers["Data Access Helpers\ndb/api/*.ts"]:::dbdata
        DBAction["Drizzle Action Helpers\nlib/db/action.ts"]:::dbdata
        S3Core["S3 Core Logic\nlib/s3/core.ts"]:::s3logic
        S3Action["S3 Action Helpers\nlib/s3/action.ts"]:::s3logic
    end

    %% AWS Layer
    subgraph "AWS Services"
        direction TB
        S3Bucket["AWS S3 Bucket"]:::s3
        LambdaIndex["Lambda Func Code\nlambda/index.mjs"]:::lambda
        LambdaZip["Lambda Deployment\nlambda/function.zip"]:::lambda
    end

    %% Database Layer
    subgraph "Database"
        Postgres["PostgreSQL Database"]:::db
    end

    %% External
    subgraph "External OAuth Provider"
        Google["Google OAuth"]:::external
    end

    %% Connections
    User --> Uppy
    User --> FileGallery
    User --> FileItem
    User --> Pagination

    Uppy -->|POST /api/files| FilesAPI
    FilesAPI -->|upload via lib/s3| S3Core
    S3Core --> S3Bucket
    FilesAPI -->|record metadata| DBHelpers
    DBHelpers --> Postgres

    S3Bucket -->|ObjectCreated event| LambdaIndex
    LambdaIndex --> S3Bucket

    FileGallery -->|GET /api/files| FilesAPI
    FilesAPI -->|Drizzle query| DBAction
    DBAction --> Postgres
    FilesAPI -->|presigned URLs| S3Action
    S3Action --> S3Bucket

    User -->|download click| FilesAPI
    User -->|fetch thumbnail| ThumbsAPI
    ThumbsAPI --> S3Action
    S3Action --> S3Bucket

    User -->|login| NextAuthRoute
    NextAuthRoute -->|redirect| Google
    Google -->|callback| NextAuthRoute
    NextAuthRoute -->|session store| Postgres

    %% Deployment flows
    DrizzleConfig --> Migrations
    Migrations -.-> Postgres

    %% Click Events
    click RootPage "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/app/page.tsx"
    click Layout "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/app/layout.tsx"
    click Protected "https://github.com/rajeshdavidbabu/s3-upload-thing/tree/master/app/(protected)/*"
    click NextAuthRoute "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/app/api/auth/[...nextauth]/route.ts"
    click AuthConfig "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/auth.config.ts"
    click AuthSetup "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/auth.ts"
    click FilesAPI "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/app/api/files/[key]/route.ts"
    click ThumbsAPI "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/app/api/thumbnails/[key]/route.ts"
    click DrizzleSchema "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/db/schema.ts"
    click DrizzleConfig "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/drizzle.config.ts"
    click Migrations "https://github.com/rajeshdavidbabu/s3-upload-thing/tree/master/db/migrations/*"
    click DBHelpers "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/db/api/*.ts"
    click DBAction "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/lib/db/action.ts"
    click S3Core "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/lib/s3/core.ts"
    click S3Action "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/lib/s3/action.ts"
    click LambdaIndex "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/lambda/index.mjs"
    click LambdaZip "https://github.com/rajeshdavidbabu/s3-upload-thing/blob/master/lambda/function.zip"

    %% Styles
    classDef user fill:#f9f,stroke:#333,stroke-width:1px
    classDef frontend fill:#bbf,stroke:#333,stroke-width:1px
    classDef server fill:#bfe,stroke:#333,stroke-width:1px
    classDef api fill:#8fb,stroke:#333,stroke-width:1px
    classDef config fill:#fcf,stroke:#333,stroke-width:1px
    classDef dbconfig fill:#dfd,stroke:#333,stroke-width:1px
    classDef dbdata fill:#dff,stroke:#333,stroke-width:1px
    classDef s3logic fill:#ffd,stroke:#333,stroke-width:1px
    classDef lambda fill:#fdd,stroke:#333,stroke-width:1px
    classDef s3 fill:#cff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef db fill:#cfc,stroke:#333,stroke-width:1px
    classDef external fill:#fcc,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
