Immich Project Structure

The self-hosted photo and video backup solution. A high-performance polyglot architecture using Node.js, Python, Dart, and Svelte.

Updated 2025-12-30

#immich #nestjs #sveltekit #flutter #python #fastapi #machine-learning

PNG PDF

Project Directory

immich/

server/

API Backend (NestJS)

src/

controllers/

API Routes

services/

Business Logic

repositories/

DB Access

package.json

web/

Web Frontend (SvelteKit)

src/routes/

File-based routing

package.json

mobile/

Mobile App (Flutter)

lib/

Dart source

pubspec.yaml

Dependencies

machine-learning/

ML Service (Python)

immich_ml/

FastAPI Application

pyproject.toml

Python config

docker-compose.yml

Orchestration

Repository Info

Repository-immich-app/immich
Stars-48k+
License-AGPL-3.0
Last Analyzed-December 2025

Tech Stack

Backend-Node.js (NestJS)
Web-SvelteKit
Mobile-Flutter (Dart)
ML-Python (FastAPI)
Database-PostgreSQL + Redis

Architecture Notes

Immich uses a microservices-inspired architecture. The main server (NestJS) handles API requests and metadata. The machine-learning service (Python) runs independently to handle heavy AI tasks like face recognition, communicating via HTTP. The web and mobile clients consume the server API.

Key Directories

server/src/-Standard NestJS structure. controllers handle incoming requests, services contain business logic, and repositories manage TypeORM/Prisma interactions.
machine-learning/-A standalone Python service. It uses FastAPI to expose endpoints that the main Node.js server calls to process images.
mobile/lib/-The Flutter application. It shares code for iOS and Android, handling asset backup logic and UI rendering.

Why This Structure?

Immich demonstrates how to use the right tool for the job. Node.js for I/O-heavy API tasks, Python for AI/ML libraries, and Flutter/Svelte for high-performance UIs. It's a modern, complex system that performs exceptionally well.

Share this template