How immich Works: Architecture, System Design & Code Deep Dive

Project Overview

Immich is a high-performance, self-hosted photo and video backup solution designed as a monorepo. It encompasses a robust NestJS backend API (`server/`), a responsive SvelteKit web frontend (`web/`), a cross-platform Flutter mobile application (`mobile/`), a command-line interface (`cli/`), and a dedicated machine learning service (`machine-learning/`). The system allows professional developers and users to store, manage, and interact with their media, leveraging automated processes for tasks like asset ingestion, metadata extraction, and AI-driven tagging.

Category

platform

Difficulty

advanced

Tech Stack

JavaScript, Node.js

Author

immich-app

Tags

cv, storage, distributed

How immich Works

Immich is a high-performance, self-hosted photo and video backup solution designed as a monorepo. It encompasses a robust NestJS backend API (`server/`), a responsive SvelteKit web frontend (`web/`), a cross-platform Flutter mobile application (`mobile/`), a command-line interface (`cli/`), and a dedicated machine learning service (`machine-learning/`). The system allows professional developers and users to store, manage, and interact with their media, leveraging automated processes for tasks like asset ingestion, metadata extraction, and AI-driven tagging.

Data Flow

Client applications (web, mobile, CLI) initiate requests to the Immich backend. These requests are routed by the underlying HTTP server (e.g., Fastify/Express integrated with NestJS) to specific `Controller` modules (defined in `server/src/controllers`). Controllers validate incoming data using DTOs and `class-validator`, then delegate business logic to `Service` modules (found in `server/src/services`). Services orchestrate data manipulation, often interacting with a `PostgreSQL` database via `TypeORM` repositories for persistence. For resource-intensive or asynchronous tasks (e.g., media processing, ML analysis), services publish messages to a `Redis`-backed `BullMQ` job queue. Dedicated workers, potentially including the `machine-learning` service (`machine-learning/immich_ml/main.py`), consume these jobs, process them, and update the database. Responses from services propagate back through controllers to the client. Media files themselves are stored in a designated storage location (e.g., local filesystem or S3-compatible object storage) separate from the database.

Key Modules & Components

• Machine Learning Media Analysis: Provides AI-powered features for analyzing media assets, including object detection, facial recognition, and smart tagging. It asynchronously processes media files, leveraging machine learning models to extract insights and enhance the user experience by automatically categorizing and organizing content.
  Key files: machine-learning/immich_ml/main.py
• System Configuration Management: Provides a centralized mechanism for managing application settings and feature flags. This includes reading configuration from environment variables, default values, and potentially database storage. It ensures consistent application behavior across different environments and allows administrators to customize the system's functionality.
  Key files: server/src/config.ts, server/src/controllers/system-config.controller.ts, server/src/services/system-config.service.ts