ImageFlow

| | |

English | 中文文档

ImageFlow is a full-stack image management platform that automatically optimizes images for different devices and browsers, while providing powerful filtering and distribution capabilities.

✨ Features

🚀 Core Capabilities

• Smart Image Conversion: Automatic WebP/AVIF generation with libvips for optimal performance
• Device-Aware Serving: Intelligent orientation detection (portrait for mobile, landscape for desktop)
• Advanced Random API: Multi-tag filtering, exclusion rules, and format preferences
• Dual Storage Support: Local filesystem or S3-compatible storage
• Real-time Processing: Background worker pool for async image conversion

🎯 Advanced Filtering

• Multi-tag Combinations: AND logic for precise content selection
• Exclusion Filters: Prevent NSFW or private content from public APIs
• Orientation Control: Force landscape/portrait regardless of device
• Format Negotiation: Client-aware format selection (AVIF > WebP > Original)

🛡️ Security & Privacy

• API Key Authentication: Secure upload and management endpoints
• Smart Defaults: Auto-exclude sensitive content from random API
• Expiry Management: Automatic cleanup of expired images
• Metadata Protection: Redis-based metadata with file fallback

🎨 Modern Frontend

• Next.js 14: App Router with TypeScript and Tailwind CSS
• Drag & Drop: Intuitive file upload with batch processing
• Dark Mode: Beautiful UI that adapts to user preferences
• Responsive Design: Works perfectly on all device sizes

🏃‍♂️ Quick Start

Using Docker (Recommended)

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

# Start with Docker Compose
docker-compose up -d

# Your ImageFlow instance is now running at http://localhost:8080

Manual Installation

Prerequisites

• Go 1.22+
• Node.js 18+
• libvips (for image processing)
• Redis (optional but recommended)

Backend Setup

# Install Go dependencies
go mod tidy

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Build and run
go build -o imageflow
./imageflow

Frontend Setup

cd frontend

# Install dependencies
npm install

# Development
npm run dev

# Production build
npm run build

🔧 Configuration

Create a .env file in the project root:

# Required Settings
API_KEY=your-secure-api-key-here
STORAGE_TYPE=local  # or 's3'
LOCAL_STORAGE_PATH=static/images

# Redis Configuration (Optional but Recommended)
REDIS_ENABLED=true
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# S3 Configuration (if STORAGE_TYPE=s3)
S3_ENDPOINT=https://s3.amazonaws.com
S3_REGION=us-east-1
S3_BUCKET=your-bucket-name
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
CUSTOM_DOMAIN=https://cdn.yourdomain.com

# Image Processing
MAX_UPLOAD_COUNT=20
IMAGE_QUALITY=80
WORKER_THREADS=4
SPEED=5

📚 API Usage

Random Image API

The crown jewel of ImageFlow - get perfectly filtered random images:

# Basic random image
GET /api/random?tag=nature

# Advanced filtering
GET /api/random?tags=nature,landscape&exclude=nsfw&orientation=landscape&format=webp

# Mobile-optimized
GET /api/random?tag=wallpaper&orientation=portrait

Upload API

curl -X POST "https://your-domain.com/api/upload" \
  -H "Authorization: Bearer your-api-key" \
  -F "images[][email protected]" \
  -F "images[][email protected]" \
  -F "tags=nature,landscape" \
  -F "expiryMinutes=1440"

Management API

# List images with filtering
GET /api/images?page=1&tag=nature&orientation=landscape

# Delete image
POST /api/delete-image
Content-Type: application/json
{"id": "image-uuid"}

# Get all tags
GET /api/tags

For complete API documentation, see API_USAGE_GUIDE.md.

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Next.js 14   │    │    Go Backend    │    │  Storage Layer  │
│                 │    │                  │    │                 │
│ • TypeScript    │◄──►│ • Fiber HTTP     │◄──►│ • Local Files   │
│ • Tailwind CSS  │    │ • libvips        │    │ • S3 Compatible │
│ • App Router    │    │ • Worker Pool    │    │ • Redis Cache   │
│ • Static Export │    │ • Auto Formats   │    │ • Metadata      │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Key Components

• Image Processor: libvips-powered conversion engine
• Worker Pool: Async processing for optimal performance
• Metadata Manager: Redis + file-based dual storage
• Smart Router: Device-aware content delivery
• Security Layer: API key auth + intelligent filtering

🚀 Deployment

Single Container (Recommended)

docker-compose up -d

Separated Services

# Frontend and backend as separate containers
docker-compose -f docker-compose-separate.yaml up -d

🔨 Development

Project Structure

ImageFlow/
├── main.go                 # Application entry point
├── config/                 # Configuration management
├── handlers/               # HTTP request handlers
│   ├── random.go          # Advanced random image API
│   ├── upload.go          # Multi-file upload handler
│   └── *.go               # Other API endpoints
├── utils/                  # Core utilities
│   ├── converter_bimg.go  # libvips image processing
│   ├── redis.go           # Metadata and caching
│   ├── worker_pool.go     # Async processing
│   └── *.go               # Storage, auth, etc.
├── frontend/              # Next.js application
│   ├── app/               # App Router structure
│   │   ├── components/    # React components
│   │   ├── hooks/         # Custom hooks
│   │   └── utils/         # Frontend utilities
│   └── package.json       # Dependencies
├── static/                # Generated assets
└── docker-compose*.yaml   # Deployment configs

📄 License

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

🙏 Acknowledgments

• libvips - High-performance image processing
• Redis - Lightning-fast metadata storage
• Next.js - Amazing React framework
• Fiber - Express-inspired Go web framework
• Tailwind CSS - Utility-first CSS framework

📞 Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions

---

Made with ❤️ by the catcat.blog team

Transform your image workflow today!