A premium, high-performance media management system for the heavy collectors.
Effortlessly organize, scan, and view millions of images, mangas, and videos with a self-hosted platform built for speed and reliability.
ImageViewer is not just another image gallery; it's a distributed powerhouse designed to handle massive libraries. Whether you're managing a 2,000,000+ item art collection, a multi-terabyte manga library, or a video archive, ImageViewer scales with your needs.
- 📚 Manga & Comics: Seamless paging, double-view modes, and archive support (ZIP, CBZ, CBR).
- 🎨 Art & Illustrations: High-fidelity thumbnail generation, nested collection discovery, and infinite scroll.
- 🎬 Video Management: Integrated video support for unified media library oversight.
- 🏠 Self-Hosting First: Complete control over your data with Docker-ready deployment and local storage.
- Smart Incremental Rebuild: 30 min full scan reduced to 3 seconds daily (600x faster).
- Atomic Caching: Distributed Redis caching with zero-leak memory management.
- Background Processing: Multi-stage RabbitMQ pipeline (Scan → Process → Thumbnail → Cache).
- Dynamic Layouts: Single, Double, Triple, or Quad-view modes.
- Control Modes: Toggle between Continuous Scroll and Classic Paging.
- Cross-Collection Navigation: Fluid browsing across different collections and folders.
- Hotkeys First: Full keyboard control (Shuffle with
Ctrl+Shift+R, Mode toggle with numbers).
- Admin Dashboard: Real-time Hangfire job monitoring and library stats.
- Incremental Indexing: Selective rebuilds and consistency verification (Verify Mode).
- Multi-Level Cache: Tailored quality settings with auto-source analysis.
- 🍃 Main Storage: MongoDB 7.0 - Utilizing document-based collections for flexible metadata.
- 🐰 Message Broker: RabbitMQ 3.12 - Orchestrating heavy background image processing tasks.
- 🚀 Caching & State: Redis 7.2 - Fast indexing and distributed session/state management.
ImageViewer follows a strict separation of concerns, ensuring that business logic remains independent of external frameworks and databases.
┌──────────────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ • ImageViewer.Api (REST + JWT) • React Frontend (Vite + TS) │
└───────────────────────────────┬──────────────────────────────────┘
│
┌───────────────────────────────▼──────────────────────────────────┐
│ Application Layer │
│ • Use Cases & Services • DTOs & Mappings │
└───────────────────────────────┬──────────────────────────────────┘
│
┌───────────────────────────────▼──────────────────────────────────┐
│ Domain Layer │
│ • Entities & Value Objects • Domain Logic & Interfaces │
└───────────────────────────────┬──────────────────────────────────┘
│
┌───────────────────────────────▼──────────────────────────────────┐
│ Infrastructure Layer │
│ • MongoDB Repositories • RabbitMQ Messaging │
│ • Redis Indexing Service • File System Operations │
└──────────────────────────────────────────────────────────────────┘
The system uses an asynchronous, message-driven approach to handle heavy media processing without blocking the user interface.
graph TD
Client[React Frontend] <--> API[.NET 9 API]
API <--> Mongo[(MongoDB)]
API <--> Redis[(Redis)]
API -- "Publish Tasks" --> MQ[RabbitMQ]
MQ -- "Scaleable Processing" --> Worker[Worker Services]
Worker -- "Storage Access" --> Storage[Local Storage]
Scheduler[Hangfire Scheduler] -- "Cron Triggers" --> API
To achieve high performance with millions of records, we utilize a highly optimized embedded document strategy:
- Aggregated Collections: Media items (images/videos) are embedded directly within the Collection document.
- Atomic Operations: Statistics (counts, sizes) are updated using atomic
$incoperators. - Single-Trip Retrieval: A single query fetches the collection, its metadata, and all media pointers.
ImageViewer is constantly evolving. Here is what we are working on:
- Smart Incremental Rebuilds: Minimize indexing time and memory usage.
- Archive Support: ZIP, CBZ, CBR, 7z extraction and viewing.
- AI-Powered Tagging: Automatic image classification and OCR for manga text search.
- Native Mobile Apps: Smooth scrolling experience for Android and iOS.
- Multi-User Collaboration: Shared libraries with granular permission models.
- Advanced Video Transcoding: On-the-fly streaming for various formats.
The fastest way to get ImageViewer running locally:
git clone https://github.com/letuhao/media-management.git
cd media-managementdocker-compose up -dThis starts MongoDB, RabbitMQ, Redis, API, Worker, and Frontend.
- Web UI:
http://localhost:3000 - API Docs:
http://localhost:5000/swagger - Dashboard:
http://localhost:5000/hangfire
| Metric | Before Optimization | After Optimization | Improvement |
|---|---|---|---|
| Daily Rebuild Time | 30 minutes | 3 seconds | 600x 🚀 |
| Peak Memory Usage | 40 GB | 120 MB | 333x 💾 |
| Memory Leakage | 37 GB / hour | 0.0 GB | Solid stable ✅ |
| Collection Capacity | - | 25,000+ | Tested 💪 |
| Media File Capacity | - | 2,000,000+ | Tested 💪 |
| Key | Action |
|---|---|
1 - 4 |
Switch View Modes (Single to Quad) |
← → |
Previous / Next Item |
Ctrl+Shift+R |
Navigate to Random Collection (Shuffle) |
Space |
Toggle Slideshow |
R |
Rotate Image 90° |
0 |
Reset Zoom |
ImageViewer is highly configurable via .env or appsettings.json.
CACHE_QUALITY=85 # Balance between quality and storage
THUMBNAIL_WIDTH=200 # Fast loading grid view
HANGFIRE_JOB_SYNC_INTERVAL=5 # Real-time state synchronization
REDIS_MAX_MEMORY=48gb # For massive 2M+ file indexingWe welcome contributions! Please see our Organization Log to understand the project structure and CONTRIBUTING.md for guidelines.
Distributed under the MIT License. See LICENSE for more information.
Built with ❤️ by Lê Tú Hào