# immich-app/immich architecture

> Architecture diagram of the GitHub repository immich-app/immich, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/immich-app/immich
- Repository: https://github.com/immich-app/immich

## Overview

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: [`server/src/services/asset.service.ts`](https://github.com/immich-app/immich/blob/main/server/src/services/asset.service.ts) (Asset management), [`machine-learning/immich_ml/pipeline.py`](https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/pipeline.py) (Inference pipeline), [`server/src/database.ts`](https://github.com/immich-app/immich/blob/main/server/src/database.ts) (Metadata database), [`machine-learning/immich_ml/main.py`](https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/main.py) (Inference API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Web and mobile clients"]
  node_android_backup["Android background backup"]
  node_ios_backup["iOS background backup"]
  node_mobile_media["Mobile media sync"]
  node_web_app["Web gallery"]
  node_admin_storage_ui["Storage template settings"]
end

subgraph group_server["Immich server"]
  node_api["HTTP API"]
  node_asset_service["Asset management<br/>[asset.service.ts]"]
  node_search_service["Search and discovery<br/>[search.service.ts]"]
  node_organization["Albums and sharing<br/>[album.service.ts]"]
  node_people["Faces and memories<br/>[person.service.ts]"]
  node_storage_template["Storage templates"]
end

subgraph group_ml["Machine learning"]
  node_ml_api["Inference API<br/>[main.py]"]
  node_ml_pipeline["Inference pipeline<br/>[pipeline.py]"]
  node_clip_models["CLIP encoders<br/>[textual.py]"]
  node_face_models["Face models<br/>[detection.py]"]
  node_ocr_models["OCR models<br/>[recognition.py]"]
  node_model_runtime["Model runtime<br/>[base.py]"]
  node_ort_session["ONNX sessions<br/>[ort.py]"]
end

subgraph group_persistence["Storage and database"]
  node_asset_store[("Asset files<br/>[storage.core.ts]")]
  node_database[("Metadata database<br/>[database.ts]")]
end

node_mobile_user(("Mobile user"))
node_web_user(("Web user"))
node_ml_service["ML service"]

node_mobile_user -.->|"starts backup"| node_android_backup
node_mobile_user -.->|"starts backup"| node_ios_backup
node_android_backup -.->|"syncs media"| node_mobile_media
node_ios_backup -.->|"syncs media"| node_mobile_media
node_mobile_media -.->|"uploads assets"| node_api
node_web_user -.->|"browses gallery"| node_web_app
node_web_app -.->|"requests assets"| node_api
node_admin_storage_ui -.->|"saves settings"| node_storage_template
node_api -.->|"routes requests"| node_asset_service
node_asset_service -.->|"writes media"| node_asset_store
node_asset_service -.->|"stores metadata"| node_database
node_search_service -.->|"queries indexes"| node_database
node_organization -.->|"stores sharing data"| node_database
node_people -.->|"stores face data"| node_database
node_asset_service -.->|"requests inference"| node_ml_service
node_ml_service -.->|"calls predict"| node_ml_api
node_ml_api -->|"builds entries"| node_ml_pipeline
node_ml_pipeline -->|"selects encoders"| node_clip_models
node_ml_pipeline -->|"selects models"| node_face_models
node_ml_pipeline -->|"selects models"| node_ocr_models
node_ml_api -->|"loads and predicts"| node_model_runtime
node_model_runtime -->|"creates session"| node_ort_session

click node_android_backup "https://github.com/immich-app/immich/blob/main/mobile/android/app/src/main/kotlin/app/alextran/immich/background/BackgroundWorker.kt"
click node_ios_backup "https://github.com/immich-app/immich/blob/main/mobile/ios/Runner/Background/BackgroundWorker.swift"
click node_mobile_media "https://github.com/immich-app/immich/blob/main/mobile/android/app/src/main/kotlin/app/alextran/immich/sync/MessagesImplBase.kt"
click node_web_app "https://github.com/immich-app/immich/tree/main/web/src/lib"
click node_admin_storage_ui "https://github.com/immich-app/immich/blob/main/web/src/lib/components/admin-settings/StorageTemplateSettings.svelte"
click node_api "https://github.com/immich-app/immich/blob/main/server/src/controllers/asset.controller.ts"
click node_asset_service "https://github.com/immich-app/immich/blob/main/server/src/services/asset.service.ts"
click node_search_service "https://github.com/immich-app/immich/blob/main/server/src/services/search.service.ts"
click node_organization "https://github.com/immich-app/immich/blob/main/server/src/services/album.service.ts"
click node_people "https://github.com/immich-app/immich/blob/main/server/src/services/person.service.ts"
click node_storage_template "https://github.com/immich-app/immich/blob/main/server/src/services/storage-template.service.ts"
click node_ml_api "https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/main.py"
click node_ml_pipeline "https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/pipeline.py"
click node_clip_models "https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/models/clip/textual.py"
click node_face_models "https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/models/facial_recognition/detection.py"
click node_ocr_models "https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/models/ocr/recognition.py"
click node_model_runtime "https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/models/base.py"
click node_ort_session "https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/sessions/ort.py"
click node_asset_store "https://github.com/immich-app/immich/blob/main/server/src/cores/storage.core.ts"
click node_database "https://github.com/immich-app/immich/blob/main/server/src/database.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_android_backup,node_ios_backup,node_mobile_media,node_web_app,node_admin_storage_ui,node_mobile_user,node_web_user toneBlue
class node_api,node_asset_service,node_search_service,node_organization,node_people,node_storage_template toneAmber
class node_ml_api,node_ml_pipeline,node_clip_models,node_face_models,node_ocr_models,node_model_runtime,node_ort_session toneMint
class node_asset_store,node_database toneRose
class node_ml_service toneIndigo
```

## Components

### Web and mobile clients

- [Android background backup](https://github.com/immich-app/immich/blob/main/mobile/android/app/src/main/kotlin/app/alextran/immich/background/BackgroundWorker.kt): `mobile/android/app/src/main/kotlin/app/alextran/immich/background/BackgroundWorker.kt`
- [iOS background backup](https://github.com/immich-app/immich/blob/main/mobile/ios/Runner/Background/BackgroundWorker.swift): `mobile/ios/Runner/Background/BackgroundWorker.swift`
- [Mobile media sync](https://github.com/immich-app/immich/blob/main/mobile/android/app/src/main/kotlin/app/alextran/immich/sync/MessagesImplBase.kt): `mobile/android/app/src/main/kotlin/app/alextran/immich/sync/MessagesImplBase.kt`
- [Web gallery](https://github.com/immich-app/immich/tree/main/web/src/lib): `web/src/lib`
- [Storage template settings](https://github.com/immich-app/immich/blob/main/web/src/lib/components/admin-settings/StorageTemplateSettings.svelte): `web/src/lib/components/admin-settings/StorageTemplateSettings.svelte`

### Immich server

- [HTTP API](https://github.com/immich-app/immich/blob/main/server/src/controllers/asset.controller.ts): `server/src/controllers/asset.controller.ts`
- [Asset management](https://github.com/immich-app/immich/blob/main/server/src/services/asset.service.ts): `server/src/services/asset.service.ts`
- [Search and discovery](https://github.com/immich-app/immich/blob/main/server/src/services/search.service.ts): `server/src/services/search.service.ts`
- [Albums and sharing](https://github.com/immich-app/immich/blob/main/server/src/services/album.service.ts): `server/src/services/album.service.ts`
- [Faces and memories](https://github.com/immich-app/immich/blob/main/server/src/services/person.service.ts): `server/src/services/person.service.ts`
- [Storage templates](https://github.com/immich-app/immich/blob/main/server/src/services/storage-template.service.ts): `server/src/services/storage-template.service.ts`

### Machine learning

- [Inference API](https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/main.py): `machine-learning/immich_ml/main.py`
- [Inference pipeline](https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/pipeline.py): `machine-learning/immich_ml/pipeline.py`
- [CLIP encoders](https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/models/clip/textual.py): `machine-learning/immich_ml/models/clip/textual.py`
- [Face models](https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/models/facial_recognition/detection.py): `machine-learning/immich_ml/models/facial_recognition/detection.py`
- [OCR models](https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/models/ocr/recognition.py): `machine-learning/immich_ml/models/ocr/recognition.py`
- [Model runtime](https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/models/base.py): `machine-learning/immich_ml/models/base.py`
- [ONNX sessions](https://github.com/immich-app/immich/blob/main/machine-learning/immich_ml/sessions/ort.py): `machine-learning/immich_ml/sessions/ort.py`

### Storage and database

- [Asset files](https://github.com/immich-app/immich/blob/main/server/src/cores/storage.core.ts): `server/src/cores/storage.core.ts`
- [Metadata database](https://github.com/immich-app/immich/blob/main/server/src/database.ts): `server/src/database.ts`

### Other components

- **Mobile user**
- **Web user**
- **ML service**

## Connections

- Mobile user → Android background backup: starts backup (evidence: `README.md`)
- Mobile user → iOS background backup: starts backup (evidence: `README.md`)
- Android background backup → Mobile media sync: syncs media (evidence: `README.md`)
- iOS background backup → Mobile media sync: syncs media (evidence: `README.md`)
- Mobile media sync → HTTP API: uploads assets (evidence: `README.md`)
- Web user → Web gallery: browses gallery (evidence: `README.md`)
- Web gallery → HTTP API: requests assets (evidence: `README.md`)
- Storage template settings → Storage templates: saves settings (evidence: `web/src/lib/components/admin-settings/StorageTemplateSettings.svelte`)
- HTTP API → Asset management: routes requests
- Asset management → Asset files: writes media (evidence: `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 (evidence: `machine-learning/immich_ml/main.py`)
- Inference pipeline → CLIP encoders: selects encoders (evidence: `machine-learning/immich_ml/pipeline.py`)
- Inference pipeline → Face models: selects models (evidence: `machine-learning/immich_ml/pipeline.py`)
- Inference pipeline → OCR models: selects models (evidence: `machine-learning/immich_ml/pipeline.py`)
- Inference API → Model runtime: loads and predicts (evidence: `machine-learning/immich_ml/main.py`)
- Model runtime → ONNX sessions: creates session (evidence: `machine-learning/immich_ml/models/base.py`)
