Specification on runner & pre-computations #3902

ildyria · 2025-12-28T20:07:42Z

Summary by CodeRabbit

Documentation
- Added comprehensive specifications and implementation plan for Worker Mode Support, enabling containerized worker queue processing with automatic restart and health checks.
- Added detailed specifications for Album Computed Fields Pre-computation to improve album data retrieval performance.
- Updated roadmap and architectural decision records to reflect new feature planning phases.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2025-12-28T20:07:59Z

📝 Walkthrough

Walkthrough

This pull request introduces comprehensive documentation for two major architectural features and supporting decision records. It adds specifications, implementation plans, and task checklists for Worker Mode Support and Album Computed Fields Pre-computation, along with updates to the open questions corpus and project roadmap.

Changes

Cohort / File(s)	Summary
Worker Mode Feature `docs/specs/4-architecture/features/002-worker-mode/plan.md`, `docs/specs/4-architecture/features/002-worker-mode/spec.md`, `docs/specs/4-architecture/features/002-worker-mode/tasks.md`	Multi-increment implementation plan (I1–I6) for worker mode support with mode detection via LYCHEE_MODE environment variable. Includes entrypoint script modifications, queue validation, Docker Compose extension, graceful shutdown handling, and comprehensive testing strategy. Accompanying spec defines dual operational modes (web/worker), worker configuration options, health checks, and POSIX shell constraints. Tasks file provides detailed checklist across 8 increments with verification commands and expected outcomes.
Album Computed Fields Feature `docs/specs/4-architecture/features/003-album-computed-fields/spec.md`	Comprehensive specification for migrating five computed fields (max_taken_at, min_taken_at, num_children, num_photos, computed_cover_id) to physical database columns. Includes event-driven recomputation workflow, backfill strategy, job-based propagation with concurrency safeguards, deprecation plan, and phased migration approach. Defines functional/non-functional requirements, test strategies, and ADR-driven decision context.
Architectural Decisions & Roadmap `docs/specs/6-decisions/ADR-0003-album-computed-fields-precomputation.md`, `docs/specs/4-architecture/open-questions.md`, `docs/specs/4-architecture/roadmap.md`	New ADR-0003 document establishing event-driven pre-computation architecture with WithoutOverlapping job deduplication and rollback strategy. Open-questions updated with Q-003-09 entry (HIGH priority) discussing multi-user cover selection strategy. Roadmap replaces placeholder with two active features (002, 003) both in Planning/P1 phase, dated 2025-12-28.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Two grand features hop into view,
Worker threads and computed fields too!
Albums glow with pre-made data bright,
While queues dance through day and night.
With specs and plans all checked and true,
Lychee blooms in all we do! 🌸

Pre-merge checks

✅ Passed checks (1 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

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

coderabbitai

Actionable comments posted: 3

Caution

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

⚠️ Outside diff range comments (1)

docs/specs/4-architecture/open-questions.md (1)
1318-1318: Update footer timestamp to match PR date.

Line 1318 shows "Last updated: 2025-12-27" but all changes in this file are dated 2025-12-28 (Q-003-09 and resolved question entries).
🔎 Proposed fix
-*Last updated: 2025-12-27*
+*Last updated: 2025-12-28*

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8ad85ec and 3616774.

📒 Files selected for processing (7)

docs/specs/4-architecture/features/002-worker-mode/plan.md
docs/specs/4-architecture/features/002-worker-mode/spec.md
docs/specs/4-architecture/features/002-worker-mode/tasks.md
docs/specs/4-architecture/features/003-album-computed-fields/spec.md
docs/specs/4-architecture/open-questions.md
docs/specs/4-architecture/roadmap.md
docs/specs/6-decisions/ADR-0003-album-computed-fields-precomputation.md

🧰 Additional context used

📓 Path-based instructions (7)

**/*.md

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.md: Use Markdown format for documentation
At the bottom of documentation files, add an hr line followed by "Last updated: [date of the update]"

Files:

docs/specs/6-decisions/ADR-0003-album-computed-fields-precomputation.md
docs/specs/4-architecture/roadmap.md
docs/specs/4-architecture/features/002-worker-mode/spec.md
docs/specs/4-architecture/features/003-album-computed-fields/spec.md
docs/specs/4-architecture/features/002-worker-mode/plan.md
docs/specs/4-architecture/features/002-worker-mode/tasks.md
docs/specs/4-architecture/open-questions.md

docs/specs/6-decisions/**/*.md

📄 CodeRabbit inference engine (AGENTS.md)

docs/specs/6-decisions/**/*.md: For architecturally significant clarifications (cross-feature/module boundaries, security/telemetry strategy, major NFR trade-offs), create or update an ADR using docs/specs/templates/adr-template.md, then mark the corresponding open-questions row as resolved with links to the spec sections and ADR ID.
Record only confirmed architectural decisions and architecturally significant clarifications as ADRs under docs/specs/6-decisions/ using the adr-template.md, and reference those ADR IDs from the relevant spec sections and open-questions log.
After completing work, summarise any lasting decisions in the appropriate ADR (if applicable).

Files:

docs/specs/6-decisions/ADR-0003-album-computed-fields-precomputation.md

docs/specs/4-architecture/roadmap.md

📄 CodeRabbit inference engine (AGENTS.md)

docs/specs/4-architecture/roadmap.md: Update the roadmap regularly to reflect feature status and progress as work is made.
Keep high-level plans in docs/specs/4-architecture/roadmap.md, store each feature's spec/plan/tasks inside docs/specs/4-architecture/features/-/, and remove plans once work is complete.

Files:

docs/specs/4-architecture/roadmap.md

docs/specs/4-architecture/features/**/*.md

📄 CodeRabbit inference engine (AGENTS.md)

docs/specs/4-architecture/features/**/*.md: Author new specifications, feature plans, and task checklists using docs/specs/templates/feature-spec-template.md, docs/specs/templates/feature-plan-template.md, and docs/specs/templates/feature-tasks-template.md to keep structure, metadata, and verification notes uniform across features.
For any new UI feature or modification, include an ASCII mock-up in the specification (see docs/specs/4-architecture/spec-guidelines/ui-ascii-mockups.md).
When revising a specification, only document fallback or compatibility behaviour if the user explicitly asked for it; if instructions are unclear, pause and request confirmation instead of assuming a fallback.
For every task, refresh the relevant feature plan and note open questions; only move forward once the plan reflects the desired change. Update specs before code.
Update feature specs, feature plans, and tasks documents as progress is made and sync context to disk.
Capture prompt summaries, command sequences, and rationale in the active feature plan or an appendix referenced from it so downstream reviewers know how the change was produced (intent logging).
Track upcoming additions for contract tests, mutation analysis, and security/red-team prompt suites in the plans until automated jobs exist (quality gates).
Publish prompt and tool usage notes alongside the feature plan update so future agents understand how the iteration unfolded.

Files:

docs/specs/4-architecture/features/002-worker-mode/spec.md
docs/specs/4-architecture/features/003-album-computed-fields/spec.md
docs/specs/4-architecture/features/002-worker-mode/plan.md
docs/specs/4-architecture/features/002-worker-mode/tasks.md

docs/specs/4-architecture/features/**/{spec,plan,tasks}.md

📄 CodeRabbit inference engine (AGENTS.md)

docs/specs/4-architecture/features/**/{spec,plan,tasks}.md: Start every feature by updating or creating its specification at docs/specs/4-architecture/features/-/spec.md, followed by plan and tasks documents after clarifications are resolved.
Generate or refresh the feature plan only after the specification is current and high-/medium-impact clarifications are resolved and recorded in the spec (plus ADRs where required).

Files:

docs/specs/4-architecture/features/002-worker-mode/spec.md
docs/specs/4-architecture/features/003-album-computed-fields/spec.md
docs/specs/4-architecture/features/002-worker-mode/plan.md
docs/specs/4-architecture/features/002-worker-mode/tasks.md

docs/specs/4-architecture/features/**/tasks.md

📄 CodeRabbit inference engine (AGENTS.md)

docs/specs/4-architecture/features/**/tasks.md: Maintain a per-feature tasks checklist that mirrors the plan, orders tests before code, and keeps planned increments ≤90 minutes by preferring finer-grained entries and documenting sub-steps when something nears the limit.
Mark each task [x] in the feature's tasks.md as soon as it passes verification. Do not batch task completions—update the checklist after every individual task so progress is always visible.
Before committing, confirm every completed task in tasks.md is marked [x] and the roadmap status reflects current progress (validate task checklist).

Files:

docs/specs/4-architecture/features/002-worker-mode/tasks.md

docs/specs/4-architecture/open-questions.md

📄 CodeRabbit inference engine (AGENTS.md)

docs/specs/4-architecture/open-questions.md: Capture every high-impact clarification question and each medium-impact uncertainty per feature in docs/specs/4-architecture/open-questions.md and, once resolved, record the outcome directly in the spec (requirements, NFR, behaviour/UI, telemetry/policy sections).
Log high- and medium-impact open questions in docs/specs/4-architecture/open-questions.md and remove each row as soon as it is resolved, ensuring the answer is captured first in the governing spec's normative sections.
Update or close entries in docs/specs/4-architecture/open-questions.md after completing work.

Files:

docs/specs/4-architecture/open-questions.md

🧠 Learnings (23)

📓 Common learnings

Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:12:18.082Z
Learning: Applies to docs/specs/4-architecture/open-questions.md : Update or close entries in docs/specs/4-architecture/open-questions.md after completing work.

Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:12:18.082Z
Learning: Applies to docs/specs/4-architecture/features/**/*.md : For every task, refresh the relevant feature plan and note open questions; only move forward once the plan reflects the desired change. Update specs before code.

Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:12:18.082Z
Learning: Applies to docs/specs/4-architecture/open-questions.md : Capture every high-impact clarification question and each medium-impact uncertainty per feature in docs/specs/4-architecture/open-questions.md and, once resolved, record the outcome directly in the spec (requirements, NFR, behaviour/UI, telemetry/policy sections).

Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:12:18.082Z
Learning: Applies to docs/specs/6-decisions/**/*.md : For architecturally significant clarifications (cross-feature/module boundaries, security/telemetry strategy, major NFR trade-offs), create or update an ADR using docs/specs/templates/adr-template.md, then mark the corresponding open-questions row as resolved with links to the spec sections and ADR ID.

Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:12:18.082Z
Learning: Applies to docs/specs/4-architecture/open-questions.md : Log high- and medium-impact open questions in docs/specs/4-architecture/open-questions.md and remove each row as soon as it is resolved, ensuring the answer is captured first in the governing spec's normative sections.

Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:12:18.082Z
Learning: Applies to docs/specs/4-architecture/features/**/*.md : Update feature specs, feature plans, and tasks documents as progress is made and sync context to disk.

Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:12:18.082Z
Learning: Applies to docs/specs/4-architecture/roadmap.md : Keep high-level plans in docs/specs/4-architecture/roadmap.md, store each feature's spec/plan/tasks inside docs/specs/4-architecture/features/<NNN>-<feature-name>/, and remove plans once work is complete.

Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:12:18.082Z
Learning: Applies to docs/specs/4-architecture/features/**/*.md : Track upcoming additions for contract tests, mutation analysis, and security/red-team prompt suites in the plans until automated jobs exist (quality gates).

Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:12:18.082Z
Learning: Applies to docs/specs/4-architecture/features/**/tasks.md : Maintain a per-feature tasks checklist that mirrors the plan, orders tests before code, and keeps planned increments ≤90 minutes by preferring finer-grained entries and documenting sub-steps when something nears the limit.

Learnt from: CR
Repo: LycheeOrg/Lychee PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:12:18.082Z
Learning: Applies to docs/specs/5-decisions/**/*.md : Before planning or implementation, skim ADRs under docs/specs/5-decisions whose related-features/specs entries reference the active feature ID so high-impact clarifications and architectural decisions are treated as required context.