image generated via Gemini.

Welcome to the Lychee documentation! This folder contains comprehensive documentation about the Lychee photo management system and is primarily focused on the internal workings of Lychee. This includes its architecture, request lifecycles, data structures, and validation systems. It is intended for developers and contributors who want to understand how Lychee operates under the hood.

Before getting started, we would like to highlight the folders of interest at the root level of the repository:

./
├── app/        # Contains the core of Lychee: models, controllers, actions, and business logic
├── database/   # Database migrations for setting up the database schema
├── docs/       # Developer documentation (this folder) explaining Lychee's internal workings
│   └── specs/  # Structured documentation following Diátaxis framework
├── lang/       # Translation files for internationalization
├── resources/  # Frontend assets including Vue.js components
├── routes/     # API and web route definitions
└── tests/      # Automated test suites for ensuring code quality and functionality

The missing folders (bootstrap, composer-cache, config, docker, phpstan, public, scripts and storage) are still essential for the overall functionality of Lychee but not of primary concern for understanding the system.

Documentation is organized following the Diátaxis framework in the specs/ directory:

• 0-overview - High-level project documentation
• 1-concepts - Conceptual explanations (domain model, photos, albums, permissions)
• 2-how-to - Practical how-to guides
• 3-reference - Technical reference documentation
• 4-architecture - Architecture decisions and designs
• 5-operations - Operational runbooks
• 6-decisions - Architectural Decision Records (ADRs)

• Backend Architecture - Laravel structure, design patterns, and key components
• API Design - RESTful API patterns, authentication, and response structure
• Database Schema - Models, relationships, smart albums vs regular albums
• Request Lifecycle: Album Creation - Complete album creation flow
• Request Lifecycle: Photo Upload - Photo upload and processing flow

• Frontend Architecture - Vue3, TypeScript, Pinia, composables, and Lychee conventions
• Frontend Gallery Views - Gallery viewing modes and component architecture
• Frontend Layout System - Photo layout algorithms
• Customize the v8 (Nuxt UI) Frontend - How-to guide for theming, per-component style overrides, icons, and toasts/dialogs in the Nuxt UI migration

• Album Tree Structure - Nested set model for hierarchical album organization
• Tag System - Tag architecture and operations
• Smart Albums Documentation - Virtual albums that dynamically contain photos based on criteria

• Policies Documentation - Authorization and access control system with regular and query policies
• Rules Documentation - Custom validation rules with patterns, security considerations, and implementation examples

• Localization Reference - Technical reference for the translation system
• Translating Lychee - How-to guide for adding translations

• Contribution Guide - How to contribute to Lychee
• Coding Conventions - PHP and Vue3 coding standards
• AI/Claude Guidelines - Guidelines for AI-assisted development
• AGENTS.md - Instructions for AI agents working on this codebase

For more information about Lychee:

• Main Repository
• Official Website
• Admin Documentation
• Knowledge Map - Module and dependency relationships

Last updated: January 21, 2026