Spec driven development support #3880
Conversation
📝 WalkthroughWalkthroughThis pull request restructures documentation into a comprehensive specifications framework (docs/specs) organized as 0-overview, 1-concepts, 2-how-to, 3-reference, 4-architecture, 5-operations, 6-decisions. It adds AGENTS.md for agent guidelines, removes legacy backend/frontend readmes, introduces concept pages (albums, e-commerce, permissions, photos, users, system), reference guides (API design, coding conventions, database schema, frontend architecture, image processing), architecture documentation (knowledge map, open questions, roadmap, shop architecture), operations guides, and standardized templates. A new commit-review script assists with conventional commits. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Areas requiring extra attention:
Poem
Pre-merge checks✅ Passed checks (1 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 15
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/copilot-instructions.md (1)
1-50: Add missing documentation footer.Per the guideline documented on line 38 of this file, all documentation files should end with a horizontal rule followed by a "Last updated" timestamp. This file itself is missing that footer.
🔎 Proposed fix
# Working with Money and Currency When dealing with monetary values in PHP, it's crucial to handle them with precision to avoid rounding errors and inaccuracies. Here are how we handle money and currency in our application: we use the `moneyphp/money` library, which provides a robust way to manage monetary values and currencies. Never use floats or doubles to represent monetary values. Instead, use integers to represent the smallest currency unit (e.g., cents for USD). This means that $10.99 should be stored as 1099 (cents). + +--- + +*Last updated: December 22, 2025*
🧹 Nitpick comments (3)
docs/specs/3-reference/renamer-system.md (1)
98-116: Consider adding nullability for the description field in the documentation.In the Data Model section at line 108,
descriptionis shown as?string(nullable), which is good. However, ensure this matches the actual model implementation to avoid confusion.AGENTS.md (1)
1-89: Consider adding a "Last updated" footer.While AGENTS.md is a governance document rather than traditional user documentation, it would benefit from having a "Last updated" footer consistent with other markdown documentation files in the repository. This helps track when the agent guidelines were last modified.
Suggested addition
Add at the end of the file:
+ +--- + +*Last updated: December 22, 2025*docs/specs/3-reference/frontend-architecture.md (1)
285-290: Minor typo: "simplied" should be "simplified".Line 288 contains a typo in the function comment.
🔎 Proposed fix
- // Very simplied! + // Very simplified!
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (58)
.github/copilot-instructions.mdAGENTS.mdREADME.mddocs/Contribute.mddocs/README.mddocs/backend/README.mddocs/frontend/README.mddocs/frontend/Vue3.mddocs/specs/0-overview/README.mddocs/specs/1-concepts/README.mddocs/specs/1-concepts/albums.mddocs/specs/1-concepts/e-commerce.mddocs/specs/1-concepts/permissions.mddocs/specs/1-concepts/photos.mddocs/specs/1-concepts/system.mddocs/specs/1-concepts/users.mddocs/specs/2-how-to/add-oauth-provider.mddocs/specs/2-how-to/translating-lychee.mddocs/specs/2-how-to/using-renamer.mddocs/specs/3-reference/api-design.mddocs/specs/3-reference/coding-conventions.mddocs/specs/3-reference/database-schema.mddocs/specs/3-reference/frontend-architecture.mddocs/specs/3-reference/frontend-gallery.mddocs/specs/3-reference/frontend-layouts.mddocs/specs/3-reference/image-processing.mddocs/specs/3-reference/localization.mddocs/specs/3-reference/renamer-system.mddocs/specs/3-reference/shop-implementation.mddocs/specs/3-reference/timestamps-handling.mddocs/specs/4-architecture/README.mddocs/specs/4-architecture/album-tree-structure.mddocs/specs/4-architecture/backend-architecture.mddocs/specs/4-architecture/knowledge-map.mddocs/specs/4-architecture/open-questions.mddocs/specs/4-architecture/request-lifecycle-album-creation.mddocs/specs/4-architecture/request-lifecycle-photo-upload.mddocs/specs/4-architecture/roadmap.mddocs/specs/4-architecture/shop-architecture.mddocs/specs/4-architecture/spec-guidelines/feature-numbering-conventions.mddocs/specs/4-architecture/spec-guidelines/open-questions-format.mddocs/specs/4-architecture/spec-guidelines/ui-ascii-mockups.mddocs/specs/4-architecture/tag-system.mddocs/specs/5-operations/analysis-gate-checklist.mddocs/specs/5-operations/quality-gate.mddocs/specs/5-operations/runbook-session-reset.mddocs/specs/5-operations/session-quick-reference.mddocs/specs/5-operations/verifying-releases.mddocs/specs/6-decisions/README.mddocs/specs/_current-session.mddocs/specs/architecture-graph.jsondocs/specs/templates/adr-template.mddocs/specs/templates/feature-plan-template.mddocs/specs/templates/feature-spec-template.mddocs/specs/templates/feature-tasks-template.mddocs/specs/templates/how-to-template.mddocs/specs/toc.ymlscripts/codex-commit-review.sh
💤 Files with no reviewable changes (3)
- docs/backend/README.md
- docs/frontend/README.md
- docs/frontend/Vue3.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.md
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
**/*.md: Use Markdown format for documentation
At the bottom of documentation files, add a horizontal rule followed by "Last updated: [date of the update]"
Files:
docs/specs/4-architecture/album-tree-structure.mddocs/specs/templates/how-to-template.mddocs/specs/1-concepts/README.mddocs/specs/4-architecture/request-lifecycle-photo-upload.mddocs/specs/3-reference/frontend-gallery.mddocs/specs/2-how-to/translating-lychee.mddocs/specs/4-architecture/roadmap.mddocs/specs/6-decisions/README.mddocs/specs/4-architecture/spec-guidelines/feature-numbering-conventions.mddocs/README.mddocs/specs/1-concepts/albums.mddocs/specs/5-operations/analysis-gate-checklist.mddocs/specs/4-architecture/knowledge-map.mddocs/specs/0-overview/README.mddocs/specs/3-reference/api-design.mddocs/specs/1-concepts/photos.mddocs/specs/5-operations/runbook-session-reset.mddocs/specs/templates/adr-template.mddocs/specs/templates/feature-tasks-template.mddocs/specs/5-operations/session-quick-reference.mddocs/specs/1-concepts/system.mddocs/specs/3-reference/timestamps-handling.mddocs/specs/1-concepts/e-commerce.mdAGENTS.mddocs/specs/5-operations/quality-gate.mddocs/specs/4-architecture/spec-guidelines/ui-ascii-mockups.mddocs/specs/2-how-to/using-renamer.mddocs/specs/3-reference/shop-implementation.mddocs/specs/3-reference/localization.mddocs/specs/5-operations/verifying-releases.mddocs/Contribute.mddocs/specs/templates/feature-plan-template.mddocs/specs/3-reference/renamer-system.mddocs/specs/4-architecture/request-lifecycle-album-creation.mddocs/specs/4-architecture/tag-system.mddocs/specs/2-how-to/add-oauth-provider.mddocs/specs/3-reference/coding-conventions.mddocs/specs/3-reference/database-schema.mdREADME.mddocs/specs/4-architecture/shop-architecture.mddocs/specs/4-architecture/README.mddocs/specs/3-reference/frontend-architecture.mddocs/specs/1-concepts/permissions.mddocs/specs/4-architecture/open-questions.mddocs/specs/3-reference/image-processing.mddocs/specs/4-architecture/backend-architecture.mddocs/specs/3-reference/frontend-layouts.mddocs/specs/4-architecture/spec-guidelines/open-questions-format.mddocs/specs/1-concepts/users.mddocs/specs/templates/feature-spec-template.md
🧠 Learnings (38)
📚 Learning: 2025-11-25T21:26:03.890Z
Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T21:26:03.890Z
Learning: Applies to **/*.md : At the bottom of documentation files, add a horizontal rule followed by "*Last updated: [date of the update]*"
Applied to files:
docs/specs/4-architecture/album-tree-structure.mddocs/specs/4-architecture/request-lifecycle-photo-upload.mddocs/specs/3-reference/timestamps-handling.mddocs/Contribute.mddocs/specs/4-architecture/request-lifecycle-album-creation.mddocs/specs/4-architecture/tag-system.md
📚 Learning: 2025-10-26T19:15:58.151Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3765
File: version.md:1-1
Timestamp: 2025-10-26T19:15:58.151Z
Learning: The `version.md` file should NOT include the documentation footer (HR line followed by "*Last updated: [date]*") that is typically added to other Markdown files in the Lychee project. This file only contains the version number.
Applied to files:
docs/specs/3-reference/frontend-gallery.mddocs/specs/0-overview/README.md
📚 Learning: 2025-08-20T20:35:04.474Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3637
File: lang/nl/renamer.php:10-94
Timestamp: 2025-08-20T20:35:04.474Z
Learning: In Lychee, translation files are initially created with English strings as placeholders, and actual translations are handled through Weblate (a web-based translation management system). This means finding English text in non-English locale files (like lang/nl/, lang/de/, etc.) is expected and part of their translation workflow, not an issue to flag.
Applied to files:
docs/specs/2-how-to/translating-lychee.mddocs/specs/3-reference/localization.md
📚 Learning: 2025-08-22T06:11:18.329Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3641
File: lang/no/settings.php:9-9
Timestamp: 2025-08-22T06:11:18.329Z
Learning: For lang/* translation files in the Lychee project: only review PHP-related issues (syntax, structure, etc.), not translation content, grammar, or language-related nitpicks. The maintainer ildyria has explicitly requested this approach.
Applied to files:
docs/specs/2-how-to/translating-lychee.mddocs/specs/3-reference/localization.md
📚 Learning: 2025-08-27T08:48:27.520Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3654
File: lang/cz/gallery.php:210-210
Timestamp: 2025-08-27T08:48:27.520Z
Learning: For this Lychee project, the maintainer prefers to keep language strings in English across all locale files rather than translating them to local languages.
Applied to files:
docs/specs/2-how-to/translating-lychee.mddocs/specs/3-reference/localization.md
📚 Learning: 2025-08-20T20:33:32.844Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3637
File: lang/cz/renamer.php:3-94
Timestamp: 2025-08-20T20:33:32.844Z
Learning: In Lychee, internationalization is done by the admin, not by the visitor, and the system uses custom locale directory naming (e.g., lang/cz/) that may not follow Laravel's standard ISO 639-1 conventions like lang/cs/. This is intentional and works within their custom internationalization system.
Applied to files:
docs/specs/2-how-to/translating-lychee.mddocs/specs/3-reference/localization.md
📚 Learning: 2025-12-19T21:01:55.399Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3838
File: lang/ar/webshop.php:1-2
Timestamp: 2025-12-19T21:01:55.399Z
Learning: License headers are not required for language translation files (e.g., files in the lang/* directory) in the Lychee project, even though they are generally required for other PHP files.
Applied to files:
docs/specs/2-how-to/translating-lychee.mddocs/specs/3-reference/localization.md
📚 Learning: 2025-08-27T08:48:45.672Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3654
File: lang/es/gallery.php:210-210
Timestamp: 2025-08-27T08:48:45.672Z
Learning: The project maintainer ildyria has indicated that language localization consistency is not a priority ("Lang = don't care"), meaning English text in non-English language files is acceptable and should not be flagged as an issue.
Applied to files:
docs/specs/2-how-to/translating-lychee.md
📚 Learning: 2025-11-25T21:26:03.890Z
Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T21:26:03.890Z
Learning: Applies to **/*.php : Any new PHP file should contain the license header and have a single blank line after the opening PHP tag
Applied to files:
.github/copilot-instructions.md
📚 Learning: 2025-11-25T21:26:03.890Z
Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T21:26:03.890Z
Learning: Applies to **/*.php : Apply PSR-4 coding standard
Applied to files:
.github/copilot-instructions.mddocs/specs/3-reference/coding-conventions.md
📚 Learning: 2025-12-19T21:01:40.134Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3838
File: lang/pl/webshop.php:1-2
Timestamp: 2025-12-19T21:01:40.134Z
Learning: In the LycheeOrg/Lychee repository, files in the lang/* directory do not require the license header that is normally required for PHP files.
Applied to files:
.github/copilot-instructions.mddocs/specs/3-reference/localization.md
📚 Learning: 2025-09-13T14:47:30.798Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3683
File: database/factories/PurchasableFactory.php:103-109
Timestamp: 2025-09-13T14:47:30.798Z
Learning: Photos and albums have a Many-Many relationship in Lychee, meaning a photo can belong to multiple albums. There is no single photo->album_id property. When creating purchasables for photos, both photo_id and album_id must be specified to indicate which photo-album combination the purchasable applies to.
Applied to files:
docs/specs/1-concepts/albums.mddocs/specs/1-concepts/photos.mddocs/specs/1-concepts/e-commerce.mddocs/specs/3-reference/database-schema.mddocs/specs/4-architecture/shop-architecture.md
📚 Learning: 2025-08-14T17:22:19.225Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3618
File: database/factories/TagAlbumFactory.php:53-59
Timestamp: 2025-08-14T17:22:19.225Z
Learning: In TagAlbumFactory (test factory), the user ildyria prefers to keep the simpler loop-based attach() approach over syncWithoutDetaching() optimization since it's only used in tests where N+1 queries and performance are not a concern.
Applied to files:
docs/specs/1-concepts/albums.md
📚 Learning: 2025-08-12T11:31:09.853Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3605
File: docs/Lifecycle-of-a-request-photo-upload.md:144-151
Timestamp: 2025-08-12T11:31:09.853Z
Learning: In Lychee, the BaseApiRequest class has been modified to change Laravel's default execution order - processValidatedValues() runs BEFORE authorize(), not after. This means that in Lychee request classes, $this->album and other processed properties are available during authorization checks, unlike standard Laravel behavior.
Applied to files:
docs/specs/3-reference/api-design.mddocs/specs/4-architecture/backend-architecture.md
📚 Learning: 2025-08-14T20:54:52.579Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3619
File: app/Rules/README.md:227-231
Timestamp: 2025-08-14T20:54:52.579Z
Learning: The user ildyria prefers to keep "Last updated" footers in italic format (*Last updated: [date]*) in documentation files, even if it triggers markdownlint MD036 warnings. This is a stylistic choice for the Lychee project.
Applied to files:
docs/specs/3-reference/timestamps-handling.mddocs/Contribute.mddocs/specs/4-architecture/tag-system.md
📚 Learning: 2025-09-13T14:20:45.835Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3683
File: database/migrations/2025_08_27_203030_create_orders_table.php:0-0
Timestamp: 2025-09-13T14:20:45.835Z
Learning: Lychee does not use Laravel's timestamps() helper method because it is broken in their project context. Always use explicit dateTime() declarations for created_at and updated_at columns in Lychee migrations.
Applied to files:
docs/specs/3-reference/timestamps-handling.md
📚 Learning: 2025-11-17T11:36:52.888Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3810
File: app/Actions/Shop/CheckoutService.php:70-72
Timestamp: 2025-11-17T11:36:52.888Z
Learning: For Mollie and Stripe payment providers in the CheckoutService, the payment flow uses redirects rather than POST callbacks. When the user completes payment, they are redirected back to Lychee with query parameters in the URL (not POST data). The purchase parameters stored in the session are used with completePurchase() to verify the payment, and any necessary callback data comes from the query parameters in the redirect URL, which Omnipay handles automatically.
Applied to files:
docs/specs/1-concepts/e-commerce.mddocs/specs/4-architecture/shop-architecture.md
📚 Learning: 2025-11-26T21:50:26.687Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 0
File: :0-0
Timestamp: 2025-11-26T21:50:26.687Z
Learning: In the LycheeOrg/Lychee repository, lang/* files should not be reviewed at all. These files should be completely excluded from code review.
Applied to files:
docs/specs/3-reference/localization.md
📚 Learning: 2025-09-20T17:43:08.152Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3698
File: resources/js/lychee.d.ts:33-44
Timestamp: 2025-09-20T17:43:08.152Z
Learning: Backend currency validation in Lychee is handled by the Configs::sanity() method using ICU currency data bundle to validate ISO-4217 currency codes. Frontend validation is not required as backend validation is sufficient.
Applied to files:
docs/specs/3-reference/localization.md
📚 Learning: 2025-11-25T21:26:03.890Z
Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T21:26:03.890Z
Learning: Applies to **/*.vue : Do not use await async calls in Vue3; use .then() instead
Applied to files:
docs/Contribute.md
📚 Learning: 2025-09-28T09:04:05.578Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3721
File: resources/js/views/gallery-panels/Album.vue:200-205
Timestamp: 2025-09-28T09:04:05.578Z
Learning: In Vue3 code, the preference between async/await and promise chaining depends on context: async/await is very much preferred in services, while in other locations it depends on the specific use case.
Applied to files:
docs/Contribute.md
📚 Learning: 2025-11-25T21:26:03.890Z
Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T21:26:03.890Z
Learning: Do not use Blade views; use Vue3 instead
Applied to files:
docs/Contribute.md
📚 Learning: 2025-11-25T21:26:03.890Z
Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T21:26:03.890Z
Learning: Applies to **/*.{vue,ts,tsx} : Use function functionName() {} syntax instead of const function = () => {}
Applied to files:
docs/Contribute.md
📚 Learning: 2025-11-25T21:26:03.890Z
Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T21:26:03.890Z
Learning: Applies to **/*.vue : Use TypeScript in composition API for Vue3 and use PrimeVue for UI components
Applied to files:
docs/Contribute.mddocs/specs/3-reference/frontend-architecture.md
📚 Learning: 2025-11-25T21:26:03.890Z
Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T21:26:03.890Z
Learning: Applies to **/*.vue : In Vue3 components, the order should be: <template>, then <script lang="ts">, then <style>
Applied to files:
docs/Contribute.md
📚 Learning: 2025-08-20T20:30:29.086Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3637
File: app/Http/Requests/Renamer/ListRenamerRulesRequest.php:25-30
Timestamp: 2025-08-20T20:30:29.086Z
Learning: In the Renamer module's ListRenamerRulesRequest, the authorization allows any user with may_upload to pass all=true, but the actual filtering logic in RenamerController::index() restricts non-admin users to only see their own rules regardless of the all parameter. This is an intentional design where request-level authorization is permissive but business logic enforcement happens at the controller level.
Applied to files:
docs/specs/3-reference/renamer-system.md
📚 Learning: 2025-08-18T10:19:04.946Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3626
File: database/migrations/2025_06_07_144157_photo_tags_to_table.php:87-105
Timestamp: 2025-08-18T10:19:04.946Z
Learning: In the Lychee photo management system, the migration `2025_06_07_144157_photo_tags_to_table.php` runs on data that only contains comma-separated tag names in tag_albums.show_tags - OR/AND expressions do not exist at this migration time, so handling them is unnecessary.
Applied to files:
docs/specs/3-reference/database-schema.md
📚 Learning: 2025-09-21T20:09:31.762Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3702
File: database/migrations/2025_08_27_203030_create_purchasable.php:35-39
Timestamp: 2025-09-21T20:09:31.762Z
Learning: In the Lychee codebase, ildyria has decided to ignore the unique constraint issue with UNIQUE(album_id, photo_id) in the purchasables table where NULL values in MySQL/MariaDB don't enforce uniqueness as expected. This is acceptable for their multi-database support strategy (sqlite, pgsql, mariadb) and likely handled at the application level.
Applied to files:
docs/specs/3-reference/database-schema.md
📚 Learning: 2025-09-16T21:56:01.607Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3683
File: app/Actions/Shop/OrderService.php:65-73
Timestamp: 2025-09-16T21:56:01.607Z
Learning: The validation for album-photo membership in OrderService::addPhotoToOrder() is implemented within PurchasableService::getEffectivePurchasableForPhoto() using a whereHas('albums') constraint that ensures the photo belongs to the specified album_id before applying pricing logic.
Applied to files:
docs/specs/4-architecture/shop-architecture.md
📚 Learning: 2025-09-16T21:56:01.607Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3683
File: app/Actions/Shop/OrderService.php:65-73
Timestamp: 2025-09-16T21:56:01.607Z
Learning: The validation for album-photo membership in PurchasableService::getEffectivePurchasableForPhoto() uses a JOIN query with the photo_album pivot table to ensure that only purchasables for albums that actually contain the specified photo are returned, preventing price spoofing attacks where clients could use arbitrary album_ids.
Applied to files:
docs/specs/4-architecture/shop-architecture.md
📚 Learning: 2025-09-18T13:37:32.687Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3683
File: app/Actions/Shop/PurchasableService.php:286-296
Timestamp: 2025-09-18T13:37:32.687Z
Learning: The deleteMultipleAlbumPurchasables() method in PurchasableService is designed to delete ALL purchasables (both album-level with photo_id IS NULL and photo-level with photo_id IS NOT NULL) for the specified album_ids. This is the intended behavior when albums are being deleted, as all photos within those albums will also be deleted, making their purchasables obsolete.
Applied to files:
docs/specs/4-architecture/shop-architecture.md
📚 Learning: 2025-09-13T14:01:20.039Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3683
File: app/Actions/Shop/OrderService.php:0-0
Timestamp: 2025-09-13T14:01:20.039Z
Learning: In PurchasableService::getEffectivePurchasableForPhoto(), both the photo-specific and album-level SQL queries include ->where('is_active', true), so the returned purchasable is guaranteed to be active and doesn't need additional is_active checks in calling code.
Applied to files:
docs/specs/4-architecture/shop-architecture.md
📚 Learning: 2025-09-18T07:09:17.176Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3683
File: app/Actions/Shop/PurchasableService.php:150-168
Timestamp: 2025-09-18T07:09:17.176Z
Learning: In PurchasablePhotoRequest, the validation for photo-album membership is implemented at the request validation level rather than in the service layer, using a count comparison to ensure all photos belong to the target album before creating purchasables.
Applied to files:
docs/specs/4-architecture/shop-architecture.md
📚 Learning: 2025-09-28T08:39:34.280Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3721
File: resources/js/stores/NsfwConsentedState.ts:3-5
Timestamp: 2025-09-28T08:39:34.280Z
Learning: In Lychee codebase, all Pinia store files follow the pattern of declaring the type alias before the store definition (e.g., `export type StoreType = ReturnType<typeof useStore>; export const useStore = defineStore(...)`). This pattern compiles successfully with TypeScript 5.9 and vue-tsc.
Applied to files:
docs/specs/3-reference/frontend-architecture.md
📚 Learning: 2025-11-30T17:19:00.773Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3837
File: resources/js/composables/checkout/useStepTwo.ts:8-16
Timestamp: 2025-11-30T17:19:00.773Z
Learning: In the Lychee project's checkout composables (resources/js/composables/checkout/), module-level refs that cause state sharing across component instances are intentional architectural choices, not issues to flag.
Applied to files:
docs/specs/3-reference/frontend-architecture.md
📚 Learning: 2025-09-28T12:48:30.559Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3721
File: resources/js/views/gallery-panels/Timeline.vue:392-0
Timestamp: 2025-09-28T12:48:30.559Z
Learning: In the Lychee frontend, delete operations at the root/timeline level are gated by `rootRights.can_edit` rather than a separate `can_delete` permission. The `RootAlbumRightsResource` only exposes `can_edit`, `can_upload`, `can_see_live_metrics`, and `can_import_from_server` properties. Album-level rights have `can_delete`, but timeline/root contexts use `can_edit` for delete permissions.
Applied to files:
docs/specs/1-concepts/permissions.md
📚 Learning: 2025-08-18T12:13:52.320Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3622
File: app/Actions/Photo/Pipes/Standalone/PlacePhoto.php:31-31
Timestamp: 2025-08-18T12:13:52.320Z
Learning: In the Lychee photo processing pipeline, files are initially created on LOCAL storage using CreateSizeVariantFlags() with default StorageDiskType::LOCAL, then transferred to S3 later via UploadSizeVariantToS3Job. This is the intended design pattern and not a bug.
Applied to files:
docs/specs/3-reference/image-processing.md
📚 Learning: 2025-09-03T14:22:58.633Z
Learnt from: ildyria
Repo: LycheeOrg/Lychee PR: 3673
File: docs/add-oauth-provider.md:36-49
Timestamp: 2025-09-03T14:22:58.633Z
Learning: Lychee uses Laravel 12 but deliberately maintains the old infrastructure model without migrating to newer Laravel 11+ patterns. They continue using EventServiceProvider for event registration rather than the newer Event::listen approach in AppServiceProvider, so documentation should reflect the traditional EventServiceProvider pattern.
Applied to files:
docs/specs/4-architecture/backend-architecture.md
🪛 LanguageTool
docs/specs/1-concepts/photos.md
[grammar] ~131-~131: Use a hyphen to join words.
Context: ...y generate thumbnail frames but not full size variants ### Access Control - **O...
(QB_NEW_EN_HYPHEN)
AGENTS.md
[style] ~20-~20: This sentence may be long and difficult for your reader to follow. Consider inserting a period and starting a new sentence here.
Context: ...ts, NFR, behaviour/UI, telemetry/policy), with history captured via [docs/specs/4-architecture/open-que...
(WITH_THE_SENTENCE)
[style] ~42-~42: ‘without warning’ might be wordy. Consider a shorter alternative.
Context: ...tracked files or directories can appear without warning; surface them for review instead of rem...
(EN_WORDINESS_PREMIUM_WITHOUT_WARNING)
docs/specs/5-operations/quality-gate.md
[uncategorized] ~5-~5: The official name of this software platform is spelled with a capital “H”.
Context: ...changes, and rely on the CI workflow ([.github/workflows/CICD.yml](../../../.github/wo...
(GITHUB)
[uncategorized] ~5-~5: The official name of this software platform is spelled with a capital “H”.
Context: ...CI workflow (.github/workflows/CICD.yml) for enforcement on...
(GITHUB)
[uncategorized] ~152-~152: The official name of this software platform is spelled with a capital “H”.
Context: ...gate on every push and pull request via .github/workflows/CICD.yml. **CI checks inclu...
(GITHUB)
[style] ~212-~212: Consider using a different verb to strengthen your wording.
Context: ...ow functions) ## Performance Tips ### Speed Up Local Development - **Parallel test ex...
(SPEED_UP_ACCELERATE)
docs/specs/3-reference/coding-conventions.md
[grammar] ~295-~295: Ensure spelling is correct
Context: ...as/composition-api-faq.html) - Official Vue3 documentation - [PrimeVue Documentation...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/specs/3-reference/frontend-architecture.md
[grammar] ~146-~146: Ensure spelling is correct
Context: ...eline state - FavouriteState.ts - Favourites items ### Store Pattern ```typescript...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (48)
docs/specs/3-reference/timestamps-handling.md (1)
1-1: LGTM!The formatting updates are compliant with coding guidelines. The title capitalization, horizontal rule insertion, and "Last updated" footer in italic format all align with project conventions. The date is current (December 22, 2025).
Also applies to: 6-6, 139-141
docs/specs/3-reference/shop-implementation.md (1)
1-557: Documentation timestamp refresh compliant.Footer format is correct, and timestamp is current. No content changes observed.
README.md (1)
55-55: Link update to new documentation structure is correct.The reference now points to the new specs-based documentation location (docs/specs/5-operations/verifying-releases.md), aligning with the PR's documentation restructuring.
docs/specs/2-how-to/translating-lychee.md (1)
1-220: Comprehensive translation guide with proper documentation structure.The guide covers developer, translator, and operations workflows clearly and includes the required footer. Links to related documentation are correct.
docs/specs/3-reference/frontend-gallery.md (1)
509-517: Documentation footer and cross-references properly implemented.The addition of the "Related Documentation" section with links to frontend architecture and coding conventions is well-placed and consistent with spec structure.
docs/specs/4-architecture/spec-guidelines/feature-numbering-conventions.md (1)
1-159: Feature numbering conventions clearly defined with proper structure.The document establishes unambiguous numbering schemes for features, questions, decisions, and tasks. The status line provides appropriate governance context, and the footer is correctly formatted.
docs/specs/2-how-to/using-renamer.md (1)
1-262: LGTM! Comprehensive how-to guide with clear examples.The documentation is well-structured with practical examples covering rule creation, pattern application, and common use cases. The PHP code examples are clear and the troubleshooting section adds practical value. The "Last updated" footer follows the coding guidelines correctly.
docs/Contribute.md (2)
211-211: LGTM! Footer correctly formatted.The "Last updated" footer follows the coding guidelines with the proper format: horizontal rule followed by the italicized date.
7-13: The documentation structure links are correctly implemented. All referenced paths exist:
specs/0-overview/README.md✓specs/1-concepts/README.md✓specs/3-reference/✓specs/4-architecture/✓The footer format also complies with the coding guideline, with the horizontal rule and "Last updated: December 22, 2025" properly placed.
scripts/codex-commit-review.sh (1)
1-60: LGTM! Well-structured commit message helper script.The script provides useful guidance for conventional commit messages and appropriately handles the case where both documentation and code change together by suggesting a "Spec impact:" section. The use of
|| trueon grep commands prevents failures when no matches are found, andset -eensures the script fails fast on errors.docs/specs/4-architecture/shop-architecture.md (2)
195-197: LGTM! Footer correctly formatted.The documentation footer follows the coding guidelines with the proper horizontal rule and italicized "Last updated" timestamp.
189-193: Cross-reference links are valid and correctly named.All three referenced documentation files exist in the repository:
../3-reference/shop-implementation.md✓backend-architecture.md✓../3-reference/database-schema.md✓The related documentation section is properly configured.
docs/specs/3-reference/renamer-system.md (2)
123-124: LGTM! Footer correctly formatted.The documentation footer follows the coding guidelines correctly.
118-121: Cross-reference links are valid. Both referenced files exist and the relative paths resolve correctly:
../../2-how-to/using-renamer.md→ docs/specs/2-how-to/using-renamer.md ✓../4-architecture/backend-architecture.md→ docs/specs/4-architecture/backend-architecture.md ✓docs/specs/3-reference/localization.md (2)
200-201: LGTM! Footer correctly formatted.The documentation footer follows the coding guidelines with the proper format.
194-198: Cross-references verified and footer format correct.Both documentation links exist and the footer follows the required format with a horizontal rule followed by the last updated timestamp.
docs/specs/4-architecture/request-lifecycle-album-creation.md (1)
432-434: LGTM! Footer correctly formatted with updated timestamp.The documentation footer follows the coding guidelines correctly with the updated timestamp.
docs/specs/toc.yml (1)
1-14: LGTM! Clean documentation structure.The table of contents follows a clear organizational pattern that aligns with the Diátaxis documentation framework. The seven-section structure (overview, concepts, how-to guides, reference, architecture, operations, decisions) provides excellent navigation for different user needs.
docs/specs/4-architecture/album-tree-structure.md (1)
269-271: LGTM! Excellent technical documentation.The documentation correctly follows the coding guidelines with a horizontal rule followed by the last updated timestamp. The nested set model explanation with mermaid diagrams is comprehensive and clear.
docs/specs/2-how-to/add-oauth-provider.md (1)
167-174: LGTM! Good addition of cross-references.The new "Related Documentation" section enhances the documentation by linking to relevant concept pages. This improves discoverability and helps users understand the broader context. The file correctly follows coding guidelines with proper formatting and the last updated timestamp.
docs/specs/4-architecture/tag-system.md (1)
136-138: LGTM! Timestamp updated correctly.The documentation follows coding guidelines with the proper horizontal rule and updated timestamp.
docs/specs/4-architecture/request-lifecycle-photo-upload.md (1)
522-524: LGTM! Comprehensive documentation with correct timestamp.The documentation follows coding guidelines properly and provides excellent detail on the photo upload lifecycle.
docs/specs/3-reference/frontend-layouts.md (1)
386-396: LGTM! Excellent cross-linking additions.The new "Related Documentation" section provides valuable navigation to related frontend documentation. This makes it easier for developers to find comprehensive information across architecture, gallery views, and coding conventions. The file correctly follows coding guidelines.
docs/specs/templates/adr-template.md (1)
1-49: LGTM! Well-structured ADR template.The Architecture Decision Record template is comprehensive and follows best practices. It includes all essential sections (context, decision, consequences, alternatives, security/privacy impact, operational impact) and provides clear guidance for documenting architectural decisions.
docs/specs/4-architecture/roadmap.md (1)
1-75: Well-structured roadmap document.The roadmap provides a clear structure for tracking features with appropriate status values, priority levels, and directory organization. The step-by-step instructions for using the roadmap are helpful for maintainers.
docs/specs/1-concepts/README.md (1)
1-135: LGTM! Comprehensive and well-structured core concepts guide.Excellent overview of Lychee's domain model with clear entity relationships, concept pages, and navigation to related documentation. The architecture diagram (lines 59–121) is well-organized and provides strong orientation for contributors.
docs/specs/5-operations/verifying-releases.md (1)
1-115: LGTM! Clean formatting and documentation updates.The simplification of the heading, punctuation fixes, and consistent quotation style improve readability. Timestamp appropriately updated to December 22, 2025.
docs/specs/3-reference/api-design.md (2)
1-176: LGTM! Comprehensive API design reference with clear patterns and examples.Excellent documentation of Lychee's RESTful API architecture, including authentication layers, Spatie Data serialization, request validation lifecycle (correctly noting that
processValidatedValues()runs beforeauthorize()), and type-safety mechanisms. The lifecycle explanation on lines 152–157 accurately reflects custom Laravel behavior documented in previous PRs.
64-64: External documentation paths are correct—bothapp/Policies/README.mdandapp/Rules/README.mdexist at the referenced locations.docs/specs/1-concepts/system.md (1)
1-294: LGTM! Comprehensive system concepts documentation.Excellent coverage of Statistics, Job History, OAuth Credentials, and System Configuration. The detailed attribute lists, status enumerations, use cases, and configuration best practices provide clear guidance for both users and developers. Cross-references to related concepts are well-placed.
docs/specs/4-architecture/knowledge-map.md (1)
1-149: LGTM! Excellent codebase navigation and reference guide.Comprehensive knowledge map cataloging backend and frontend modules, dependencies, architectural patterns, and cross-module contracts. The extensive cross-references to related documentation across concepts, how-to guides, references, and architecture sections provide excellent navigation. Well-maintained pointers to domain model, coding standards, and operational guides align the documentation structure well.
docs/specs/4-architecture/open-questions.md (1)
1-30: Documentation structure and format are excellent.Clear table layout for tracking questions, well-defined workflow steps, and proper footer formatting. The guidance on logging, detailing, presenting, and resolving questions establishes a solid process for handling unresolved issues.
docs/specs/3-reference/database-schema.md (2)
94-100: Clarify the Photo-Album relationship as many-to-many.The learnings indicate that photos have a many-to-many relationship with albums (a photo can belong to multiple albums), but the current description only shows "Belongs to Album" as a singular relationship. This should be clarified in the relationships section to accurately reflect that multiple album assignments are possible.
Based on learnings, verify whether the Photo-Album relationship documentation should be updated to reflect the many-to-many nature, or if this detail is intentionally omitted in favor of documenting it only in the concepts layer (docs/specs/1-concepts/photos.md).
1-239: Comprehensive schema documentation with proper footer.Well-organized reference with clear section headers, model descriptions, relationship mapping, and optimization guidance. Cross-references to related documentation aid navigation. The distinction between Regular and Smart Albums is clearly explained, and the nested set model is appropriately referenced to external docs.
docs/specs/1-concepts/albums.md (1)
1-312: Clear, comprehensive album architecture documentation.Excellent explanation of the dual hierarchy (persistent vs. virtual albums), the composition pattern used by BaseAlbumImpl, and detailed feature comparisons. The nested tree structure example and side-by-side comparison tables effectively communicate complex architectural choices. Proper footer and cross-references are in place.
docs/specs/1-concepts/photos.md (1)
1-217: Comprehensive photo documentation with clear examples.Well-structured coverage of photo attributes, temporal data, EXIF metadata, color palettes, and size variants. The many-to-many photo-album relationship is clearly explained (lines 57-60), and the dual-checksum approach is well-motivated. Size variant access control and EXIF privacy considerations are appropriately documented. Footer format is correct.
docs/specs/5-operations/quality-gate.md (1)
1-234: Practical quality gate guide with comprehensive coverage.Clear quick-reference commands, detailed section breakdowns (PHP and Frontend checks), troubleshooting guidance, and CI integration overview. The standards and conventions section effectively bridges to related documentation (coding-conventions.md, AGENTS.md). Footer is properly formatted. The top-of-file timestamp (line 3) is redundant with the footer timestamp but does not violate guidelines.
docs/specs/5-operations/analysis-gate-checklist.md (1)
1-66: Well-structured gates with clear preconditions and outputs.The Analysis Gate and Implementation Drift Gate checklists are comprehensive and actionable. The distinction between pre-implementation (analysis) and post-implementation (drift) gates provides good process discipline. Cross-references to constitution, open-questions, and decision records are appropriately integrated. The guidance on divergence handling and coverage confirmation is thorough.
docs/specs/1-concepts/e-commerce.md (1)
1-260: Comprehensive e-commerce documentation with clear models and workflows.Well-structured coverage of Purchasable, PurchasablePrice, Order, and OrderItem models. The pricing strategy examples (lines 111-119) effectively illustrate the dual-variant/dual-license approach. Payment flows for both Omnipay-integrated providers and offline payments are clearly documented. The constraint that either photo_id OR album_id must be set (line 52) properly reflects the business logic. Footer format is correct, and cross-references to related concepts are in place.
docs/specs/0-overview/README.md (1)
1-119: LGTM! This overview document provides an excellent introduction to Lychee with clear audience segmentation, capability descriptions, and helpful navigation. The structure, messaging, and comparison table effectively position Lychee in the market while remaining accessible to both new users and developers.docs/specs/3-reference/frontend-architecture.md (1)
1-694: LGTM! Comprehensive frontend architecture documentation that clearly explains Vue3 Composition API patterns, Pinia store conventions, and Lychee-specific practices like avoidingasync/awaitin favor of.then()chains. The structure progresses logically from overview through component architecture to performance considerations and best practices.docs/specs/1-concepts/permissions.md (1)
1-112: LGTM! Clear and well-structured permissions documentation that explains the access model hierarchy, nested album permissions, and password protection effectively. The examples with Paris/Day 1/Rome scenario make the permission inheritance model easy to understand.docs/README.md (1)
1-80: LGTM! The documentation index now provides clear navigation across the new Diátaxis-inspired specs structure. The reorganization into Backend Architecture, Frontend Architecture, Data Structures, and Authorization sections makes it easy for both new and experienced developers to find what they need. The integration with the new specs framework is seamless.docs/specs/3-reference/coding-conventions.md (1)
1-300: LGTM! Comprehensive coding standards documentation that codifies project-wide conventions for PHP (PSR-4, strict comparisons, money handling), Vue3/TypeScript (Composition API, function declarations,.then()chains), testing (unit/feature test structure), and documentation. The conventions align with the codebase learnings and the footer format is correct.docs/specs/4-architecture/backend-architecture.md (1)
1-260: LGTM! Comprehensive backend architecture documentation that clearly explains Laravel structure, design patterns (Actions, Request classes, Spatie Data resources, Factories), and security/performance considerations. The documentation aligns with codebase learnings, particularly regarding the customized Request lifecycle and EventServiceProvider patterns. The request flow examples and module documentation references provide good navigation to deeper details.docs/specs/5-operations/session-quick-reference.md (1)
1-131: Comprehensive session reference with clear structure and actionable guidance.This document provides excellent operational guidance with proper markup formatting, clear sections, and practical examples. The session kickoff checklist, commit protocol, and handoff template align well with specification-driven development practices. Cross-references use consistent relative paths.
docs/specs/3-reference/image-processing.md (1)
1-211: Well-structured image processing documentation aligned with system design.Clear explanation of size variants, processing pipeline stages, and storage strategy. The configuration examples, code models, and security considerations provide practical guidance for developers. Storage strategy correctly describes the configurable nature of disk targets and the processing workflow.
docs/specs/1-concepts/users.md (1)
1-190: Clear, well-structured user concept documentation with practical examples.Comprehensive coverage of user attributes, authentication methods, capabilities, and user groups. The permission resolution example (lines 156-167) effectively illustrates how group and direct permissions combine. Cross-references to related concepts are properly formatted. All sections are actionable and appropriate for developers implementing user-related features.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.