Knowledge Base updated: 2026-10-18
Immich knowledge base
Orientation
Immich is a self-hosted photo and video platform with a NestJS server, Svelte web client, Flutter mobile client, Python machine-learning service, and Rust-backed native mobile media utilities.
Critical durable state lives in PostgreSQL through the server repository and migration layers, while original media and derived files are managed through configurable storage abstractions. Client applications reconcile library, session, and activity state through server APIs and realtime connections.
The server coordinates HTTP APIs, background jobs, media processing, search and analysis, and external contracts. Deployment configuration composes these services for production and end-to-end validation.
flowchart TD
Web[Svelte web application] --> API[NestJS API server]
Mobile[Flutter mobile application] --> API
CLI[CLI, SDKs, plugins] --> API
API --> DB[(PostgreSQL)]
API --> Storage[Storage abstraction]
API --> Queue[Job queues and workers]
Queue --> Media[Media processing]
Queue --> Analysis[Automated asset analysis]
Analysis --> ML[Python machine-learning service]
API --> Realtime[WebSocket and activity state]
Mobile --> Native[Rust native media core]
Deploy[Container deployment] --> API
Deploy --> ML
Deploy --> DB
Glossary
- Asset — a photo, video, or related media record with persisted metadata and stored files.
- Library — a configured source of user media and its associated synchronization state.
- Storage template — a configurable naming and layout rule for media stored by the server.
- Smart information — machine-derived asset data used for discovery, including visual and text analysis outputs.
- ThumbHash — a compact image placeholder representation produced by native mobile media utilities.
Invariants
- API input and output contracts are validated through DTOs; server DTO implementations and tests under server/…/*.ts are the evidence boundary.
- Persistent schema evolution is represented by migrations under
server/src/migrations/**; repository access must remain compatible with that schema. - Server-managed media access goes through storage abstractions and templates rather than assuming a fixed filesystem layout (server/…/storage*.service.ts, server/…/storage-template*.service.ts).
- Background work is coordinated through queue and worker services rather than executed inline for long-running media and analysis operations (server/…/job.service.ts, server/…/*-job.service.ts).
- Generated external API definitions remain synchronized with server-facing contracts through open-api/immich-openapi-specs.json.
Routing table
- server/…/app.module.ts -> docs/server-api-and-application-runtime.md
server/src/controllers/**-> docs/server-api-and-application-runtime.md- server/…/asset*.service.ts -> docs/asset-lifecycle-and-media-processing.md
- server/…/media*.service.ts -> docs/asset-lifecycle-and-media-processing.md
- server/…/auth*.service.ts -> docs/identity-access-and-sharing.md
- server/…/shared-link*.service.ts -> docs/identity-access-and-sharing.md
- server/…/job.service.ts -> docs/background-jobs-and-operations.md
- server/…/*-job.service.ts -> docs/background-jobs-and-operations.md
- server/…/smart-info*.service.ts -> docs/automated-asset-analysis.md
- server/…/metadata*.service.ts -> docs/automated-asset-analysis.md
- server/…/storage*.service.ts -> docs/storage-and-system-operations.md
- server/…/system-config*.service.ts -> docs/storage-and-system-operations.md
server/src/repositories/**-> docs/data-model-and-persistence.mdserver/src/dtos/**-> docs/data-model-and-persistence.md- server/…/album*.service.ts -> docs/asset-organization-and-discovery.md
- server/…/search*.service.ts -> docs/asset-organization-and-discovery.md
- server/…/sync*.service.ts -> docs/sync-and-client-state.md
- server/…/activity*.service.ts -> docs/sync-and-client-state.md
- web/…/+layout.svelte -> docs/web-application-experience.md
web/src/lib/managers/**-> docs/web-application-experience.mdweb/src/lib/components/pages/**-> docs/web-library-workflows.md- web/…/asset*.service.ts -> docs/web-library-workflows.md
web/src/routes/(user)/auth/**-> docs/web-administration-and-authentication.mdweb/src/lib/components/admin-settings/**-> docs/web-administration-and-authentication.mdmobile/lib/main.dart-> docs/mobile-application-architecture.mdmobile/lib/presentation/**-> docs/mobile-application-architecture.mdmobile/lib/domain/**-> docs/mobile-library-synchronization.mdmobile/lib/data/**-> docs/mobile-library-synchronization.mdmobile/lib/services/background.service.dart-> docs/mobile-capture-and-backup.mdmobile/lib/presentation/pages/backup/**-> docs/mobile-capture-and-backup.mdmobile/native/**-> docs/native-media-core.mdmachine-learning/app/**-> docs/machine-learning-service.mdmachine-learning/tests/**-> docs/machine-learning-service.mdmachine-learning/app/models/**-> docs/vision-and-text-model-capabilities.mdmachine-learning/app/schemas/**-> docs/vision-and-text-model-capabilities.mdopen-api/**-> docs/developer-contracts-and-extension-ecosystem.mdcli/**-> docs/developer-contracts-and-extension-ecosystem.mddocker/**-> docs/deployment-and-end-to-end-validation.mde2e/**-> docs/deployment-and-end-to-end-validation.md