# open-noodle/gallery architecture

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

- Interactive diagram: https://gitdiagram.com/open-noodle/gallery
- Repository: https://github.com/open-noodle/gallery

## Overview

Noodle Gallery is a self-hosted photo and video library, based on Immich, with web/mobile clients, a server API, media storage, and machine-learning capabilities. A typical flow starts with a user uploading media through a client; the server handles asset operations and stores media using its storage layer. The README also documents distinct discovery, collaboration, and media-management features. The sampled sources establish storage behavior and a small amount of client/server behavior; most feature links below indicate API capability, not inspected internal call chains.

Main entry points: [`web/src/lib/services/app.service.ts`](https://github.com/open-noodle/gallery/blob/main/web/src/lib/services/app.service.ts) (Web client), [`server/src/cores/storage.core.ts`](https://github.com/open-noodle/gallery/blob/main/server/src/cores/storage.core.ts) (Storage core), [`server/src/controllers/asset-file.controller.ts`](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/asset-file.controller.ts) (Upload API), [`machine-learning/immich_ml/main.py`](https://github.com/open-noodle/gallery/blob/main/machine-learning/immich_ml/main.py) (ML service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_web["Web client<br/>[app.service.ts]"]
  node_mobile["Mobile client<br/>[MainActivity.kt]"]
  node_cli["CLI client<br/>[index.ts]"]
end

subgraph group_media["Media lifecycle"]
  node_asset_api["Asset API"]
  node_upload_api["Upload API"]
  node_storage_core["Storage core<br/>[storage.core.ts]"]
  node_disk_backend["Disk storage"]
  node_s3_backend["S3 storage"]
  node_database[("Metadata database<br/>[database.ts]")]
  node_editing_api["Edits and trimming"]
  node_migration_api["Storage migration"]
end

subgraph group_discovery["Search and discovery"]
  node_search_api["Search and filters"]
  node_timeline_api["Timeline and map"]
  node_memory_api["Memories"]
end

subgraph group_sharing["Sharing and identity"]
  node_space_api["Shared Spaces"]
  node_album_api["Albums and links"]
  node_people_api["People and faces"]
end

subgraph group_intelligence["AI and administration"]
  node_ml_service["ML service<br/>[main.py]"]
  node_face_models["Face recognition<br/>[recognition.py]"]
  node_pet_models["Pet detection<br/>[detection.py]"]
  node_ocr_models["OCR models<br/>[recognition.py]"]
  node_classification_api["Classification"]
  node_server_admin["Server administration"]
end

node_user(("Library user"))

node_user -->|"uses"| node_web
node_user -->|"uses"| node_mobile
node_user -->|"uses"| node_cli
node_web -->|"uploads media"| node_upload_api
node_mobile -->|"uploads media"| node_upload_api
node_cli -->|"uploads media"| node_upload_api
node_upload_api -->|"stores files"| node_storage_core
node_storage_core -->|"uses backend"| node_disk_backend
node_storage_core -.->|"uses backend"| node_s3_backend
node_storage_core -->|"updates paths"| node_database
node_web -->|"manages assets"| node_asset_api
node_web -->|"edits media"| node_editing_api
node_web -->|"searches"| node_search_api
node_web -->|"browses"| node_timeline_api
node_web -->|"views memories"| node_memory_api
node_web -->|"collaborates"| node_space_api
node_web -->|"manages albums"| node_album_api
node_web -->|"manages people"| node_people_api
node_web -->|"reviews categories"| node_classification_api
node_web -->|"administers server"| node_server_admin
node_web -->|"starts migration"| node_migration_api
node_ml_service -->|"runs recognition"| node_face_models
node_ml_service -->|"runs detection"| node_pet_models
node_ml_service -->|"runs OCR"| node_ocr_models

click node_web "https://github.com/open-noodle/gallery/blob/main/web/src/lib/services/app.service.ts"
click node_mobile "https://github.com/open-noodle/gallery/blob/main/mobile/android/app/src/main/kotlin/app/alextran/immich/MainActivity.kt"
click node_cli "https://github.com/open-noodle/gallery/blob/main/packages/cli/src/index.ts"
click node_asset_api "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/asset.controller.ts"
click node_upload_api "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/asset-file.controller.ts"
click node_storage_core "https://github.com/open-noodle/gallery/blob/main/server/src/cores/storage.core.ts"
click node_disk_backend "https://github.com/open-noodle/gallery/blob/main/server/src/backends/disk-storage.backend.ts"
click node_s3_backend "https://github.com/open-noodle/gallery/blob/main/server/src/backends/s3-storage.backend.ts"
click node_database "https://github.com/open-noodle/gallery/blob/main/server/src/database.ts"
click node_editing_api "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/asset.controller.ts"
click node_migration_api "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/storage-migration.controller.ts"
click node_search_api "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/search.controller.ts"
click node_timeline_api "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/timeline.controller.ts"
click node_memory_api "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/memory.controller.ts"
click node_space_api "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/shared-space.controller.ts"
click node_album_api "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/album.controller.ts"
click node_people_api "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/person.controller.ts"
click node_ml_service "https://github.com/open-noodle/gallery/blob/main/machine-learning/immich_ml/main.py"
click node_face_models "https://github.com/open-noodle/gallery/blob/main/machine-learning/immich_ml/models/facial_recognition/recognition.py"
click node_pet_models "https://github.com/open-noodle/gallery/blob/main/machine-learning/immich_ml/models/pet_detection/detection.py"
click node_ocr_models "https://github.com/open-noodle/gallery/blob/main/machine-learning/immich_ml/models/ocr/recognition.py"
click node_classification_api "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/classification.controller.ts"
click node_server_admin "https://github.com/open-noodle/gallery/blob/main/server/src/controllers/server.controller.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_web,node_mobile,node_cli,node_user toneBlue
class node_asset_api,node_upload_api,node_storage_core,node_disk_backend,node_s3_backend,node_database,node_editing_api,node_migration_api toneAmber
class node_search_api,node_timeline_api,node_memory_api toneMint
class node_space_api,node_album_api,node_people_api toneRose
class node_ml_service,node_face_models,node_pet_models,node_ocr_models,node_classification_api,node_server_admin toneIndigo
```

## Components

### Clients

- [Web client](https://github.com/open-noodle/gallery/blob/main/web/src/lib/services/app.service.ts): `web/src/lib/services/app.service.ts`
- [Mobile client](https://github.com/open-noodle/gallery/blob/main/mobile/android/app/src/main/kotlin/app/alextran/immich/MainActivity.kt): `mobile/android/app/src/main/kotlin/app/alextran/immich/MainActivity.kt`
- [CLI client](https://github.com/open-noodle/gallery/blob/main/packages/cli/src/index.ts): `packages/cli/src/index.ts`

### Media lifecycle

- [Asset API](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/asset.controller.ts): `server/src/controllers/asset.controller.ts`
- [Upload API](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/asset-file.controller.ts): `server/src/controllers/asset-file.controller.ts`
- [Storage core](https://github.com/open-noodle/gallery/blob/main/server/src/cores/storage.core.ts): `server/src/cores/storage.core.ts`
- [Disk storage](https://github.com/open-noodle/gallery/blob/main/server/src/backends/disk-storage.backend.ts): `server/src/backends/disk-storage.backend.ts`
- [S3 storage](https://github.com/open-noodle/gallery/blob/main/server/src/backends/s3-storage.backend.ts): `server/src/backends/s3-storage.backend.ts`
- [Metadata database](https://github.com/open-noodle/gallery/blob/main/server/src/database.ts): `server/src/database.ts`
- [Edits and trimming](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/asset.controller.ts): `server/src/controllers/asset.controller.ts`
- [Storage migration](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/storage-migration.controller.ts): `server/src/controllers/storage-migration.controller.ts`

### Search and discovery

- [Search and filters](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/search.controller.ts): `server/src/controllers/search.controller.ts`
- [Timeline and map](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/timeline.controller.ts): `server/src/controllers/timeline.controller.ts`
- [Memories](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/memory.controller.ts): `server/src/controllers/memory.controller.ts`

### Sharing and identity

- [Shared Spaces](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/shared-space.controller.ts): `server/src/controllers/shared-space.controller.ts`
- [Albums and links](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/album.controller.ts): `server/src/controllers/album.controller.ts`
- [People and faces](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/person.controller.ts): `server/src/controllers/person.controller.ts`

### AI and administration

- [ML service](https://github.com/open-noodle/gallery/blob/main/machine-learning/immich_ml/main.py): `machine-learning/immich_ml/main.py`
- [Face recognition](https://github.com/open-noodle/gallery/blob/main/machine-learning/immich_ml/models/facial_recognition/recognition.py): `machine-learning/immich_ml/models/facial_recognition/recognition.py`
- [Pet detection](https://github.com/open-noodle/gallery/blob/main/machine-learning/immich_ml/models/pet_detection/detection.py): `machine-learning/immich_ml/models/pet_detection/detection.py`
- [OCR models](https://github.com/open-noodle/gallery/blob/main/machine-learning/immich_ml/models/ocr/recognition.py): `machine-learning/immich_ml/models/ocr/recognition.py`
- [Classification](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/classification.controller.ts): `server/src/controllers/classification.controller.ts`
- [Server administration](https://github.com/open-noodle/gallery/blob/main/server/src/controllers/server.controller.ts): `server/src/controllers/server.controller.ts`

### Other components

- **Library user**

## Connections

- Library user → Web client: uses
- Library user → Mobile client: uses
- Library user → CLI client: uses
- Web client → Upload API: uploads media
- Mobile client → Upload API: uploads media
- CLI client → Upload API: uploads media
- Upload API → Storage core: stores files
- Storage core → Disk storage: uses backend
- Storage core → S3 storage: uses backend
- Storage core → Metadata database: updates paths
- Web client → Asset API: manages assets
- Web client → Edits and trimming: edits media
- Web client → Search and filters: searches
- Web client → Timeline and map: browses
- Web client → Memories: views memories
- Web client → Shared Spaces: collaborates
- Web client → Albums and links: manages albums
- Web client → People and faces: manages people
- Web client → Classification: reviews categories
- Web client → Server administration: administers server
- Web client → Storage migration: starts migration
- ML service → Face recognition: runs recognition
- ML service → Pet detection: runs detection
- ML service → OCR models: runs OCR