🚧 Assisted vision

[ildyria]

Summary by CodeRabbit

• Documentation
  • Added comprehensive specification, plan, and task checklist for Feature 030: AI Vision Service (facial recognition), covering end-to-end design, 19 implementation increments, APIs, UI flows, and quality gates.
  • Added Feature 030 to the active roadmap with Planning status and P1 priority.
  • Recorded numerous resolved Q-030 decisions: API/webhook contract, callbacks, privacy/search controls, scan/rescan rules, UI behaviors, operational limits, and maintenance/CLI actions.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added comprehensive documentation for Feature 030 (AI Vision Service): new spec, plan, and task checklist; resolved Q-030 open questions (Q-030-01..Q-030-48); and a roadmap entry marking the feature as Planning with P1 priority. All changes are documentation-only.

Changes

Cohort / File(s)	Summary
Feature spec & plan docs/specs/4-architecture/features/030-ai-vision-service/spec.md, docs/specs/4-architecture/features/030-ai-vision-service/plan.md	New detailed specification and implementation plan defining Person/Face/FaceSuggestion models, REST + webhook contracts, scan lifecycle, Python FastAPI service design, privacy rules, UI/CLI endpoints, and 19 implementation increments.
Tasks checklist docs/specs/4-architecture/features/030-ai-vision-service/tasks.md	New task breakdown across Python service, Lychee PHP backend, and Vue3 frontend with verification steps, CI/containerization, and maintenance tasks.
Open questions & roadmap docs/specs/4-architecture/open-questions.md, docs/specs/4-architecture/roadmap.md	Open-questions doc updated with resolved Q-030-01..Q-030-48 and remaining active Q-030 items; roadmap gains Feature 030 entry (Planning, P1) with progress and dates.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 I nibbled notes beneath moonlight glow,
I tracked each face where wild ideas grow.
Specs and plans in tidy little stacks,
I hopped through questions, leaving solved tracks.
A carrot of progress — hop! — now watch it go!

🚥 Pre-merge checks | ✅ 1

✅ 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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 10

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: eda740d4-e176-4108-a2c7-bfa80283677b

📥 Commits

Reviewing files that changed from the base of the PR and between 692b295 and d808e9c.

📒 Files selected for processing (5)

• docs/specs/4-architecture/features/029-ai-vision-service/plan.md
• docs/specs/4-architecture/features/029-ai-vision-service/spec.md
• docs/specs/4-architecture/features/029-ai-vision-service/tasks.md
• docs/specs/4-architecture/open-questions.md
• docs/specs/4-architecture/roadmap.md

[coderabbitai]

Actionable comments posted: 7

♻️ Duplicate comments (3)

docs/specs/4-architecture/open-questions.md (3)

7-10: ⚠️ Potential issue | 🟠 Major

Active-questions status is internally inconsistent.

The table says no active questions, but unresolved Q-030 entries still exist below. Please either list them in the table or mark/remove them as resolved after updating the governing spec/ADR trail.

As per coding guidelines: "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 and, for high-impact clarifications, in an ADR."

Also applies to: 243-450

---

243-594: ⚠️ Potential issue | 🟠 Major

Stale duplicate Q-030 blocks reintroduce conflicting decisions.

This section reintroduces older Q-030 resolutions that conflict with the newer resolved definitions above (e.g., suggestion target and crop storage semantics). Keep only the final canonical resolution per question ID.

Based on learnings: "Treat legacy per-feature Clarifications sections as removed; do not reintroduce them. Resolved clarifications must be folded into the spec's normative sections (requirements, NFR, behaviour/UI, telemetry/policy), with history captured via docs/specs/4-architecture/open-questions.md, ADRs, and session/plan logs."

---

2481-2481: ⚠️ Potential issue | 🟡 Minor

Last updated footer is stale and not at file bottom.

This footer is both outdated for this revision and appears before additional content. Move it to the very end and refresh the date.

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

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2f4b5727-ae76-497b-b74f-191033be8182

📥 Commits

Reviewing files that changed from the base of the PR and between d808e9c and d28ce61.

📒 Files selected for processing (5)

• docs/specs/4-architecture/features/030-ai-vision-service/plan.md
• docs/specs/4-architecture/features/030-ai-vision-service/spec.md
• docs/specs/4-architecture/features/030-ai-vision-service/tasks.md
• docs/specs/4-architecture/open-questions.md
• docs/specs/4-architecture/roadmap.md

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

• docs/specs/4-architecture/roadmap.md

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (5)

docs/specs/4-architecture/features/030-ai-vision-service/tasks.md (1)

357-357: ⚠️ Potential issue | 🟡 Minor

Add the required bottom documentation footer.

The file ends without the required trailing --- and italic *Last updated: ...* block.

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

docs/specs/4-architecture/features/030-ai-vision-service/plan.md (1)

409-409: ⚠️ Potential issue | 🟡 Minor

Add the required documentation footer at the bottom.

Please append --- and italic *Last updated: [date]* at the end of this file.

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

docs/specs/4-architecture/features/030-ai-vision-service/spec.md (3)

12-12: ⚠️ Potential issue | 🟡 Minor

Use the repository ADR path convention (docs/specs/6-decisions/).

Line 12 still points to docs/specs/5-decisions/, which conflicts with the documented ADR location convention.

Based on learnings: "Applies to docs/specs/6-decisions/*.md : Use ADRs only for final decisions. Do not add ADRs during planning; record final, confirmed architectural decisions and architecturally significant clarifications as ADRs under docs/specs/6-decisions/ using the adr-template.md structure."

---

51-51: ⚠️ Potential issue | 🟠 Major

Unify FR-030-08 with the resolved callback_url contract.

Line 51 says Lychee sends callback URL in the request, while Line 591 states callback_url is removed from payload and sourced from VISION_FACE_LYCHEE_API_URL. Keep one canonical behavior.

Based on learnings: "Applies to docs/specs/4-architecture/features/**/*.md : Update feature specs, feature plans, and tasks documents as progress is made to maintain the single source of truth for each feature's requirements, design, and implementation status."

Also applies to: 591-591

---

1008-1008: ⚠️ Potential issue | 🟡 Minor

Add the required bottom footer block.

The spec is missing the trailing --- and italic *Last updated: ...* footer at the end.

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

🧹 Nitpick comments (1)

docs/specs/4-architecture/features/030-ai-vision-service/tasks.md (1)

340-357: Avoid reintroducing per-feature clarification logs in tasks.md.

Lines 340-357 duplicate resolved clarification history inside the task file; keep resolved outcomes in normative spec sections and open-questions/ADR history to avoid drift.

Based on learnings: "Treat legacy per-feature Clarifications sections as removed; do not reintroduce them. Resolved clarifications must be folded into the spec's normative sections (requirements, NFR, behaviour/UI, telemetry/policy), with history captured via docs/specs/4-architecture/open-questions.md, ADRs, and session/plan logs."

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4fac6456-39e9-4949-aebc-1f7bb2ee1afd

📥 Commits

Reviewing files that changed from the base of the PR and between d28ce61 and 85c6d62.

📒 Files selected for processing (3)

• docs/specs/4-architecture/features/030-ai-vision-service/plan.md
• docs/specs/4-architecture/features/030-ai-vision-service/spec.md
• docs/specs/4-architecture/features/030-ai-vision-service/tasks.md