$ show immich-app/immich
Immich is a high-performance, self-hosted photo and video management platform composed of a NestJS backend server, a SvelteKit SPA frontend, a Python FastAPI machine-learning service, a Flutter mobile client (iOS/Android), a CLI tool, and a TypeScript SDK. The server orchestrates asset ingestion, metadata extraction (EXIF, OCR, facial recognition, CLIP embeddings), video transcoding (HLS), and background job processing via BullMQ/Redis, with PostgreSQL (Kysely ORM + vector extensions for smart search) as the primary data store. The ML service provides ONNX-based inference for CLIP visual/textual embeddings, face detection/recognition (InsightFace), and OCR (RapidOCR), supporting multiple hardware accelerators (CUDA, ROCm, OpenVINO, ARM NN, RKNN). The architecture uses a multi-worker process model (API, microservices, maintenance) managed by a main process that handles lifecycle and restarts. Key data flows include: mobile/web upload → asset processing pipeline → metadata extraction → ML inference → search indexing, with real-time sync via WebSocket/Redis adapter and a full incremental sync API for mobile clients. The codebase demonstrates strong engineering practices: comprehensive repository pattern with 50+ repositories, extensive medium/integration test suites, schema migrations managed via Kysely SQL tools, OpenAPI-driven SDK generation for both TypeScript and Dart, and a plugin system using Extism WASM.
The LLM identified 6 files worth highlighting for reuse:
Implements a multi-worker process manager that bootstraps API, microservices, and maintenance workers as separate Node.js processes (fork for API, Worker threads for others). Handles maintenance mode detection via database advisory locks, graceful restart orchestration across all workers, and crash propagation. This is a clean, self-contained pattern for managing heterogeneous worker lifecycles in a monorepo server that could be extracted for any NestJS application needing process-level isolation.
Implements a production-grade ML inference service with an in-memory model cache supporting TTL-based unloading, optimistic locking for concurrent model access, thread pool execution to bypass asyncio's GIL bottleneck for CPU-bound inference, and an idle shutdown task for resource reclamation. The dependency-aware inference pipeline allows parallel execution of independent models (e.g., CLIP visual + textual) with automatic sequential execution when dependencies exist. The model loading includes retry logic with cache clearing on corruption, and fallback from hardware-accelerated formats (ARMNN, RKNN) to ONNX. This is a well-structured pattern for serving multiple ML models behind a single API.
Defines the complete database schema as typed Kysely table classes with decorators for extensions, indexes, and constraints. Provides a single source of truth for 60+ tables, custom SQL functions (uuid_v7, unaccent, ll_to_earth), and enum types, all composed into a typed DB interface. This pattern enables fully type-safe SQL query building with Kysely while keeping schema definitions declarative and migration-friendly. The approach of co-locating table definitions, functions, and enums in a schema module is reusable for any Kysely-based project.
A sophisticated timeline manager implementing virtual scrolling with justified layout calculation for photo/video grids. Decomposes timeline management into composable 'support' modules (intersection, search, load, layout, websocket) that mixin into the main manager via Svelte 5's reactive state system. Handles dynamic asset grouping by day/month, viewport-aware rendering, WebSocket-driven real-time updates, and search filtering with result insertion caching. The modular support pattern using Svelte 5 runes demonstrates a clean architecture for complex UI state management that avoids monolithic component logic.
Implements a WASM-based plugin system using Extism where each plugin method is a pure function receiving typed data, config, and host functions. Demonstrates declarative asset pipeline actions (archive, favorite, file filter, location filter, type filter, visibility, webhook, add-to-albums) that can be composed into workflows. The wrapper pattern enforces that all methods are explicitly destructured and exported, preventing silent omissions. This is a clean pattern for building extensible, sandboxed plugin systems where plugins declare capabilities through a manifest and the host provides controlled API access.
Implements hierarchical tag upsert with automatic closure table maintenance. Given a list of slash-delimited tag paths (e.g., 'nature/flowers/roses'), it creates each level of the hierarchy, linking children to parents via upsert operations. This is a reusable pattern for any application needing hierarchical categorization with closure tables for efficient ancestor/descendant queries. The function is isolated, depends only on a repository interface, and handles deduplication and incremental creation correctly.