lychee Documentation

Lychee's facial recognition feature allows users to browse their photo library by the people appearing in them. The system uses a separate Python-based service (running in a container) to detect faces and generate embeddings. Lychee (the PHP/Laravel backend) manages the storage of these results, provides a management UI, and handles privacy settings.

Key capabilities include:

• Browsing photos by person.
• Viewing face overlays on photo details.
• Managing persons (merging, assigning, or unassigning faces).
• Batch face operations (multi-select, unassign, reassign, or uncluster).
• Privacy controls to ensure non-searchable persons are invisible to unauthorized users.

Smart Albums are virtual, dynamically-generated albums in Lychee that automatically contain photos based on specific criteria (e.g., being highlighted, recently uploaded, or unassigned).

Key Characteristics:

• Virtual Albums: No database storage for the album itself, only for photos.
• Dynamic Content: Photos appear or disappear automatically based on their properties.
• Singleton Pattern: Only one instance of each smart album type exists.
• Read-Only: Users cannot create, delete, or manually add/remove photos from them.
• Configurable: Can be enabled or disabled via configuration settings.

Lychee is refactoring album virtual computed fields from runtime calculations to pre-computed database columns. This change moves expensive subqueries (previously handled by AlbumBuilder.php) to an event-driven system that updates values when photos or albums are mutated. This improves performance for album lists and gallery views by reducing database load at read time.

Key fields being moved to physical columns include:

• max_taken_at
• min_taken_at
• num_children
• num_photos
• auto_cover_id_least_privilege
• auto_cover_id_max_privilege

The Webshop Print & Pixel Sizes feature extends Lychee's webshop capabilities to support physical print orders and custom pixel-size digital exports.

Key capabilities:

• Physical Prints: Customers can purchase photos as physical prints using photographer-configured sizes (cm or inches) and optional paper types.
• Pixel-Size Digital Exports: Customers can purchase photos at specific pixel dimensions defined by the photographer.
• Automated Checkout Logic: If a basket contains any print items, the checkout process automatically requires a shipping address.
• Admin Management: Photographers manage a global catalogue of available print and pixel sizes and assign specific prices to these sizes on a per-purchasable basis.
• License Types: Print and pixel-size orders are automatically assigned the PurchasableLicenseType::PRINT license type.

Lychee's frontend is a modern Single Page Application (SPA) built using the following core technologies:

• Vue.js 3: Uses the Composition API and TypeScript (no Options API).
• PrimeVue 4: The primary UI component library.
• Tailwind CSS: Used for styling with custom PrimeUI integration.
• Pinia: For state management with persistence.
• Vue Router 4: For client-side routing.
• Vite: The build tool and development server.
• i18n: For internationalization.

Lychee uses two primary design patterns for photo management:

1. Action Pattern: Encapsulates business logic in dedicated classes with a single responsibility. This provides a clean interface between controllers and domain logic and ensures consistent response formats.
2. Pipeline Pattern: Used for complex operations like photo creation. Data flows through a series of 'pipes' (processing steps). Each pipe performs a specific transformation or validation and passes the data to the next step in the sequence.

The Lychee backend is built with Laravel (PHP) and follows a layered architecture:

• Application Layer: Contains Controllers for handling HTTP requests, Requests for validation/sanitization, Resources for API response transformation (using Spatie Data), and Middleware for filtering and authentication.
• Domain Layer: Contains Models (Eloquent ORM entities like Person, Face, and Album), Services for business logic orchestration (e.g., AdminStatsService, LdapService), and Actions for single-responsibility command objects (e.g., CreateInitialAdmin, ProvisionLdapUser).
• Infrastructure Layer: Manages Events (e.g., PhotoSaved), Listeners (e.g., RecomputeAlbumStatsOnPhotoChange), and Jobs for asynchronous tasks (e.g., ScanFacesJob).

The RAW size variant is designed to preserve untouched original files. It has the following characteristics:

• No Web Display: RAW files are never served to the frontend for rendering. Only the converted ORIGINAL variant is shown in the gallery.
• No Watermarking: RAW files are never watermarked by the system.
• API Visibility: The RAW variant is omitted from the standard SizeVariantsResouce. Instead, the PhotoResource includes a has_raw: boolean property to indicate if a RAW variant exists.
• No Shop Integration: RAW files are not purchasable via the shop and are not included in PurchasableSizeVariantType.

The Lychee frontend gallery is organized into four specialized modules that handle different aspects of the photo browsing experience:

• Album Module (albumModule/): Manages album-related UI, including grids, sub-albums, metadata, and statistics.
• Flow Module (flowModule/): Implements an Instagram-style infinite scroll interface with card-based layouts and lightboxes.
• Photo Module (photoModule/): Handles individual photo display, including full-screen viewing, EXIF metadata, rotation, and geotagging maps.
• Search Module (searchModule/): Provides the search interface, autocomplete, and result filtering.

The Gallery page layout changes based on the user's 'Shared Albums Visibility' preference:

• SHOW Mode (Default): A single continuous list containing 'Smart Albums', 'My Albums', and 'Shared Albums' sections.
• SEPARATE Mode (Tabbed View):
  • 'Smart Albums' are always visible at the top.
  • A tab bar appears with 'My Albums' and 'Shared with Me' options (only if shared albums are available).
  • Selecting 'My Albums' shows only the user's albums.
  • Selecting 'Shared with Me' shows all accessible albums from other users.
  • If no shared albums exist, the tab bar is hidden and it behaves like SHOW mode.
• HIDE Mode: The 'Shared Albums' section is completely removed, showing only 'Smart Albums' and 'Albums' (the user's own albums).

The Search UI has been refactored from an automatic debounce-based search to an explicit, button-triggered system. It features two modes:

1. Simple Mode: A single-line text input for entering raw token strings (e.g., tag:sunset date:>=2024-01-01).
2. Advanced Mode: An expandable panel containing structured form fields that automatically assemble tokens into the simple input's query string.

Key Changes:

• Search requests are only sent when clicking the Search button or pressing Enter.
• The backend API (GET /Search) remains unchanged.
• After a successful search, the view automatically scrolls to the first result using smooth behavior.