Introducing a new way to review your PRs.

Read the announcement

immich-app / immich

High performance self-hosted photo and video management solution.

View on GitHub

21 documents · Updated Oct 19, 2026

docs / asset-organization-and-discovery

Asset organization and discovery

Immich gives each asset several durable ways to group, label, filter, and find it. Albums and tags express user intent. Stacks reduce visual duplicates. Timelines, folders, maps, memories, people, and search provide different views over the same asset library. The server keeps these relationships subject to user access, while clients use them to present a consistent library across web and mobile; see Data model and persistence, Sync and client state, and Web library workflows.

Organization model

Albums

An album is a named collection of assets with its own description, cover asset, sort order, and sharing state. An asset can be in more than one album, so albums add a user-curated view without moving or copying the asset. Album lists can show owned albums, albums shared with the user, albums shared by the user, or albums that contain a given asset. Album membership can be changed in bulk, and only assets that the user can share are added. An album can be shared with users who receive a role. Shared albums can also expose a link when the owner enables one; the access rules are described in Identity, access, and sharing.

Album access controls who can change the collection. Owners manage album details and sharing. Editors can add assets, while viewers can read the album but cannot add assets. A shared user can leave an album, but the last owner cannot be removed. Album changes notify the other album users so their library views can update.

References: server/…/album.service.ts• L50-89 server/…/album.service.ts• L101-137 server/…/album.service.ts• L140-196 server/…/album.service.ts• L202-353 server/…/album.service.spec.ts• L43-185 server/…/album.service.spec.ts• L208-370 server/…/album.service.spec.ts• L760-946

Tags

Tags are user-owned labels that can form a tree. A tag has a displayed name and a full path that includes its parents, which lets users organize labels into nested groups while keeping each label distinct. Tag membership is many-to-many: one asset can have several tags, and one tag can describe many assets. Tag membership and tag-name changes also update each affected asset’s searchable tag information, so later filters see the current label set. A color-only change affects the label display and does not require an asset update. Empty tags are eligible for background cleanup after their asset links are gone.

References: server/…/tag.service.ts• L25-91 server/…/tag.service.ts• L93-155 server/…/tag.service.ts• L157-185 server/…/tag.service.spec.ts• L121-149 server/…/tag.service.spec.ts• L196-217 server/…/tag.service.spec.ts• L350-357 server/…/tag.table.ts• L15-46 server/…/tag-asset.table.ts• L5-12 server/…/tag-closure.table.ts• L4-10

Stacks

A stack groups related assets that should appear as one item in condensed library views. One asset is the primary asset and represents the stack in the timeline. Users can change the primary asset, remove non-primary assets, or dissolve the stack; creating a stack from assets that already belong to stacks merges those groups into the new stack.

References: server/…/stack.service.ts• L12-79 server/…/stack.dto.ts• L13-47 server/…/stack.controller.ts• L17-115 server/…/stack.table.ts• L24-42

Library views

Timeline

The timeline is the main chronological view of a user’s assets. The server first returns compact time buckets, then returns the asset IDs and display data for a selected bucket. The view can narrow the library by owner, album, person, tag, favorite state, trash state, visibility, partner assets, or map bounds. It can also show only primary assets from stacks. The date used for grouping can represent when the asset was taken or when it was added to Immich.

Timeline access follows the requested scope. An album request needs album-read access, while a user timeline needs timeline-read access and archive-read access for archived assets. Locked assets require elevated permission and cannot be read from another user’s timeline. Partner assets are limited to partners enabled for timeline sharing, and partner inclusion is not valid for locked, archived, trashed, or favorited requests. Shared links without metadata permission do not receive coordinates.

The web timeline loads months and their assets as the user reaches them. This keeps the visible library responsive while allowing asset updates and stack changes to move items between the right time groups.

References: server/…/timeline.service.ts• L12-89 server/…/asset.util.ts• L113-141 server/…/time-bucket.dto.ts• L7-73 web/…/timeline-manager.svelte.ts• L282-329 web/…/timeline-manager.svelte.ts• L386-404 web/…/timeline-manager.svelte.ts• L647-668

Map and place views

The map view discovers assets through location data extracted from asset metadata. It returns a marker for each matching asset and can include partner assets or assets from shared albums. Reverse geocoding turns coordinates into city, state, and country labels. The places view presents representative assets grouped by city, while the album view can show markers for only that album.

Location data is access-controlled. A shared link that does not allow metadata access does not receive coordinates or album map markers.

References: server/…/map.service.ts• L8-25 server/…/map.controller.ts• L20-40 server/…/album.service.ts• L91-99 server/…/timeline.service.ts• L68-74 server/…/search.service.ts• L200-203

Folder views

The folder view exposes the original paths of assets as a tree. It lists unique paths first, then loads assets for the selected path. This view reflects the source path recorded for each asset and does not create a second copy of the library.

References: server/…/view.service.ts• L7-15 server/…/view.controller.ts• L15-35 web/…/folders.svelte.ts• L16-53 web/…/+page.ts• L7-29

Discovery collections

Memories

A memory is a dated, asset-backed collection intended for a time-based reminder or story. Memories can be user-created or generated for events such as “on this day” and birthdays. Each memory has a display window, a memory date, a seen state, and a saved state. Unsaved generated memories can be cleaned up later, while saved memories remain available as part of the user’s memory collection.

The memory view filters by date, type, saved state, upcoming state, and order. It hides memories with no remaining assets, and removing the last asset removes the memory from the usable collection.

References: server/…/memory.service.ts• L27-64 server/…/memory.service.ts• L66-146 server/…/memory.service.ts• L149-169 server/…/memory.service.ts• L171-245 server/…/memory.table.ts• L26-67 server/…/memory.dto.ts• L10-22

People

A person is a named group of detected or manually assigned faces. The group can have a birth date, a featured face image, a favorite state, a hidden state, and a display color. Users can move faces between people, add or remove face assignments, merge people, and choose which people appear in the library. A person filter then returns assets whose faces belong to that person.

People can be shared with other users in the same cluster group. Shared person data has limits: users can update shared identity fields such as the name and birth date, while personal display choices remain with the owner. This lets people-based discovery extend across permitted users without giving one user control over another user’s private presentation.

People depend on face analysis, but the user’s name, visibility, favorite state, corrections, and sharing choices are durable library data. Face detection and recognition create or update the groups, and cleanup removes groups that no longer contain faces; see Automated asset analysis for that analysis flow.

References: server/…/person.service.ts• L55-85 server/…/person.service.ts• L95-187 server/…/person.service.ts• L189-300 server/…/person.service.ts• L329-363 server/…/person.service.ts• L656-749 server/…/person.service.ts• L757-830 server/…/person.service.ts• L838-897 server/…/person.table.ts• L19-78 server/…/person.controller.ts• L49-69 server/…/person.controller.ts• L175-221

Explore views

Explore is a summary view built from discovery signals already present in the library. It shows representative assets for places and recently added items, and it combines these with visible people and available memories. Explore therefore acts as a set of entry points into the timeline rather than a separate asset collection.

References: server/…/search.service.ts• L48-71 server/…/search.controller.ts• L94-103 web/…/+page.ts• L7-26

Search behavior

Metadata search finds assets through structured facts and relationships. Users can combine asset type, visibility, dates, location, camera details, ratings, original names and paths, OCR text, people, tags, albums, and album membership state. Search can return asset results, counts, and facets. Results are paged so a large library does not need to load in one response.

The current search contract supports a structured filter with exact, range, list, pattern, and relationship tests. Older flat fields remain part of the contract during the transition, but a request must use one shape or the other. Album filters also define a safe search boundary for shared links.

References: server/…/search.dto.ts• L25-68 server/…/search.dto.ts• L247-323 server/…/search.service.ts• L74-114 server/…/search.service.ts• L241-259 server/…/search.service.ts• L302-323

Smart search finds assets by visual or natural-language similarity. A text query is converted into a search representation, while an asset query uses that asset as the reference. The result is ranked by similarity and can still use the normal access and filter scope. Smart search is available only when the machine-learning capability is enabled; the analysis boundary is covered in Automated asset analysis.

References: server/…/search.service.ts• L168-197 server/…/search.service.ts• L281-300 server/…/search.service.ts• L325-354 server/…/search.controller.ts• L82-92 web/…/search-manager.svelte.ts• L21-27 web/…/search-manager.svelte.ts• L94-130

Search scope

Every discovery request runs within the current user’s allowed asset scope. The scope can include the user’s timeline and enabled partner timelines, but locked assets remain limited to their owner. Album-based requests check album access before searching. Shared-link requests must stay confined to an allowed album because a shared-link visitor has no wider library scope.

References: server/…/search.service.ts• L302-367 server/…/timeline.service.ts• L47-89 server/…/map.service.ts• L9-19

Cross-view relationships

An asset is the shared point between organization and discovery surfaces. Albums, tags, stacks, memories, and people attach to the asset without changing its identity. Timeline and search use those relationships as filters, while map and folder views use location and original-path data. This means one edit can affect several views: for example, adding a tag changes tag filters, and changing a stack changes whether the timeline shows its member or only its primary asset.

The following model shows how one asset record feeds the durable organization links and the discovery views.

flowchart LR
    Asset[Asset] --> Albums[Albums]
    Asset --> Tags[Tags]
    Asset --> Stack[Stack]
    Asset --> Memory[Memories]
    Asset --> Person[People and faces]
    Asset --> Timeline[Timeline]
    Asset --> Map[Map and places]
    Asset --> Folder[Folders]
    Asset --> Search[Metadata and smart search]
    Albums --> Search
    Tags --> Search
    Person --> Search

The web client listens for changes to these relationships and updates the visible view rather than treating each page as an isolated cache. Mobile clients consume the same durable relationships through the shared API and sync contracts; see Mobile library synchronization for client reconciliation.

References: server/…/asset-response.dto.ts• L61-117 server/…/asset-response.dto.ts• L193-245 web/…/timeline-manager.svelte.ts• L112-153 server/…/tag.service.ts• L104-150 server/…/stack.service.ts• L21-79

Change checklist

When these files or sections are changed, remember to consider these:

  • Changes to album membership, album filters, or album access must preserve owned, shared-with-me, shared-out, and asset-specific album lists. They must also preserve album-scoped timeline reads and album-confined search, including shared-link access.
  • Changes to tag paths or tag membership must keep the tag tree, asset tag data, and tag-based timeline and search filters aligned.
  • Changes to stack membership or the primary asset must update both condensed timeline results and full asset responses so clients do not show stale stack state.
  • Changes to people, face assignment, or person sharing must preserve the link between person filters, asset people data, birthday memories, thumbnails, and each user’s allowed person fields.
  • Changes to asset date or location meaning must be checked against timeline grouping, map markers, places, reverse geocoding, and search date and place filters.
  • Changes to timeline scope or partner eligibility must preserve album, timeline, archive, locked, and partner access checks across time-bucket and selected-bucket reads.
  • Changes to memory visibility or cleanup rules must preserve saved, seen, show, and hide behavior across generated memories and the memory viewer.
  • Changes to search filter shape or cursor behavior must be reflected in the server contract and in web and mobile clients that build or page search requests.

Important failure modes

TriggerConsequenceGuard
A shared-link search is not confined to an albumThe request is rejected instead of exposing assets from a wider librarySearchService requires an album-confined filter for shared links.
A locked asset is requested through a partner or general scopeThe asset can cross a private-library boundaryLocked searches use only the current user and require elevated permission.
A partner timeline request includes archived, trashed, favorited, or locked assetsThe request mixes partner sharing with states that are not supported by the timeline contractTimeline validation rejects partner inclusion for those states.
An album receives an asset outside the user’s allowed share scopeThe album can expose an asset that the album user cannot shareAlbum membership checks asset access before adding the asset.
A viewer tries to add assets or a shared user changes album detailsA read-only participant can alter the shared collectionAlbum permissions reserve asset changes and album updates for the matching roles.
A stack update selects an asset outside the stackThe stack would point to an invalid primary assetStack updates reject a primary asset that is not a member.
A stack removal targets the primary assetThe stack loses the asset that represents it in condensed viewsThe primary asset cannot be removed directly.
A tag change updates the relation but not asset tag dataTag filters and asset responses can disagreeTag changes refresh the asset’s tag information after membership changes.
A person merge has fewer than two distinct peopleThe merge can erase or self-merge a person without a valid targetMerge requests require at least two unique IDs.
A person or memory has no remaining assetsThe discovery page can point to an empty collectionPerson cleanup removes empty groups, while memory results filter empty memories and asset removal deletes a memory when its last asset is removed.
A user shares a person with an outside cluster group or with themselvesPerson sharing can cross the supported user boundary or create a self-shareSharing rejects the current user and users outside the owner’s cluster group.
Map or timeline data is returned through a link without metadata permissionLocation details can leak through a discovery viewShared-link requests suppress coordinates and album map markers when EXIF display is disabled.

Key files

FileWhy to read it
server/…/album.service.tsDefines album listing, membership, sharing, metadata, thumbnails, and access-aware asset changes.
server/…/tag.service.tsDefines tag trees, asset labeling, and the asset data refreshed after tag changes.
server/…/stack.service.tsDefines stack creation, merging, primary selection, removal, and deletion.
server/…/timeline.service.tsDefines the access and filter rules for chronological asset discovery.
server/…/map.service.tsDefines map marker scope, partner and shared-album inclusion, and reverse geocoding.
server/…/memory.service.tsDefines generated and user-managed memories and their asset membership.
server/…/person.service.tsDefines people, face assignment, merging, sharing, cleanup, and durable user corrections.
server/…/search.service.tsDefines metadata, smart, explore, suggestion, and access-scoped search behavior.
server/…/search.dto.tsDefines the search filter language, result shape, and album-confined scope rules.
server/…/asset-response.dto.tsShows how tags, people, stacks, visibility, and asset dates appear in shared asset responses.
web/…/timeline-manager.svelte.tsShows how the web timeline loads time buckets and reacts to asset and stack changes.
web/…/memory-manager.svelte.tsShows how the web client pages memories and keeps viewer navigation aligned with memory state.
web/…/search-manager.svelte.tsShows how web search controls become API metadata or smart-search requests.