Sub albums data refactoring for speed.

[ildyria]

Summary by CodeRabbit

• New Features

  • Added API v3 endpoints for album children, timeline buckets, and access rights.
  • Added configurable date- and title-based bucket grouping.
  • Added support for regular, tag-based, and person-based album listings.
  • Added pinned, public, and link-required album indicators.
  • Added permission-aware caching and bulk bucket recomputation.

• Bug Fixes

  • Bucket data now refreshes when sorting or timeline settings change.
  • Improved child ordering and cache isolation for changing permissions.

• Documentation

  • Documented the new endpoints, configuration options, and bucket behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

Feature 061 adds materialized album buckets, recomputation jobs, a backfill command, three flag-gated API v3 endpoints, identity-aware caching, permission aggregation, and supporting documentation and tests.

Changes

Album timeline buckets

Layer / File(s)	Summary
Bucket storage and recomputation app/Enum/TitleBucketMode.php, app/Services/AlbumBucketComputer.php, app/Jobs/*Bucket*, app/Console/Commands/RecomputeAlbumBuckets.php, database/migrations/*	Albums receive nullable bucket_id values. Shared computation supports date, title-prefix, alphabetical, and non-bucketable sorting. Jobs and the CLI command recompute values in bulk.
API contracts and shared wiring app/Http/Requests/Album/*, app/Http/Resources/V3/*, routes/api_v3.php, app/Services/Cache/CacheKeyProvider.php, app/Repositories/AlbumRepository.php	The endpoints add validated requests, Struct-of-Arrays resources, routes, cache-key isolation, reusable tag/person album queries, and cache invalidation wiring.
Bucket endpoint app/Http/Controllers/Gallery/AlbumBucketController.php, tests/Feature_v3/Album/AlbumBucketsV3Test.php	The endpoint groups visible children by materialized bucket, formats labels, orders unknown values last, caches responses, and reports non-bucketable sorting.
Children data endpoint app/Http/Controllers/Gallery/AlbumChildrenDataController.php, app/Policies/AlbumQueryPolicy.php, tests/Feature_v3/Album/AlbumChildrenDataV3Test.php	The endpoint returns flat child arrays with visibility filtering, bucket ordering, SQL description truncation, cover IDs, sensitivity flags, timestamps, and bucket IDs.
Children rights endpoint app/Http/Controllers/Gallery/AlbumChildrenRightsController.php, tests/Feature_v3/Album/AlbumChildrenRightsV3Test.php	The endpoint returns per-child edit and download grants plus parent-level delete and move flags. It handles administrator, guest, tag album, person album, and aggregated group-grant cases.
Documentation and verification docs/specs/3-reference/*, docs/specs/4-architecture/*	The API, schema, feature specification, implementation plan, task checklist, knowledge map, and roadmap describe the completed feature and its verification records.

Estimated code review effort: 5 (Critical) | ~120 minutes

Merge Risk: 🟡 Moderate · up to f4193

This PR changes album timeline grouping to materialized buckets, adds cached APIs, and recomputes derived data asynchronously. At the current head, unresolved issues can cause incorrect derived writes, inaccurate child-rights flags, duplicate child records, and stale bucket or child responses, so the PR is not merge-ready until these risks are fixed or explicitly accepted.

Poem

A rabbit watched the buckets fill,
With dates and titles sorted still.
Three little routes began to hop,
While cached rights knew when to stop.
“Fresh rows bloom!” the rabbit sang,
As bulk updates softly rang.

🚥 Pre-merge checks | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 53.85% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 169 functions across 35 files. (3 skipped…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Full details: Docstring Coverage

Explanation

Docstring coverage is 53.85% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 169 functions across 35 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 13

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

docs/specs/4-architecture/features/061-album-timeline-buckets/tasks.md (1)

214-214: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add the required documentation footer.

This documentation file ends without a horizontal rule followed by *Last updated: 2026-08-29*. Add that footer at the bottom of the file.

As per coding guidelines, “At the bottom of documentation files, add an hr line followed by "Last updated: [date of the update]".”

Source: Coding guidelines

docs/specs/4-architecture/features/061-album-timeline-buckets/plan.md (1)

206-206: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add the required documentation footer.

Both documents end without the required horizontal rule and Last updated footer.

• docs/specs/4-architecture/features/061-album-timeline-buckets/plan.md#L206-L206: append the footer after the final follow-up.
• docs/specs/4-architecture/features/061-album-timeline-buckets/spec.md#L352-L353: append the footer after the Spec DSL.

As per coding guidelines: “At the bottom of documentation files, add an hr line followed by *Last updated: [date of the update]*.”

Source: Coding guidelines

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2fe0987f-61e5-4e98-a864-aecd0a4f2938

📥 Commits

Reviewing files that changed from the base of the PR and between f96f9f9 and 976e777.

📒 Files selected for processing (39)

• app/Console/Commands/RecomputeAlbumBuckets.php
• app/Enum/TitleBucketMode.php
• app/Http/Controllers/Gallery/AlbumBucketController.php
• app/Http/Controllers/Gallery/AlbumChildrenDataController.php
• app/Http/Controllers/Gallery/AlbumChildrenRightsController.php
• app/Http/Controllers/Gallery/AlbumController.php
• app/Http/Controllers/Gallery/AlbumListController.php
• app/Http/Requests/Album/GetAlbumBucketsRequest.php
• app/Http/Requests/Album/GetAlbumChildrenDataRequest.php
• app/Http/Requests/Album/GetAlbumChildrenRightsRequest.php
• app/Http/Resources/V3/AlbumBucketResource.php
• app/Http/Resources/V3/AlbumChildrenDataResource.php
• app/Http/Resources/V3/AlbumChildrenRightsResource.php
• app/Jobs/RecomputeAlbumStatsJob.php
• app/Jobs/RecomputeChildAlbumBucketsJob.php
• app/Listeners/ManagedCacheAlbumListingInvalidator.php
• app/Policies/AlbumQueryPolicy.php
• app/Repositories/AlbumRepository.php
• app/Services/AlbumBucketComputer.php
• app/Services/Cache/CacheKeyProvider.php
• database/migrations/2026_08_29_220001_add_bucket_id_to_albums.php
• database/migrations/2026_08_29_220002_add_title_bucket_configs.php
• docs/specs/3-reference/api-design.md
• docs/specs/3-reference/database-schema.md
• docs/specs/4-architecture/features/061-album-timeline-buckets/plan.md
• docs/specs/4-architecture/features/061-album-timeline-buckets/spec.md
• docs/specs/4-architecture/features/061-album-timeline-buckets/tasks.md
• docs/specs/4-architecture/knowledge-map.md
• docs/specs/4-architecture/roadmap.md
• routes/api_v3.php
• tests/Feature_v2/Album/AlbumSortingBucketDispatchTest.php
• tests/Feature_v3/Album/AlbumBucketsV3Test.php
• tests/Feature_v3/Album/AlbumChildrenDataV3Test.php
• tests/Feature_v3/Album/AlbumChildrenRightsV3Test.php
• tests/Precomputing/CoverSelection/RecomputeAlbumBucketsCommandTest.php
• tests/Precomputing/CoverSelection/RecomputeAlbumStatsJobBucketTest.php
• tests/Precomputing/CoverSelection/RecomputeChildAlbumBucketsJobTest.php
• tests/Unit/Listeners/ManagedCacheAlbumListingInvalidatorTest.php
• tests/Unit/Services/Cache/CacheKeyProviderTest.php

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 61bd733d-ac67-4b43-8fb1-048afa35fc10

📥 Commits

Reviewing files that changed from the base of the PR and between 976e777 and 46e735f.

📒 Files selected for processing (18)

• app/Actions/Tag/GetTagWithPhotosAndAlbums.php
• app/Http/Controllers/Gallery/AlbumBucketController.php
• app/Http/Controllers/Gallery/AlbumChildrenDataController.php
• app/Http/Controllers/Gallery/AlbumChildrenRightsController.php
• app/Http/Controllers/Gallery/AlbumController.php
• app/Repositories/AlbumRepository.php
• app/Services/Cache/CacheKeyProvider.php
• database/migrations/2026_08_29_220001_add_bucket_id_to_albums.php
• docs/specs/3-reference/api-design.md
• docs/specs/4-architecture/features/061-album-timeline-buckets/plan.md
• docs/specs/4-architecture/features/061-album-timeline-buckets/spec.md
• docs/specs/4-architecture/features/061-album-timeline-buckets/tasks.md
• routes/api_v3.php
• tests/Feature_v2/Album/AlbumSortingBucketDispatchTest.php
• tests/Feature_v3/Album/AlbumBucketsV3Test.php
• tests/Feature_v3/Album/AlbumChildrenDataV3Test.php
• tests/Feature_v3/Album/AlbumChildrenRightsV3Test.php
• tests/Unit/Services/Cache/CacheKeyProviderTest.php

🚧 Files skipped from review as they are similar to previous changes (6)

• tests/Feature_v2/Album/AlbumSortingBucketDispatchTest.php
• tests/Unit/Services/Cache/CacheKeyProviderTest.php
• docs/specs/4-architecture/features/061-album-timeline-buckets/plan.md
• docs/specs/4-architecture/features/061-album-timeline-buckets/spec.md
• routes/api_v3.php
• docs/specs/4-architecture/features/061-album-timeline-buckets/tasks.md

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

[coderabbitai]

Actionable comments posted: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 140ef0fc-536d-441e-8a2f-ff846ffcb990

📥 Commits

Reviewing files that changed from the base of the PR and between 4363260 and f419345.

📒 Files selected for processing (11)

• app/Http/Controllers/Gallery/AlbumBucketController.php
• app/Http/Controllers/Gallery/AlbumChildrenDataController.php
• app/Http/Resources/GalleryConfigs/AlbumConfig.php
• app/Http/Resources/GalleryConfigs/RootConfig.php
• app/Http/Resources/V3/AlbumChildrenDataResource.php
• app/Policies/AlbumQueryPolicy.php
• docs/specs/3-reference/api-design.md
• docs/specs/4-architecture/features/061-album-timeline-buckets/spec.md
• docs/specs/4-architecture/features/061-album-timeline-buckets/tasks.md
• tests/Feature_v3/Album/AlbumBucketsV3Test.php
• tests/Feature_v3/Album/AlbumChildrenDataV3Test.php

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.