From 42ad52fc46f4853fdf0801dcd4f731f84167db94 Mon Sep 17 00:00:00 2001 From: "Leivur R. Djurhuus" Date: Sun, 1 Mar 2026 11:45:16 -0600 Subject: [PATCH] feat: add comprehensive upgrade plan for phases 5 to 11, including detailed feature descriptions, implementation strategies, data model changes, new API routes, and third-party library dependencies --- UPGRADE_PLAN.md | 1124 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1124 insertions(+) create mode 100644 UPGRADE_PLAN.md diff --git a/UPGRADE_PLAN.md b/UPGRADE_PLAN.md new file mode 100644 index 0000000..74f289f --- /dev/null +++ b/UPGRADE_PLAN.md @@ -0,0 +1,1124 @@ +# HP CG Production Tracker — Upgrade Plan (Phase 5+) + +> This document covers all planned upgrades beyond the Phase 1–4 foundation. Each feature +> area includes scope, implementation approach, new/modified files, and dependencies. +> Features are grouped by domain and ordered within each phase by priority. + +--- + +## Table of Contents + +1. [Phase 5: Visual Review & Annotation System](#phase-5-visual-review--annotation-system) +2. [Phase 6: Workload & Resource Management](#phase-6-workload--resource-management) +3. [Phase 7: Automation & Workflow Engine](#phase-7-automation--workflow-engine) +4. [Phase 8: Asset Intelligence & AI Review Integration](#phase-8-asset-intelligence--ai-review-integration) +5. [Phase 9: Advanced Reporting & Analytics](#phase-9-advanced-reporting--analytics) +6. [Phase 10: Collaboration Enhancements](#phase-10-collaboration-enhancements) +7. [Phase 11: Quality of Life & Polish](#phase-11-quality-of-life--polish) +8. [Data Model Changes Summary](#data-model-changes-summary) +9. [New API Routes Summary](#new-api-routes-summary) +10. [New Pages Summary](#new-pages-summary) +11. [Third-Party Libraries](#third-party-libraries) + +--- + +## Phase 5: Visual Review & Annotation System + +The cornerstone upgrade. Transforms the tracker from a status management tool into a +true visual production platform. Every CG deliverable ultimately produces an image — +reviewing those images with precision is the core workflow. + +### 5.1 — Image Viewer with High-Fidelity Zoom + +**What:** Full-screen image viewer with smooth pan/zoom up to 200%+ for pixel-level +inspection. Supports common CG output formats (PNG, TIFF, EXR preview, JPEG). + +**Why:** HP's quality bar for CG renders is extremely high. Producers and artists need to +inspect fine details (texture seams, aliasing, color banding) at pixel level without +downloading files to a separate app. + +**Implementation:** +- Canvas-based viewer component using `` with WebGL acceleration for large images +- Zoom controls: scroll wheel, pinch gesture (touch), toolbar buttons, keyboard shortcuts (+/-) +- Zoom levels: fit-to-view, 50%, 100% (1:1 pixel), 150%, 200%, and free zoom +- Pan via click-drag when zoomed in; minimap overlay showing viewport position on full image +- Pixel coordinate display in status bar (x, y) with color value readout (RGB/Hex) +- Preload adjacent revisions for instant switching +- Support for high-DPI displays (retina) with proper pixel ratio handling + +**Key files:** +- `src/components/review/image-viewer.tsx` — Core canvas viewer component +- `src/components/review/zoom-controls.tsx` — Zoom toolbar + keyboard handler +- `src/components/review/minimap.tsx` — Navigation minimap overlay +- `src/hooks/use-image-viewer.ts` — Pan/zoom state management hook + +**Dependencies:** None (uses native Canvas API + WebGL) + +--- + +### 5.2 — Pixel-Accurate Annotations + +**What:** Draw annotations directly on images — circles, rectangles, arrows, freehand, +and text labels. Each annotation is anchored to image coordinates (not screen coordinates) +so they remain accurate at any zoom level. Annotations are linked to comments. + +**Why:** "See the artifact on the left edge of the product, 3rd shelf" is ambiguous. +Clicking on the exact pixel and drawing a circle around it eliminates miscommunication +between producers, artists, and HP reviewers. + +**Implementation:** +- SVG overlay layer on top of the canvas viewer (annotations render in SVG for crisp + scaling, image renders in canvas for performance) +- Annotation tools: rectangle, ellipse, arrow, freehand path, text label, pin (point marker) +- Color picker for annotation stroke (default: accent red for visibility) +- Annotations stored as JSON in the database with image-space coordinates +- Each annotation is linked to a Comment record — clicking an annotation highlights the + associated comment in the sidebar, and vice versa +- Annotation visibility toggle (show/hide all, show/hide per revision round) +- Undo/redo stack for annotation drawing session + +**Data model additions:** +```prisma +model Annotation { + id String @id @default(cuid()) + commentId String + comment Comment @relation(fields: [commentId], references: [id], onDelete: Cascade) + revisionId String + revision Revision @relation(fields: [revisionId], references: [id], onDelete: Cascade) + type AnnotationType // RECTANGLE, ELLIPSE, ARROW, FREEHAND, TEXT, PIN + data Json // { x, y, width, height, points[], text, color, strokeWidth } + imageX Float // anchor point in image coordinates + imageY Float + createdById String + createdBy User @relation(fields: [createdById], references: [id]) + createdAt DateTime @default(now()) +} + +enum AnnotationType { + RECTANGLE + ELLIPSE + ARROW + FREEHAND + TEXT + PIN +} +``` + +**Key files:** +- `src/components/review/annotation-layer.tsx` — SVG overlay with tool switching +- `src/components/review/annotation-tools.tsx` — Toolbar with tool selection +- `src/components/review/annotation-renderer.tsx` — Renders individual annotation shapes +- `src/lib/services/annotation-service.ts` — CRUD for annotations +- `src/lib/validators/annotation.ts` — Zod schemas +- `src/hooks/use-annotations.ts` — TanStack Query hook + +**Dependencies:** Requires 5.1 (Image Viewer) + +--- + +### 5.3 — Side-by-Side Version Comparison + +**What:** Compare two revisions of the same deliverable using multiple comparison modes: +side-by-side, overlay with opacity slider, horizontal/vertical wipe (swipe divider), +and onion skin. + +**Why:** CG revision changes are often subtle — slightly adjusted lighting, minor geometry +fixes, color grading tweaks. Direct visual comparison makes it obvious what changed +between rounds. + +**Implementation:** +- Dual-pane viewer sharing a synchronized zoom/pan state (pan one, both move) +- Comparison modes: + - **Side-by-side:** Two viewers, synced zoom/pan, with version labels + - **Overlay:** Single viewer, second image overlaid with adjustable opacity (0-100%) + - **Wipe:** Draggable vertical or horizontal divider revealing one image on each side + - **Onion skin:** Alternating between images at adjustable interval (useful for animation) +- Dropdown selectors for left/right revision (default: previous round vs. current round) +- Annotations from both versions shown with version-colored borders +- Keyboard shortcuts: 1/2/3/4 to switch modes, left/right arrows to cycle revisions + +**Key files:** +- `src/components/review/comparison-viewer.tsx` — Dual-pane orchestrator +- `src/components/review/wipe-divider.tsx` — Draggable split control +- `src/components/review/overlay-controls.tsx` — Opacity slider + mode toggles +- `src/app/(app)/projects/[projectId]/deliverables/[deliverableId]/review/page.tsx` — Review page + +**Dependencies:** Requires 5.1 (Image Viewer) + +--- + +### 5.4 — Review Sessions & Playlists + +**What:** Curate a set of deliverables/revisions into a review session. Walk through them +sequentially with per-item approve/request-changes/reject actions. Shareable via link. + +**Why:** Producers regularly review batches of deliverables with HP stakeholders. A +structured review session replaces scattered email threads and ensures every item gets +a documented decision. + +**Implementation:** +- Review Session entity containing ordered list of items (deliverable stage + revision) +- Session states: DRAFT -> IN_PROGRESS -> COMPLETED +- Presenter mode: full-screen, navigate with arrow keys, decision buttons prominent +- Each item shows: image viewer, annotation layer, comment sidebar, decision buttons +- Summary view: grid of thumbnails with approve/reject status badges +- Shareable link with optional expiry and access control (internal only vs. external) +- Auto-generate session from filters (e.g., "all Catalog Images in Review for Project X") + +**Data model additions:** +```prisma +model ReviewSession { + id String @id @default(cuid()) + name String + status ReviewSessionStatus @default(DRAFT) + createdById String + createdBy User @relation(fields: [createdById], references: [id]) + organizationId String + organization Organization @relation(fields: [organizationId], references: [id]) + shareToken String? @unique + expiresAt DateTime? + items ReviewSessionItem[] + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt +} + +model ReviewSessionItem { + id String @id @default(cuid()) + sessionId String + session ReviewSession @relation(fields: [sessionId], references: [id], onDelete: Cascade) + deliverableStageId String + deliverableStage DeliverableStage @relation(fields: [deliverableStageId], references: [id]) + revisionId String? + revision Revision? @relation(fields: [revisionId], references: [id]) + sortOrder Int + decision ReviewDecision? + decisionNote String? + decidedById String? + decidedBy User? @relation(fields: [decidedById], references: [id]) + decidedAt DateTime? +} + +enum ReviewSessionStatus { + DRAFT + IN_PROGRESS + COMPLETED +} + +enum ReviewDecision { + APPROVED + CHANGES_REQUESTED + REJECTED +} +``` + +**Key files:** +- `src/app/(app)/reviews/page.tsx` — Review sessions list +- `src/app/(app)/reviews/[sessionId]/page.tsx` — Session presenter view +- `src/components/review/session-builder.tsx` — Create/edit session with item picker +- `src/components/review/session-presenter.tsx` — Full-screen walkthrough mode +- `src/components/review/session-summary.tsx` — Thumbnail grid with decisions +- `src/lib/services/review-session-service.ts` — Business logic +- `src/hooks/use-review-sessions.ts` — TanStack Query hooks +- API routes: `/api/reviews/`, `/api/reviews/[sessionId]/`, `/api/reviews/[sessionId]/items/` + +**Dependencies:** Requires 5.1 + 5.2 (Image Viewer + Annotations) + +--- + +## Phase 6: Workload & Resource Management + +Gives producers visibility into team capacity so they can make informed assignment +decisions and prevent burnout/bottlenecks. + +### 6.1 — Capacity Planning View + +**What:** Visual overview of each artist's assignment load across all projects, broken +down by week. Shows allocated vs. available capacity with overallocation warnings. + +**Implementation:** +- New page: `/workload` — grid with artists as rows, weeks as columns +- Each cell shows number of active assignments + status breakdown (colored segments) +- Configurable capacity threshold per user (default: 5 concurrent assignments) +- Overallocation highlighted in red when assignments exceed threshold +- Click a cell to drill down into specific assignments for that artist/week +- Filter by project, stage type, date range +- Data sourced from existing StageAssignment + DeliverableStage records + +**Data model additions:** +```prisma +// Add to User model: +maxCapacity Int @default(5) // max concurrent assignments +``` + +**Key files:** +- `src/app/(app)/workload/page.tsx` — Capacity planning page +- `src/components/workload/capacity-grid.tsx` — Artist x Week grid +- `src/components/workload/capacity-cell.tsx` — Individual cell with status bars +- `src/components/workload/capacity-detail-popover.tsx` — Drill-down assignment list +- `src/lib/services/workload-service.ts` — Aggregation queries +- API route: `/api/workload/` + +--- + +### 6.2 — Utilization Heatmaps + +**What:** Color-coded heatmap showing team utilization over time. Instantly spot who's +overloaded, who's underutilized, and how load trends over weeks/months. + +**Implementation:** +- Heatmap component integrated into workload page as an alternate visualization +- Color scale: light green (low load) -> yellow (moderate) -> red (overallocated) +- Toggle between absolute count and percentage of capacity +- Time range: 4-week, 8-week, 12-week, custom +- Export to image/PDF for stakeholder reports + +**Key files:** +- `src/components/workload/utilization-heatmap.tsx` — Heatmap visualization (recharts) +- `src/components/workload/heatmap-legend.tsx` — Color scale legend + +**Dependencies:** Requires 6.1 (Capacity Planning data) + +--- + +### 6.3 — Skill-Based Assignment Suggestions + +**What:** Tag users with specialties (modeling, texturing, lighting, compositing, animation). +When assigning an artist to a stage, suggest best-fit artists based on skill match, +current workload, and availability. + +**Implementation:** +- New `Skill` model and many-to-many with User +- Predefined skill set relevant to CG pipeline: Modeling, Texturing, UV Mapping, Lighting, + Rendering, Compositing, Animation, Rigging, Photography, Retouching +- Each pipeline stage template maps to recommended skills +- Assignment dialog shows suggested artists sorted by: skill match -> lowest current load +- Visual indicator showing each suggestion's match score and current utilization + +**Data model additions:** +```prisma +model Skill { + id String @id @default(cuid()) + name String @unique + users UserSkill[] + stages StageSkillRequirement[] +} + +model UserSkill { + userId String + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + skillId String + skill Skill @relation(fields: [skillId], references: [id], onDelete: Cascade) + level SkillLevel @default(INTERMEDIATE) + + @@id([userId, skillId]) +} + +model StageSkillRequirement { + stageTemplateId String + stageTemplate PipelineStageTemplate @relation(fields: [stageTemplateId], references: [id]) + skillId String + skill Skill @relation(fields: [skillId], references: [id]) + importance Int @default(1) // 1=nice-to-have, 2=important, 3=required + + @@id([stageTemplateId, skillId]) +} + +enum SkillLevel { + JUNIOR + INTERMEDIATE + SENIOR + LEAD +} +``` + +**Key files:** +- `src/app/(app)/settings/skills/page.tsx` — Skill management page (admin) +- `src/components/assignments/skill-match-suggestions.tsx` — Suggested artists list +- `src/lib/services/skill-service.ts` — Matching algorithm +- API routes: `/api/skills/`, `/api/users/[userId]/skills/` + +**Dependencies:** Requires 6.1 (capacity data for load-aware suggestions) + +--- + +## Phase 7: Automation & Workflow Engine + +Reduces manual overhead by automating repetitive status changes, notifications, and +escalations based on configurable triggers. + +### 7.1 — Trigger-Based Automations + +**What:** Configurable "when X happens, do Y" rules that execute automatically. +Eliminates manual status bumping and notification sending for predictable workflows. + +**Example rules:** +- When all Catalog Images are APPROVED -> auto-advance Hero/Packaging/Photocomps/360/Dynamic to NOT_STARTED +- When a deliverable is 2 days past due -> notify the assigned PM +- When an artist submits a revision -> auto-set stage to IN_REVIEW +- When a review session is completed -> update all approved items' stages to APPROVED + +**Implementation:** +- Automation rules stored in database, configurable per organization +- Rule structure: Trigger (event type + conditions) -> Actions (status change, notification, assignment) +- Event bus: when a stage/revision/assignment changes, evaluate matching rules +- Built-in rule templates for common CG pipeline workflows +- Admin UI to create, edit, enable/disable rules +- Execution log for audit trail (what fired, when, what it did) + +**Data model additions:** +```prisma +model AutomationRule { + id String @id @default(cuid()) + name String + description String? + organizationId String + organization Organization @relation(fields: [organizationId], references: [id]) + isEnabled Boolean @default(true) + trigger Json // { event, conditions[] } + actions Json // { type, params }[] + createdById String + createdBy User @relation(fields: [createdById], references: [id]) + executions AutomationExecution[] + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt +} + +model AutomationExecution { + id String @id @default(cuid()) + ruleId String + rule AutomationRule @relation(fields: [ruleId], references: [id], onDelete: Cascade) + triggeredBy Json // the event that triggered it + result Json // what actions were taken + status ExecutionStatus + executedAt DateTime @default(now()) +} + +enum ExecutionStatus { + SUCCESS + PARTIAL_FAILURE + FAILURE +} +``` + +**Supported trigger events:** +- `stage.status_changed` — with conditions on stage type, old/new status +- `revision.submitted` — new revision uploaded +- `review.decision_made` — approve/reject in review session +- `deadline.approaching` — N days before due date +- `deadline.passed` — due date exceeded +- `assignment.created` — artist assigned to stage + +**Supported actions:** +- `update_stage_status` — change a stage's status +- `send_notification` — create notification for specified users/roles +- `create_assignment` — auto-assign a user +- `send_webhook` — POST to external URL (future AI review integration point) + +**Key files:** +- `src/app/(app)/settings/automations/page.tsx` — Automation rules management +- `src/components/automations/rule-builder.tsx` — Visual rule editor +- `src/components/automations/execution-log.tsx` — Audit log viewer +- `src/lib/services/automation-service.ts` — Rule evaluation engine +- `src/lib/automation/event-bus.ts` — Event dispatcher +- `src/lib/automation/action-executor.ts` — Action runner +- API routes: `/api/automations/`, `/api/automations/[ruleId]/`, `/api/automations/[ruleId]/executions/` + +**Note:** The existing dependency engine (`src/lib/pipeline/dependency-engine.ts`) already +handles stage unblocking. The automation engine extends this with user-configurable rules +beyond the hardcoded pipeline dependencies. + +--- + +### 7.2 — Multi-Level Approval Chains + +**What:** Define approval workflows requiring sign-off from multiple stakeholders in +sequence. For example: Artist Lead -> Producer -> Client Contact. + +**Implementation:** +- Approval chain template per organization (configurable per stage type) +- Each step has: approver role/user, required or optional, auto-advance on approve +- Status tracking per step: PENDING -> APPROVED / REJECTED +- When all required steps are approved, the stage is marked APPROVED +- If any step is rejected, stage goes back to IN_PROGRESS with feedback +- Visual progress indicator showing which approval steps are complete +- Email/in-app notification at each step to the next approver + +**Data model additions:** +```prisma +model ApprovalChain { + id String @id @default(cuid()) + name String + organizationId String + organization Organization @relation(fields: [organizationId], references: [id]) + stageType String? // null = applies to all stages + steps ApprovalStep[] + createdAt DateTime @default(now()) +} + +model ApprovalStep { + id String @id @default(cuid()) + chainId String + chain ApprovalChain @relation(fields: [chainId], references: [id], onDelete: Cascade) + stepOrder Int + approverRole Role? // role-based (any PRODUCER) + approverUserId String? // specific user + approverUser User? @relation(fields: [approverUserId], references: [id]) + isRequired Boolean @default(true) + autoAdvance Boolean @default(true) + approvalRecords ApprovalRecord[] +} + +model ApprovalRecord { + id String @id @default(cuid()) + deliverableStageId String + deliverableStage DeliverableStage @relation(fields: [deliverableStageId], references: [id]) + stepId String + step ApprovalStep @relation(fields: [stepId], references: [id]) + decision ReviewDecision + note String? + decidedById String + decidedBy User @relation(fields: [decidedById], references: [id]) + decidedAt DateTime @default(now()) +} +``` + +**Key files:** +- `src/app/(app)/settings/approvals/page.tsx` — Approval chain configuration +- `src/components/approvals/chain-builder.tsx` — Visual chain editor (drag to reorder steps) +- `src/components/approvals/approval-progress.tsx` — Step-by-step progress indicator +- `src/lib/services/approval-service.ts` — Chain evaluation and advancement +- API routes: `/api/approval-chains/`, `/api/stages/[stageId]/approve/` + +--- + +### 7.3 — Project Templates + +**What:** Save a full project configuration (deliverable list, stage settings, default +assignments, automation rules) as a reusable template. One-click project creation for +repeat HP SKU types. + +**Why:** HP product shoots often follow the same structure — same deliverable types, same +pipeline, same team assignments. Templates eliminate 15-20 minutes of manual setup per project. + +**Implementation:** +- "Save as Template" action on any existing project +- Template captures: deliverable names/types, stage configurations, default assignments + (by role, not specific user), automation rules, priority defaults +- "New Project from Template" in project creation dialog +- Template library page with preview, edit, duplicate, delete +- Org-level templates (shared) + personal templates + +**Data model additions:** +```prisma +model ProjectTemplate { + id String @id @default(cuid()) + name String + description String? + organizationId String + organization Organization @relation(fields: [organizationId], references: [id]) + createdById String + createdBy User @relation(fields: [createdById], references: [id]) + isShared Boolean @default(true) + configuration Json // full template config + deliverables ProjectTemplateDeliverable[] + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt +} + +model ProjectTemplateDeliverable { + id String @id @default(cuid()) + templateId String + template ProjectTemplate @relation(fields: [templateId], references: [id], onDelete: Cascade) + name String + type String? + priority Priority @default(MEDIUM) + defaultAssignments Json? // [{ role, stageType }] + sortOrder Int +} +``` + +**Key files:** +- `src/app/(app)/templates/page.tsx` — Template library +- `src/components/templates/template-card.tsx` — Template preview card +- `src/components/templates/template-builder.tsx` — Create/edit template +- `src/lib/services/template-service.ts` — Template CRUD + instantiation +- API routes: `/api/templates/`, `/api/templates/[templateId]/instantiate/` + +--- + +## Phase 8: Asset Intelligence & AI Review Integration + +Ensures uploaded assets meet HP's strict quality standards through automated validation +and future AI-powered review. The AI Review Engine is being developed as a separate +service and will connect via API. + +### 8.1 — File Validation on Upload + +**What:** Automatically validate uploaded files against spec requirements: resolution, +color space, file format, file size, aspect ratio. Reject non-conforming files with +clear error messages before they enter the review pipeline. + +**Implementation:** +- Validation rules configurable per stage type (e.g., Catalog Images require 4000x4000px + minimum, sRGB color space, PNG or TIFF) +- Server-side validation using `sharp` for image metadata extraction +- Client-side pre-validation for instant feedback (file type, basic dimensions) +- Validation report: pass/fail per check with details +- Override option for producers (with reason logged) when files are intentionally non-standard +- Batch validation for multi-file uploads + +**Data model additions:** +```prisma +model AssetSpec { + id String @id @default(cuid()) + organizationId String + organization Organization @relation(fields: [organizationId], references: [id]) + stageType String // which pipeline stage this spec applies to + name String + rules Json // { minWidth, minHeight, maxFileSize, allowedFormats[], colorSpace, dpi } + isActive Boolean @default(true) + validationResults AssetValidationResult[] + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt +} + +model AssetValidationResult { + id String @id @default(cuid()) + revisionId String + revision Revision @relation(fields: [revisionId], references: [id], onDelete: Cascade) + specId String + spec AssetSpec @relation(fields: [specId], references: [id]) + passed Boolean + results Json // [{ check, expected, actual, passed }] + overrideById String? + overrideBy User? @relation(fields: [overrideById], references: [id]) + overrideReason String? + validatedAt DateTime @default(now()) +} +``` + +**Key files:** +- `src/app/(app)/settings/asset-specs/page.tsx` — Spec configuration (admin) +- `src/components/upload/file-validator.tsx` — Validation UI with pass/fail report +- `src/lib/services/asset-validation-service.ts` — Validation engine +- `src/lib/validators/asset-specs.ts` — Zod schemas for spec rules +- API routes: `/api/asset-specs/`, `/api/revisions/[revisionId]/validate/` + +**New dependency:** `sharp` (image processing — already commonly used in Next.js) + +--- + +### 8.2 — Thumbnail & Preview Generation + +**What:** Auto-generate web-optimized thumbnails and preview images from uploaded +high-resolution assets. Enables fast browsing without downloading 100MB+ source files. + +**Implementation:** +- On upload: generate 3 sizes — thumbnail (200px), preview (1200px), full (original) +- Use `sharp` for server-side image processing +- Store generated previews alongside originals (same storage, different paths) +- Lazy loading with blur placeholder (LQIP — low quality image placeholder) +- Support TIFF/EXR to JPEG/WebP conversion for browser viewing +- Background job queue for processing (avoid blocking upload response) + +**Key files:** +- `src/lib/services/preview-service.ts` — Image processing pipeline +- `src/lib/jobs/generate-previews.ts` — Background processing job +- `src/components/common/optimized-image.tsx` — Image component with lazy load + LQIP + +--- + +### 8.3 — AI Review Engine Integration Point + +**What:** API integration layer for the external AI Review Engine. When connected, the +AI engine analyzes uploaded renders for quality issues (noise, artifacts, color accuracy, +composition) and returns structured feedback. + +**Why:** HP demands exceptional quality consistency. Manual review catches most issues but +human reviewers have throughput limits and can miss subtle problems. The AI engine acts +as a first-pass QC layer. + +**Implementation:** +- Webhook endpoint that the AI Review Engine calls with analysis results +- Structured result format: overall score, per-check scores, flagged regions (coordinates), + severity levels, suggested actions +- AI review results displayed alongside human review in the annotation viewer +- AI-flagged regions rendered as annotations with a distinct style (dashed border, AI icon) +- Configuration: which stages trigger AI review, confidence thresholds, auto-block on fail +- Dashboard widget showing AI review pass rates and common issue categories + +**Data model additions:** +```prisma +model AIReviewResult { + id String @id @default(cuid()) + revisionId String + revision Revision @relation(fields: [revisionId], references: [id], onDelete: Cascade) + overallScore Float // 0-100 + passed Boolean + checks Json // [{ name, score, severity, details }] + flaggedRegions Json // [{ x, y, width, height, issue, severity }] + engineVersion String + processingTimeMs Int + createdAt DateTime @default(now()) +} +``` + +**Key files:** +- `src/app/api/webhooks/ai-review/route.ts` — Incoming webhook from AI engine +- `src/components/review/ai-review-overlay.tsx` — AI annotations on image viewer +- `src/components/review/ai-review-summary.tsx` — Score card + issue list +- `src/lib/services/ai-review-service.ts` — Result processing + storage +- API routes: `/api/webhooks/ai-review/`, `/api/revisions/[revisionId]/ai-review/` + +**Dependencies:** External AI Review Engine (separate project). This phase only builds +the integration layer — the engine itself is developed independently. + +--- + +## Phase 9: Advanced Reporting & Analytics + +Builds on the existing dashboard with deeper insights for project management and +stakeholder reporting. + +### 9.1 — Velocity & Throughput Metrics + +**What:** Track deliverables completed per week, average time per stage, and identify +pipeline bottlenecks. + +**Implementation:** +- Time tracking derived from stage status change timestamps (already captured in `updatedAt`) +- Metrics: throughput (deliverables completed/week), cycle time (brief intake to final approval), + stage dwell time (average time spent in each stage), bottleneck detection (stages with + longest average dwell) +- Trend charts over configurable time windows (4/8/12/26 weeks) +- Filterable by project, stage type, artist, priority +- Compare periods (this month vs. last month) + +**Key files:** +- `src/components/dashboard/velocity-chart.tsx` — Throughput trend line +- `src/components/dashboard/cycle-time-chart.tsx` — Average cycle time breakdown +- `src/components/dashboard/bottleneck-chart.tsx` — Stage dwell time comparison +- `src/lib/services/analytics-service.ts` — Metric aggregation queries + +--- + +### 9.2 — Burndown Charts + +**What:** Per-project burndown showing remaining deliverables over time with projected +completion date based on current velocity. + +**Implementation:** +- Chart shows: ideal burndown line, actual burndown line, projection line +- Scope changes (added deliverables) shown as step-ups in the remaining count +- Confidence interval on projection based on velocity variance +- Warning when projected completion exceeds deadline + +**Key files:** +- `src/components/dashboard/burndown-chart.tsx` — Burndown visualization +- `src/components/dashboard/projection-engine.ts` — Velocity-based projection math + +--- + +### 9.3 — Client-Facing Dashboard (Read-Only Portal) + +**What:** Simplified, read-only view for HP stakeholders to check project status without +needing full app access. Accessible via secure share link. + +**Implementation:** +- New route group: `src/app/(portal)/` — minimal layout, no sidebar, branded header +- Share link generation with token-based auth (no account required) +- Configurable visibility: which projects, which data fields are exposed +- Shows: project status overview, deliverable progress grid, latest revision thumbnails, + timeline, pending decisions +- No edit capabilities — view only +- Optional password protection + expiry on share links +- Mobile-optimized layout + +**Data model additions:** +```prisma +model PortalLink { + id String @id @default(cuid()) + token String @unique + organizationId String + organization Organization @relation(fields: [organizationId], references: [id]) + projectIds String[] // which projects are visible + createdById String + createdBy User @relation(fields: [createdById], references: [id]) + password String? // bcrypt hashed, optional + expiresAt DateTime? + lastAccessedAt DateTime? + accessCount Int @default(0) + isActive Boolean @default(true) + createdAt DateTime @default(now()) +} +``` + +**Key files:** +- `src/app/(portal)/[token]/page.tsx` — Portal landing page +- `src/app/(portal)/[token]/projects/[projectId]/page.tsx` — Project detail view +- `src/components/portal/portal-header.tsx` — Branded header with HP/Oliver logos +- `src/components/portal/project-overview.tsx` — Status summary grid +- `src/lib/services/portal-service.ts` — Token validation + scoped data access +- `src/middleware.ts` — Portal route auth handling +- API routes: `/api/portal/`, `/api/portal/[token]/` + +--- + +### 9.4 — SLA Tracking + +**What:** Define target turnaround times per stage type. Measure actual vs. target and +flag SLA breaches in real-time. + +**Implementation:** +- SLA configuration per organization per stage type (e.g., Model Prep: 3 business days, + Catalog Images: 5 business days) +- Real-time SLA status: on-track (green), at-risk (yellow, >75% elapsed), breached (red) +- SLA dashboard widget showing compliance rate and breach trends +- Notification when an SLA is at risk (configurable threshold) +- Historical SLA compliance reports (filterable by project, stage, artist, date range) +- Business-hours-aware calculation (exclude weekends, optionally holidays) + +**Data model additions:** +```prisma +model SLATarget { + id String @id @default(cuid()) + organizationId String + organization Organization @relation(fields: [organizationId], references: [id]) + stageType String + targetHours Int // business hours + warningThreshold Float @default(0.75) // warn at 75% of target + isActive Boolean @default(true) + createdAt DateTime @default(now()) +} +``` + +**Key files:** +- `src/app/(app)/settings/sla/page.tsx` — SLA target configuration +- `src/components/dashboard/sla-compliance-chart.tsx` — Compliance rate visualization +- `src/components/stages/sla-indicator.tsx` — Inline SLA status badge +- `src/lib/services/sla-service.ts` — SLA calculation engine (business hours aware) + +--- + +## Phase 10: Collaboration Enhancements + +Deepens the communication layer to reduce dependency on email and Slack for +project-related discussions. + +### 10.1 — Rich @Mentions with Deep Linking + +**What:** @mention users in comments with autocomplete. Mentioned users receive +notifications with deep links directly to the relevant deliverable/stage/comment. + +**Implementation:** +- `@` trigger in comment input opens user autocomplete dropdown +- Mentions stored as structured data: `{ userId, displayName, position }` within comment text +- Notification created for each mentioned user with direct link to the comment +- Mentioned user's name rendered as a clickable link to their profile +- Support @mentioning roles (e.g., @producers) to notify all users with that role + +**Key files:** +- `src/components/comments/mention-input.tsx` — Comment input with @mention autocomplete +- `src/components/comments/mention-renderer.tsx` — Renders mention inline with link +- Update `src/lib/services/comment-service.ts` — Extract mentions + create notifications + +--- + +### 10.2 — Project Activity Feed + +**What:** Unified chronological stream of all activity on a project: status changes, +comments, uploads, assignments, approvals. Single source of truth for "what happened." + +**Implementation:** +- Activity log entries auto-generated on every state change (already partially done via + notifications — extend to a dedicated activity model) +- Filterable by: event type, user, deliverable, date range +- Compact view (one-liner per event) and expanded view (with details) +- Infinite scroll with cursor-based pagination + +**Data model additions:** +```prisma +model ActivityEntry { + id String @id @default(cuid()) + projectId String + project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) + deliverableId String? + deliverable Deliverable? @relation(fields: [deliverableId], references: [id]) + stageId String? + userId String + user User @relation(fields: [userId], references: [id]) + type ActivityType + summary String // human-readable: "Jane moved Catalog Images to IN_REVIEW" + metadata Json? // structured event data for rich rendering + createdAt DateTime @default(now()) +} + +enum ActivityType { + STATUS_CHANGE + COMMENT_ADDED + REVISION_SUBMITTED + ASSIGNMENT_CHANGED + APPROVAL_DECISION + FILE_UPLOADED + DEADLINE_CHANGED + PRIORITY_CHANGED + PROJECT_CREATED + DELIVERABLE_CREATED +} +``` + +**Key files:** +- `src/components/activity/activity-feed.tsx` — Feed component with filters +- `src/components/activity/activity-entry.tsx` — Individual entry renderer +- `src/lib/services/activity-service.ts` — Logging + querying +- API route: `/api/projects/[projectId]/activity/` + +--- + +### 10.3 — External Review Links + +**What:** Generate watermarked, time-limited URLs for external stakeholders (e.g., HP +brand team) to view specific deliverables without creating an account. + +**Implementation:** +- Generate unique token-based URL for specific deliverable/revision +- Watermark overlay on images showing: reviewer email/name, date, "CONFIDENTIAL" +- Configurable expiry (24h, 48h, 7 days, 30 days) +- Access logging (who viewed, when, from what IP) +- Revoke link capability +- Comment capability for external reviewers (optional, requires email verification) + +**Key files:** +- `src/app/(external)/review/[token]/page.tsx` — External review page +- `src/components/review/watermark-overlay.tsx` — Dynamic watermark renderer +- `src/lib/services/external-link-service.ts` — Token generation + validation +- API routes: `/api/external-links/`, `/api/external-links/[token]/` + +**Note:** Overlaps with 5.4 Review Sessions share functionality and 9.3 Client Portal. +These should share the underlying token/auth infrastructure but serve different use +cases (bulk review vs. individual deliverable vs. project overview). + +--- + +## Phase 11: Quality of Life & Polish + +Incremental UX improvements that make the daily workflow faster and more pleasant. + +### 11.1 — Saved Filters & Custom Views + +**What:** Let users save their current filter/sort/column configuration as a named view. +Quick-switch between saved views. Share views with team. + +**Implementation:** +- "Save View" button in table/board/timeline toolbar +- View stores: filters, sort order, column visibility, column order, grouping +- Personal views (private) and shared views (visible to org) +- Quick access via dropdown in view toolbar +- Pin favorite views for one-click access +- URL-encode view ID so saved views are linkable + +**Data model additions:** +```prisma +model SavedView { + id String @id @default(cuid()) + name String + userId String + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + organizationId String + organization Organization @relation(fields: [organizationId], references: [id]) + projectId String? // null = cross-project view + viewType ViewType // TABLE, BOARD, TIMELINE + configuration Json // { filters, sort, columns, groupBy } + isShared Boolean @default(false) + isPinned Boolean @default(false) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt +} + +enum ViewType { + TABLE + BOARD + TIMELINE +} +``` + +**Key files:** +- `src/components/views/saved-view-picker.tsx` — Dropdown with saved views +- `src/components/views/save-view-dialog.tsx` — Save/edit view dialog +- `src/lib/services/saved-view-service.ts` — CRUD +- API routes: `/api/views/`, `/api/views/[viewId]/` + +--- + +### 11.2 — Extended Command Palette Actions + +**What:** Extend the existing Cmd+K palette with quick-actions beyond navigation: +"approve and advance," "assign to me," "mark blocked," "start review session." + +**Implementation:** +- Add action commands alongside existing search/navigation commands +- Context-aware actions: show relevant actions based on current page/selected item +- Recent commands history +- Fuzzy search across all command types +- Keyboard shortcut hints shown inline + +**Key files:** +- Update `src/components/layout/command-palette.tsx` — Add action commands +- `src/lib/commands/action-registry.ts` — Registry of available actions + handlers + +--- + +### 11.3 — Offline Indicator & Optimistic Updates + +**What:** Detect when connectivity drops, show indicator, queue changes locally, and +sync when connection resumes. Extends existing TanStack Query optimistic updates. + +**Implementation:** +- Network status detection via `navigator.onLine` + periodic ping +- Visual indicator in topbar when offline (amber banner) +- TanStack Query already supports optimistic updates — extend to queue failed mutations +- Sync queue with retry logic when back online +- Conflict resolution: last-write-wins with toast notification if server state diverged + +**Key files:** +- `src/components/layout/offline-indicator.tsx` — Banner component +- `src/hooks/use-network-status.ts` — Network detection hook +- `src/lib/sync/mutation-queue.ts` — Offline mutation queue + +--- + +### 11.4 — Batch Upload with Auto-Matching + +**What:** Drag-and-drop multiple files onto a project and auto-match to deliverables by +file naming convention (e.g., `SKU-12345_catalog_v2.png` matches Catalog Images deliverable). + +**Implementation:** +- Drop zone on project detail page accepting multiple files +- Naming convention parser: configurable regex patterns per organization +- Preview table showing: file name, matched deliverable, matched stage, confidence +- Manual override for mismatches or unmatched files +- Bulk upload with progress indicator +- Auto-create revisions for matched files + +**Key files:** +- `src/components/upload/batch-upload-zone.tsx` — Drag-and-drop area +- `src/components/upload/file-matcher.tsx` — Auto-match preview table +- `src/lib/services/file-matching-service.ts` — Naming convention parser + matcher +- `src/lib/validators/naming-convention.ts` — Configurable pattern schemas + +--- + +## Data Model Changes Summary + +| Phase | New Models | Modified Models | +|-------|-----------|----------------| +| 5 | Annotation, ReviewSession, ReviewSessionItem | Comment (add annotations relation) | +| 6 | Skill, UserSkill, StageSkillRequirement | User (add maxCapacity, skills) | +| 7 | AutomationRule, AutomationExecution, ApprovalChain, ApprovalStep, ApprovalRecord, ProjectTemplate, ProjectTemplateDeliverable | — | +| 8 | AssetSpec, AssetValidationResult, AIReviewResult | Revision (add validation/AI relations) | +| 9 | PortalLink, SLATarget | — | +| 10 | ActivityEntry | — | +| 11 | SavedView | — | + +**Total new models: 20** + +--- + +## New API Routes Summary + +| Phase | Routes | +|-------|--------| +| 5 | `/api/annotations/`, `/api/reviews/`, `/api/reviews/[id]/items/` | +| 6 | `/api/workload/`, `/api/skills/`, `/api/users/[id]/skills/` | +| 7 | `/api/automations/`, `/api/automations/[id]/executions/`, `/api/approval-chains/`, `/api/stages/[id]/approve/`, `/api/templates/`, `/api/templates/[id]/instantiate/` | +| 8 | `/api/asset-specs/`, `/api/revisions/[id]/validate/`, `/api/webhooks/ai-review/`, `/api/revisions/[id]/ai-review/` | +| 9 | `/api/portal/`, `/api/portal/[token]/`, `/api/analytics/velocity/`, `/api/analytics/sla/` | +| 10 | `/api/projects/[id]/activity/`, `/api/external-links/` | +| 11 | `/api/views/` | + +**Total new API routes: ~22** + +--- + +## New Pages Summary + +| Phase | Pages | +|-------|-------| +| 5 | Review page (per deliverable), Review sessions list, Session presenter | +| 6 | Workload/capacity page, Skills management (settings) | +| 7 | Automations management (settings), Approval chains (settings), Template library | +| 8 | Asset specs (settings) | +| 9 | Client portal (external), SLA configuration (settings) | +| 10 | Activity feed (per project), External review page | +| 11 | — (enhancements to existing pages) | + +**Total new pages: ~12** + +--- + +## Third-Party Libraries + +| Library | Purpose | Phase | +|---------|---------|-------| +| `sharp` | Server-side image processing (validation, thumbnails, previews) | 8 | +| `fabric.js` or native Canvas/SVG | Annotation drawing on canvas (evaluate during 5.2) | 5 | +| `bcryptjs` | Password hashing for portal links | 9 | + +**Philosophy:** Minimize new dependencies. Most features build on the existing stack +(React, TanStack Query, shadcn/ui, recharts, Prisma). Canvas/SVG APIs are native browser +capabilities. Only add libraries when they provide substantial value over a custom solution. + +--- + +## Implementation Priority & Dependencies + +``` +Phase 5 (Visual Review) ─── standalone, highest impact + | + |-- 5.1 Image Viewer <-- foundation for everything + |-- 5.2 Annotations <-- requires 5.1 + |-- 5.3 Comparison <-- requires 5.1 + +-- 5.4 Review Sessions <-- requires 5.1 + 5.2 + +Phase 6 (Workload) ─── standalone, high impact for producers + | + |-- 6.1 Capacity Grid <-- foundation + |-- 6.2 Heatmaps <-- requires 6.1 + +-- 6.3 Skill Matching <-- requires 6.1 + +Phase 7 (Automation) ─── standalone, reduces manual work + | + |-- 7.1 Trigger Rules <-- foundation + |-- 7.2 Approval Chains <-- standalone within phase + +-- 7.3 Templates <-- standalone within phase + +Phase 8 (Asset Intelligence) ─── requires Phase 5 for full value + | + |-- 8.1 File Validation <-- standalone + |-- 8.2 Preview Generation <-- standalone + +-- 8.3 AI Integration <-- requires external engine + 8.1 + 8.2 + +Phase 9 (Reporting) ─── benefits from Phase 6 + 7 data +Phase 10 (Collaboration) ─── benefits from Phase 5 +Phase 11 (QoL) ─── standalone incremental improvements, can be interleaved +``` + +--- + +## Estimated Scope + +| Phase | New Models | New Routes | New Pages | Components | +|-------|-----------|-----------|-----------|------------| +| 5 | 4 | 3 | 3 | ~15 | +| 6 | 3 | 3 | 2 | ~8 | +| 7 | 6 | 6 | 3 | ~10 | +| 8 | 3 | 4 | 1 | ~8 | +| 9 | 2 | 4 | 2 | ~8 | +| 10 | 1 | 2 | 2 | ~6 | +| 11 | 1 | 1 | 0 | ~8 | +| **Total** | **20** | **~23** | **~13** | **~63** | + +--- + +*Document version: 1.0 — Created 2026-03-01* +*To be updated as features are refined and priorities shift.* \ No newline at end of file