📤 Upload Widget Server

A robust, high-performance Node.js API for seamless file management, powered by Fastify, Drizzle ORM, and Cloudflare R2.

---

📖 About The Project

Upload Widget Server is a backend solution designed to handle file uploads efficiently and securely. It solves the complexity of managing file storage, metadata, and retrieval by providing a clean API interface that integrates directly with Cloudflare R2 (S3-compatible storage) and PostgreSQL.

Whether you are building a dashboard, a social platform, or a content management system, this server provides the essential plumbing for your media assets.

✨ Key Features

• 🚀 High-Performance Uploads: Optimized handling of multipart/form-data using Fastify.
• ☁️ Cloud Storage Integration: Native support for Cloudflare R2 (via AWS SDK).
• 🗄️ Robust Data Management: PostgreSQL database with Drizzle ORM for type-safe queries.
• 🔍 Advanced Search & Filtering: Built-in pagination, sorting, and text search capabilities.
• 📊 Data Export: Generate CSV reports of your uploaded assets on the fly.
• 🛡️ Type Safety: End-to-end type validation with Zod and TypeScript.
• 🐳 Docker Ready: Containerized environment for easy deployment and development.

---

🛠️ Tech Stack

Core

• Node.js - Runtime environment
• TypeScript - Static typing
• Fastify - Web framework

Data & Storage

• PostgreSQL - Relational database
• Drizzle ORM - TypeScript ORM
• Cloudflare R2 - Object storage

Tools & DevOps

• Docker - Containerization
• Zod - Schema validation
• Vitest - Testing framework
• Biome - Linting & Formatting

---

🚀 Getting Started

Follow these steps to get your development environment running in less than 5 minutes.

Prerequisites

• Node.js (v20+ recommended)
• pnpm (Package Manager)
• Docker & Docker Compose

Installation

1. Clone the repository

   git clone https://github.com/christopherldo/upload-widget-server.git
   cd upload-widget-server

2. Install dependencies

   pnpm install

3. Configure Environment Variables Copy the example file and fill in your credentials (especially Cloudflare R2 details).

   cp .env.example .env

4. Start Database (Docker) Run the PostgreSQL container in the background.

   docker-compose up -d

5. Run Migrations Apply the database schema.

   pnpm db:migrate

---

🎮 Usage

Development Server

Start the server in watch mode:

pnpm dev

The server will start at http://localhost:3333.

API Documentation

Access the interactive Swagger/OpenAPI documentation at:

http://localhost:3333/docs

Key Commands

Command	Description
pnpm dev	Starts the development server with hot-reload
pnpm build	Builds the project for production
pnpm test	Runs the test suite with Vitest
pnpm db:generate	Generates SQL migrations from Drizzle schema
pnpm db:studio	Opens Drizzle Studio to view/edit data

Example Request

Upload an Image:

curl -X POST http://localhost:3333/uploads \
  -F "file=@/path/to/your/image.png"

Response (201 Created):

// No content (201)

---

📂 Project Structure

.
├── 📁 docker/               # Docker configuration and init scripts
├── 📁 src/
│   ├── 📁 app/              # Business logic & Use Cases
│   │   └── 📁 functions/    # Core functionality (upload, get, export)
│   ├── 📁 infra/            # Infrastructure layer
│   │   ├── 📁 db/           # Database setup (Drizzle schemas, migrations)
│   │   ├── 📁 http/         # HTTP server (Fastify routes, server setup)
│   │   └── 📁 storage/      # Storage implementation (S3/R2 client)
│   ├── 📁 shared/           # Shared utilities (Either pattern, types)
│   └── 📄 env.ts            # Environment variable validation
├── 📄 .env.example          # Environment variables template
├── 📄 docker-compose.yml    # Docker services
├── 📄 package.json          # Project dependencies
└── 📄 drizzle.config.ts     # Drizzle ORM config

---

🗺️ Roadmap

Based on the current codebase, here are some suggested improvements:

• Authentication: Add JWT or API Key authentication to protect endpoints.
• File Validation: Expand support for other file types (PDF, Docs) and add virus scanning.
• CDN Integration: Directly expose public URLs via a configured CDN domain.

---

_{Built with ❤️ by ChristopherLDO}