How immich-app/immich works
Immich is a self-hosted photo and video management product. In the principal workflow, a mobile client backs up media to the server; the server stores assets and metadata, while machine-learning inference supplies search embeddings, face results, and OCR. Users then browse, search, organize, share, and download assets through web or mobile clients. The README documents these capabilities; sampled excerpts show the ML inference path, Android background lock behavior, and storage-template configuration, but not most server and client call paths, so those links are documented or left unverified.
Main entry points: asset.service.ts Asset management · pipeline.py Inference pipeline · database.ts Metadata database · main.py Inference API
Components 23
Web and mobile clients
- Android background backup
mobile/android/app/src/main/kotlin/app/alextran/immich/background/BackgroundWorker.kt - iOS background backup
mobile/ios/Runner/Background/BackgroundWorker.swift - Mobile media sync
mobile/android/app/src/main/kotlin/app/alextran/immich/sync/MessagesImplBase.kt - Web gallery
web/src/lib - Storage template settings
web/src/lib/components/admin-settings/StorageTemplateSettings.svelte
Immich server
- HTTP API
server/src/controllers/asset.controller.ts - Asset management
server/src/services/asset.service.ts - Search and discovery
server/src/services/search.service.ts - Albums and sharing
server/src/services/album.service.ts - Faces and memories
server/src/services/person.service.ts - Storage templates
server/src/services/storage-template.service.ts
Machine learning
- Inference API
machine-learning/immich_ml/main.py - Inference pipeline
machine-learning/immich_ml/pipeline.py - CLIP encoders
machine-learning/immich_ml/models/clip/textual.py - Face models
machine-learning/immich_ml/models/facial_recognition/detection.py - OCR models
machine-learning/immich_ml/models/ocr/recognition.py - Model runtime
machine-learning/immich_ml/models/base.py - ONNX sessions
machine-learning/immich_ml/sessions/ort.py
Storage and database
- Asset files
server/src/cores/storage.core.ts - Metadata database
server/src/database.ts
Other components
- Mobile user
- Web user
- ML service
Connections 22
- Mobile user → Android background backup: starts backup
README.md - Mobile user → iOS background backup: starts backup
README.md - Android background backup → Mobile media sync: syncs media
README.md - iOS background backup → Mobile media sync: syncs media
README.md - Mobile media sync → HTTP API: uploads assets
README.md - Web user → Web gallery: browses gallery
README.md - Web gallery → HTTP API: requests assets
README.md - Storage template settings → Storage templates: saves settings
web/src/lib/components/admin-settings/StorageTemplateSettings.svelte - HTTP API → Asset management: routes requests
- Asset management → Asset files: writes media
server/src/cores/storage.core.ts - Asset management → Metadata database: stores metadata
- Search and discovery → Metadata database: queries indexes
- Albums and sharing → Metadata database: stores sharing data
- Faces and memories → Metadata database: stores face data
- Asset management → ML service: requests inference
- ML service → Inference API: calls predict
- Inference API → Inference pipeline: builds entries
machine-learning/immich_ml/main.py - Inference pipeline → CLIP encoders: selects encoders
machine-learning/immich_ml/pipeline.py - Inference pipeline → Face models: selects models
machine-learning/immich_ml/pipeline.py - Inference pipeline → OCR models: selects models
machine-learning/immich_ml/pipeline.py - Inference API → Model runtime: loads and predicts
machine-learning/immich_ml/main.py - Model runtime → ONNX sessions: creates session
machine-learning/immich_ml/models/base.py