README.md · main · ZhienXuan/gallery

ZhienXuan/gallery

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

gallery/README.md

Innei<tukon479@gmail.com>

refactor: remove landing page components and configurations

e1d1d733

PreviewCode viewBlame

Afilmory

A modern, high-performance photo gallery platform for photographers

Official SaaS • Documentation • Live Examples • Self-Hosting

Afilmory (/əˈfɪlməri/, "uh-FIL-muh-ree") is a comprehensive photo gallery solution that combines Auto Focus (AF), Aperture (light control), Film (vintage medium), and Memory (captured moments). Built with React + TypeScript, it offers automatic photo synchronization from multiple storage sources, high-performance WebGL rendering, and professional EXIF metadata display.

🚀 Quick Start

Option 1: Official SaaS (Recommended)

👉 Get Started at afilmory.art - Zero setup, live in minutes!

The easiest way to create your photo gallery. No deployment, no servers, no maintenance required.

Why Choose SaaS?

✅ Zero Configuration - Sign up and go live immediately
✅ Live CMS - Edit photos, titles, and metadata in real-time
✅ Custom Domains - Bind your own domain with DNS verification
✅ Auto Updates - Always running the latest features
✅ Managed Infrastructure - We handle scaling, backups, and maintenance

Start Your Gallery Now →

Option 2: Self-Hosting

For developers who need full control over their deployment:

Docker (Recommended)


# See our Docker deployment guide
https://github.com/Afilmory/docker

Manual Installation


# 1. Clone and install
git clone https://github.com/Afilmory/Afilmory.git
cd Afilmory
pnpm install

# 2. Configure
cp config.example.json config.json
cp builder.config.default.ts builder.config.ts
# Edit both files with your settings

# 3. Build manifest and thumbnails
pnpm run build:manifest

# 4. Start the application
pnpm dev

For detailed self-hosting instructions, see DEVELOPMENT.md and Documentation.

📸 Live Galleries

See Afilmory in action:

afilmory.innei.in - Creator's personal gallery
gallery.mxte.cc
photography.pseudoyu.com
afilmory.magren.cc

✨ Features

Core Capabilities

🖼️ High-Performance WebGL Renderer - Custom WebGL image viewer with smooth zoom, pan, and gesture support
📱 Responsive Masonry Layout - Powered by Masonic, adapts seamlessly to any screen size
🎨 Modern UI/UX - Built with Tailwind CSS and Radix UI for accessibility and aesthetics
⚡ Incremental Sync - Smart change detection processes only new or modified photos
🌐 Internationalization - Multi-language support with i18next
🔗 Social Sharing - OpenGraph metadata for rich social media previews

Image Processing

🔄 Format Support - Automatic conversion of HEIC/HEIF and TIFF formats
🖼️ Smart Thumbnails - Multi-size thumbnail generation for optimized loading
📊 Complete EXIF Display - Camera model, focal length, aperture, ISO, and more
🌈 Blurhash Placeholders - Elegant progressive loading experience
📱 Live Photos - Detection and display of iPhone Live Photos
☀️ HDR Images - Full HDR image support
🎛️ Fujifilm Recipes - Display Fujifilm film simulation settings

Advanced Features

🗂️ Multi-Storage Support - S3-compatible storage, GitHub, Eagle, and local file system
🏷️ File System Tags - Auto-generated tags based on directory structure
⚡ Concurrent Processing - Multi-process/multi-thread support for fast builds
🗺️ Interactive Map - Geographic visualization with GPS coordinates using MapLibre
🔍 Fullscreen Viewer - Immersive image viewing with gesture controls
📷 Share & Embed - Share images to social media or embed in your website

🏗️ Architecture

Monorepo Structure


afilmory/
├── apps/
│   ├── web/              # React SPA (Vite + React Router 7)
│   ├── ssr/              # Next.js SSR wrapper for SEO/OG
│   ├── docs/             # Documentation site (VitePress)
├── be/                   # Backend services (Hono-based)
│   ├── apps/
│   │   ├── core/         # Core API server
│   │   ├── dashboard/    # Admin dashboard backend
│   │   └── oauth-gateway/# OAuth authentication gateway
│   └── packages/
│       ├── framework/    # Hono enterprise framework
│       ├── db/           # Database schemas (Drizzle ORM)
│       ├── redis/        # Redis client
│       └── websocket/    # WebSocket gateway
├── packages/
│   ├── builder/          # Photo processing pipeline
│   ├── webgl-viewer/     # WebGL image viewer component
│   ├── ui/               # Shared UI components
│   ├── hooks/            # React hooks library
│   ├── sdk/              # API client SDK
│   ├── utils/            # Utility functions
│   └── data/             # Shared data types
└── plugins/              # Builder plugins

Frontend Stack

React 19 - Latest React with Compiler
TypeScript - Full type safety
Vite - Lightning-fast build tool
React Router 7 - Modern routing
Tailwind CSS - Utility-first CSS framework
Radix UI - Accessible component primitives
Jotai - Atomic state management
TanStack Query - Data fetching and caching
i18next - Internationalization

Backend Stack

Hono - Ultra-fast web framework
Drizzle ORM - Type-safe database toolkit
PostgreSQL - Primary database
Redis - Caching and pub/sub
WebSocket - Real-time communication

Build Pipeline

Node.js - Server-side runtime
Sharp - High-performance image processing
AWS SDK - S3 storage operations
Worker Threads/Cluster - Parallel processing
EXIF-Reader - Metadata extraction

Storage Adapters

Designed with adapter pattern for flexibility:

S3-Compatible - AWS S3, MinIO, Backblaze B2, Alibaba Cloud OSS
GitHub - Use GitHub repository as storage
Eagle - Import from Eagle app library
Local File System - For development and testing

🛠️ Development

Prerequisites

Node.js 18+
pnpm 10+
TypeScript 5.9+

Project Setup


# Install dependencies
pnpm install

# Copy configuration files
cp config.example.json config.json
cp builder.config.default.ts builder.config.ts

# Set up environment variables
cp .env.template .env
# Edit .env with your credentials

Common Commands


# Development
pnpm dev                    # Start web + SSR
pnpm dev:be                 # Start backend services
pnpm --filter web dev       # Web app only
pnpm --filter @afilmory/ssr dev  # SSR only

# Build
pnpm build                  # Build production web app
pnpm build:manifest         # Generate photo manifest (incremental)
pnpm build:manifest -- --force  # Full rebuild

# Documentation
pnpm docs:dev               # Start docs dev server
pnpm docs:build             # Build documentation

# Code Quality
pnpm lint                   # Lint and fix
pnpm format                 # Format code
pnpm type-check             # Type checking

Configuration Files

config.json - Site presentation config:


{
  "name": "My Gallery",
  "title": "My Photography",
  "description": "Capturing beautiful moments",
  "url": "https://gallery.example.com",
  "accentColor": "#007bff",
  "author": {
    "name": "Your Name",
    "url": "https://example.com",
    "avatar": "https://example.com/avatar.jpg"
  },
  "social": {
    "github": "username",
    "twitter": "username"
  },
  "map": ["maplibre"],
  "mapStyle": "builtin",
  "mapProjection": "mercator"
}

builder.config.ts - Photo processing config:


import { defineBuilderConfig } from '@afilmory/builder'

export default defineBuilderConfig(() => ({
  storage: {
    provider: 's3',
    bucket: 'my-photos',
    region: 'us-east-1',
    // ... other S3 settings
  },
  system: {
    processing: {
      defaultConcurrency: 10,
      enableLivePhotoDetection: true,
    },
    observability: {
      showProgress: true,
      showDetailedStats: true,
    },
  },
}))

🔌 Extending Afilmory

Custom Storage Provider

Implement the StorageProvider interface:


import { StorageProvider } from '@afilmory/builder'

class MyStorageProvider implements StorageProvider {
  async getFile(key: string): Promise<Buffer | null> {
    // Your implementation
  }

  async listImages(): Promise<StorageObject[]> {
    // Your implementation
  }

  // ... other required methods
}

Custom Builder Plugin

Create a plugin for the build pipeline:


import { BuilderPlugin } from '@afilmory/builder'

export const myPlugin = (): BuilderPlugin => ({
  name: 'my-plugin',
  async onBeforeBuild(context) {
    // Pre-build hook
  },
  async onAfterBuild(context) {
    // Post-build hook
  },
})