ImageFlow

A modern image management and distribution platform with automatic format optimization

Looking for a Serverless version? Check out CattoPic - ImageFlow's serverless implementation for Cloudflare Workers.

Introduction

ImageFlow is a full-stack image management platform that automatically optimizes images for different devices and browsers. It combines a high-performance Go backend with a modern Next.js frontend to provide intelligent image conversion, device-aware serving, and powerful filtering capabilities.

Preview

Architecture

graph TB
    subgraph Client["Client Layer"]
        Browser["Web Browser"]
        APIClient["API Client"]
    end

    subgraph Frontend["Frontend Container :3000"]
        NextJS["Next.js 14<br/>TypeScript + Tailwind CSS<br/>App Router"]
    end

    subgraph Backend["Backend Container :8686"]
        GoServer["Go HTTP Server"]
        ImageProc["Image Processor<br/>libvips"]
        WorkerPool["Worker Pool<br/>Async Processing"]
    end

    subgraph Storage["Storage Layer"]
        Redis[("Redis<br/>Metadata Store")]
        LocalFS["Local Filesystem"]
        S3["S3 Compatible<br/>Storage"]
    end

    Browser --> NextJS
    APIClient --> GoServer
    NextJS --> GoServer
    GoServer --> ImageProc
    GoServer --> WorkerPool
    WorkerPool --> ImageProc
    GoServer --> Redis
    GoServer --> LocalFS
    GoServer --> S3

Component Overview

Component	Technology	Description
Frontend	Next.js 14, TypeScript, Tailwind CSS	Modern web interface with drag-and-drop upload
Backend	Go 1.23+, libvips	High-performance image processing server
Metadata	Redis	Fast metadata storage with tag indexing
Storage	Local / S3	Flexible storage backend options

Features

Image Processing

Automatic conversion to WebP and AVIF formats
High-performance processing powered by libvips
Configurable quality and compression settings
Background worker pool for async processing
GIF preservation (maintains animation)

Intelligent Distribution

Device-aware orientation detection (portrait for mobile, landscape for desktop)
Browser-based format negotiation (AVIF > WebP > Original)
Multi-tag filtering with AND logic
Exclusion filters for sensitive content
Forced orientation override option

Storage Options

Local filesystem storage
S3-compatible object storage (AWS S3, MinIO, Cloudflare R2, etc.)
Organized directory structure by orientation and format

Security

API key authentication for management endpoints
Automatic cleanup of expired images
Configurable CORS policies
Sensitive content auto-exclusion from public APIs

Modern Frontend

Next.js 14 with App Router
Drag-and-drop batch upload
Dark mode support
Responsive masonry layout
Real-time upload progress

Deployment

Prerequisites

Docker and Docker Compose installed
Minimum 1GB RAM recommended
Sufficient disk space for image storage

Quick Start

# Clone the repository
git clone https://github.com/Yuri-NagaSaki/ImageFlow.git
cd ImageFlow

# Create configuration file
cp .env.example .env

# Edit configuration (see Configuration section below)
nano .env

# Start all services (using pre-built images)
docker-compose up -d

# Or build locally for development/testing
docker-compose -f docker-compose.build.yaml up --build -d

After deployment:

Frontend: http://localhost:3000
Backend API: http://localhost:8686

Service Architecture

The deployment includes three containers:

Service	Port	Description
imageflow-frontend	3000	Next.js web interface
imageflow-backend	8686	Go API server
imageflow-redis	6379	Metadata storage

Configuration

Create a .env file in the project root with the following settings:

Core Settings

Variable	Required	Default	Description
`API_KEY`	Yes	-	Authentication key for upload/management APIs
`STORAGE_TYPE`	No	`local`	Storage backend: `local` or `s3`
`LOCAL_STORAGE_PATH`	No	`static/images`	Path for local image storage
`DEBUG_MODE`	No	`false`	Enable debug logging

Redis Configuration

Variable	Required	Default	Description
`METADATA_STORE_TYPE`	No	`redis`	Metadata storage type
`REDIS_HOST`	No	`localhost`	Redis server hostname
`REDIS_PORT`	No	`6379`	Redis server port
`REDIS_PASSWORD`	No	-	Redis authentication password
`REDIS_DB`	No	`0`	Redis database number
`REDIS_TLS_ENABLED`	No	`false`	Enable TLS for Redis connection

S3 Configuration (when STORAGE_TYPE=s3)

Variable	Required	Default	Description
`S3_ENDPOINT`	Yes	-	S3 endpoint URL
`S3_REGION`	Yes	-	S3 region
`S3_ACCESS_KEY`	Yes	-	S3 access key
`S3_SECRET_KEY`	Yes	-	S3 secret key
`S3_BUCKET`	Yes	-	S3 bucket name
`CUSTOM_DOMAIN`	No	-	Custom domain for S3 assets

Image Processing

Variable	Required	Default	Description
`MAX_UPLOAD_COUNT`	No	`20`	Maximum images per upload request
`IMAGE_QUALITY`	No	`80`	Conversion quality (1-100)
`WORKER_THREADS`	No	`4`	libvips parallel processing threads
`WORKER_POOL_SIZE`	No	`4`	Concurrent image processing workers
`SPEED`	No	`5`	Encoding speed (0=slowest/best, 8=fastest)

Frontend Configuration

Variable	Required	Default	Description
`NEXT_PUBLIC_API_URL`	No	-	Backend API URL for frontend
`NEXT_PUBLIC_REMOTE_PATTERNS`	No	-	Allowed image domains (comma-separated)

Example Configuration

# Core
API_KEY=your-secure-api-key-here
STORAGE_TYPE=local
DEBUG_MODE=false

# Redis
METADATA_STORE_TYPE=redis
REDIS_HOST=redis
REDIS_PORT=6379

# Image Processing
IMAGE_QUALITY=80
WORKER_THREADS=4
WORKER_POOL_SIZE=4
MAX_UPLOAD_COUNT=20

# Frontend 
NEXT_PUBLIC_API_URL=http://backend:8686
NEXT_PUBLIC_REMOTE_PATTERNS=http://backend:8686,https://s3.url

API Reference

Public Endpoints

Get Random Image

GET /api/random

Query Parameters:

Parameter	Type	Description
`tag`	string	Filter by single tag
`tags`	string	Filter by multiple tags (comma-separated, AND logic)
`exclude`	string	Exclude images with these tags (comma-separated)
`orientation`	string	Force orientation: `portrait` or `landscape`
`format`	string	Preferred format: `avif`, `webp`, or `original`

Examples:

# Basic random image
curl "http://localhost:8686/api/random"

# Filter by tags
curl "http://localhost:8686/api/random?tags=nature,landscape"

# Exclude sensitive content
curl "http://localhost:8686/api/random?tag=wallpaper&exclude=nsfw,private"

# Force portrait orientation
curl "http://localhost:8686/api/random?orientation=portrait&format=webp"

Authenticated Endpoints

All management endpoints require the Authorization header:

Authorization: Bearer your-api-key

Upload Images

POST /api/upload
Content-Type: multipart/form-data

Field	Type	Description
`images[]`	file	Image files to upload (multiple allowed)
`tags`	string	Comma-separated tags
`expiryMinutes`	number	Auto-delete after N minutes (optional)

List Images

GET /api/images

Parameter	Type	Description
`page`	number	Page number
`tag`	string	Filter by tag
`orientation`	string	Filter by orientation

Delete Image

POST /api/delete-image
Content-Type: application/json

{"id": "image-uuid"}

Get All Tags

GET /api/tags

Get Configuration

GET /api/config

Project Structure

ImageFlow/
├── main.go                 # Application entry point
├── config/                 # Configuration management
├── handlers/               # HTTP request handlers
│   ├── auth.go            # Authentication middleware
│   ├── upload.go          # Image upload handler
│   ├── random.go          # Random image API
│   ├── list.go            # Image listing
│   ├── delete.go          # Image deletion
│   └── tags.go            # Tag management
├── utils/                  # Core utilities
│   ├── converter_bimg.go  # libvips image processing
│   ├── storage.go         # Storage interface
│   ├── redis.go           # Redis operations
│   ├── worker_pool.go     # Async processing
│   └── cleaner.go         # Expired image cleanup
├── frontend/              # Next.js application
│   ├── app/               # App Router pages
│   ├── components/        # React components
│   └── utils/             # Frontend utilities
├── docker-compose.yaml       # Docker deployment (pre-built images)
├── docker-compose.build.yaml # Docker deployment (local build)
├── Dockerfile.backend        # Backend container
├── Dockerfile.frontend       # Frontend container
└── .env.example           # Configuration template

Image Storage Structure

static/images/
├── original/
│   ├── landscape/         # Original landscape images
│   └── portrait/          # Original portrait images
├── landscape/
│   ├── webp/              # WebP converted landscape
│   └── avif/              # AVIF converted landscape
├── portrait/
│   ├── webp/              # WebP converted portrait
│   └── avif/              # AVIF converted portrait
└── gif/                   # GIF files (preserved)

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

libvips - High-performance image processing library
bimg - Go bindings for libvips
Next.js - React framework for production
Tailwind CSS - Utility-first CSS framework
Redis - In-memory data store

Name		Name	Last commit message	Last commit date
Latest commit History 282 Commits
.github		.github
config		config
docs/img		docs/img
favicon		favicon
frontend		frontend
handlers		handlers
scripts		scripts
utils		utils
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile.backend		Dockerfile.backend
Dockerfile.frontend		Dockerfile.frontend
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
docker-compose.build.yaml		docker-compose.build.yaml
docker-compose.yaml		docker-compose.yaml
go.mod		go.mod
go.sum		go.sum
main.go		main.go

License

ivoryjin/ImageFlow

Folders and files

Latest commit

History

Repository files navigation

ImageFlow

Introduction

Preview

Architecture

Component Overview

Features

Image Processing

Intelligent Distribution

Storage Options

Security

Modern Frontend

Deployment

Prerequisites

Quick Start

Service Architecture

Configuration

Core Settings

Redis Configuration

S3 Configuration (when STORAGE_TYPE=s3)

Image Processing

Frontend Configuration

Example Configuration

API Reference

Public Endpoints

Get Random Image

Authenticated Endpoints

Upload Images

List Images

Delete Image

Get All Tags

Get Configuration

Project Structure

Image Storage Structure

License

Acknowledgments

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages