db82eb4fed
Replace FeedbackSeverity enum (Critical/Major/Minor/Suggestion) with a simple isActionItem boolean. Annotations default to action items (things the artist must fix). Any item can be toggled to an info callout (context that doesn't need action). Progress bar and carry-forward only count action items. Screenshot paste limited to 5MB with user notification. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
946 lines
39 KiB
Markdown
946 lines
39 KiB
Markdown
# HP CG Production Tracker — Roadmap
|
||
|
||
> Single source of truth for project status and remaining work.
|
||
> Previous planning documents (IMPLEMENTATION_PLAN.md, UPGRADE_PLAN.md) are archived in `docs/archive/`.
|
||
|
||
*Last updated: 2026-03-14 (Phase 2 complete)*
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
1. [What's Built](#whats-built)
|
||
2. [Remaining Work — Priority Order](#remaining-work--priority-order)
|
||
- [A. Visual Review Tool](#a-visual-review-tool)
|
||
- [B. Collaboration Enhancements](#b-collaboration-enhancements)
|
||
- [C. Reporting Completions](#c-reporting-completions)
|
||
- [D. Automation Completions](#d-automation-completions)
|
||
- [E. Asset Intelligence](#e-asset-intelligence)
|
||
- [F. Quality of Life](#f-quality-of-life)
|
||
- [G. Docker Deployment](#g-docker-deployment)
|
||
3. [Data Model Status](#data-model-status)
|
||
4. [Architecture Reference](#architecture-reference)
|
||
|
||
---
|
||
|
||
## What's Built
|
||
|
||
### Core Foundation (Phases 1–4)
|
||
|
||
| Feature | Status |
|
||
|---|---|
|
||
| Project scaffold (Next.js, TS, Tailwind, Prisma, Auth.js) | ✅ Complete |
|
||
| Design system (Oliver Agency palette, Montserrat + Inter, light/dark) | ✅ Complete |
|
||
| Auth — SSO (Google + Microsoft Entra ID) + dev bypass | ✅ Complete |
|
||
| Project CRUD + deliverable CRUD with auto-pipeline | ✅ Complete |
|
||
| User management + role assignment | ✅ Complete |
|
||
| Dependency engine + stage state machine | ✅ Complete |
|
||
| Artist assignments + My Work page | ✅ Complete |
|
||
| Table view (TanStack Table, filters, sort, column visibility) | ✅ Complete |
|
||
| Board view (Kanban drag-and-drop) | ✅ Complete |
|
||
| Timeline view (Gantt with dependencies) | ✅ Complete |
|
||
| Dashboard (KPIs, charts, overdue alerts) | ✅ Complete |
|
||
| Revision tracking (rounds, feedback notes, history) | ✅ Complete |
|
||
| Threaded comment system | ✅ Complete |
|
||
| Notification system (in-app bell + full page) | ✅ Complete |
|
||
| Excel import (bulk upload from Master CG Tracker) | ✅ Complete |
|
||
| Excel export | ✅ Complete |
|
||
| Deadline tracking (approaching/overdue + notifications) | ✅ Complete |
|
||
| Command palette (Cmd+K) | ✅ Complete |
|
||
| Bulk operations (multi-select → batch status/assignment/priority) | ✅ Complete |
|
||
| Loading skeletons, error boundaries, empty states | ✅ Complete |
|
||
| Responsive design + mobile sidebar | ✅ Complete |
|
||
| Accessibility (skip-to-content, ARIA, focus-visible) | ✅ Complete |
|
||
| Stage date override + scheduling features | ✅ Complete |
|
||
|
||
### Beyond Phase 4 (implemented opportunistically)
|
||
|
||
| Feature | Notes |
|
||
|---|---|
|
||
| **Workload capacity grid** | Artist × Week grid with status bars, overallocation warnings, 4/8/12-week projections |
|
||
| **Workload utilization heatmap** | Color-coded heatmap on workload page (green → yellow → red by load). Added in `c8f88c6`. |
|
||
| **Calendar view** | Monthly calendar with event pills, filters, day detail. *Not in original plan.* |
|
||
| **Calendar heatmap** | Heatmap overlay on calendar grid with toggle and bar visualization. Added in `bac6d4c`. *Not in original plan.* |
|
||
| **Automation rule engine** | Full trigger/action engine with event bus, rule evaluator, action executor, execution log |
|
||
| **Semantic search (pgvector + Ollama)** | Embedding service, hybrid search, pgvector columns on Project + Deliverable |
|
||
| **AI Chat panel** | SSE streaming chat with tool calls (search_entities), entity cards, project/deliverable context. *Not in original plan.* |
|
||
| **Weekly executive report** | Full report page at `/reports/weekly/[date]` with KPI strip, completed, deadlines, at-risk, upcoming sections |
|
||
| **Skill data model** | `Skill`, `UserSkill`, `StageSkillRequirement` in schema with seed data — **no assignment UI yet** |
|
||
|
||
### Phase 2: Multi-Brand Ready (Dynamic Pipelines)
|
||
|
||
| Feature | Status |
|
||
|---|---|
|
||
| **WP1 — RBAC Foundation** | ✅ Complete |
|
||
| `Permission` enum (20 perms) + `OrgRolePermission` model | ✅ |
|
||
| `requireAuth(permission?)` replaces `getAuthSession()` across all 28 API routes | ✅ |
|
||
| Default permissions per role (ADMIN/PRODUCER/ARTIST) with org-level overrides | ✅ |
|
||
| Permission matrix settings page (`/settings/permissions`) | ✅ |
|
||
| **WP2 — Org Hardening** | ✅ Complete |
|
||
| Denormalized `organizationId` on Deliverable + DeliverableStage | ✅ |
|
||
| `assertOrgAccess()` on all project/deliverable/stage API routes | ✅ |
|
||
| Backfill script (`scripts/backfill-org-ids.ts`) | ✅ |
|
||
| **WP3 — Dynamic Pipeline Schema** | ✅ Complete |
|
||
| `PipelineTemplate`, `PipelineStageDefinition`, `PipelineStageDependencyV2` models | ✅ |
|
||
| `pipelineTemplateId` on Project, `stageDefinitionId` on DeliverableStage | ✅ |
|
||
| Stage resolver normalizes old/new definitions | ✅ |
|
||
| `deliverable-service.ts` creates stages from project's dynamic pipeline | ✅ |
|
||
| Migration script (`scripts/migrate-to-dynamic-pipelines.ts`) | ✅ |
|
||
| **WP4 — Pipeline Template CRUD** | ✅ Complete |
|
||
| Full service: list, get, create, update, archive, duplicate | ✅ |
|
||
| Stage CRUD: add, update, remove, reorder | ✅ |
|
||
| Dependency management with cycle detection | ✅ |
|
||
| Pipeline validation (cycles, orphans, root stages) | ✅ |
|
||
| 8 API routes under `/api/pipelines/` | ✅ |
|
||
| **WP5 — Pipeline Builder UI** | ✅ Complete |
|
||
| `@xyflow/react` dependency graph visualization | ✅ |
|
||
| Pipeline list page (`/settings/pipelines`) with create, duplicate, archive | ✅ |
|
||
| Pipeline editor page with two-panel layout (stage list + dependency graph) | ✅ |
|
||
| Stage edit sheet, validation banner, custom edge with delete | ✅ |
|
||
| **WP6 — Invite System & Org Onboarding** | ✅ Complete |
|
||
| `Invitation` model with token-based accept flow | ✅ |
|
||
| Invitation service: create, list, revoke, accept | ✅ |
|
||
| Team settings page (`/settings/team`) with member list + invite form | ✅ |
|
||
| **WP7 — Custom Fields & Notification Rules** | ✅ Complete |
|
||
| `CustomFieldDefinition` model + `customFields` JSON on Project/Deliverable | ✅ |
|
||
| `NotificationRule` model (org-scoped event + conditions + channels) | ✅ |
|
||
| CRUD services, validators, hooks, API routes for both | ✅ |
|
||
| Custom fields settings page (`/settings/fields`) | ✅ |
|
||
| Notification rules settings page (`/settings/notifications`) | ✅ |
|
||
|
||
---
|
||
|
||
## Remaining Work — Priority Order
|
||
|
||
---
|
||
|
||
### A. Visual Review Tool
|
||
|
||
The highest-impact remaining feature. CG production review is fundamentally visual — this is a single, unified review tool built in stages, each independently useful. No throwaway prototypes.
|
||
|
||
The review tool lives at its own dedicated page (`/projects/[projectId]/deliverables/[deliverableId]/review`) and is also accessible from the stage detail sheet via a "Review" button. It's the primary interface for inspecting renders, comparing revisions, annotating feedback, and making approve/reject decisions.
|
||
|
||
**Infrastructure built so far:**
|
||
- Review page at `/projects/[projectId]/deliverables/[deliverableId]/review` with image viewer, upload, gallery
|
||
- Canvas-based image viewer with zoom/pan/minimap, retina support
|
||
- Image upload API with PNG alpha compositing + TIFF conversion (sharp)
|
||
- `Revision.attachments` JSON stores `{ referenceImage, currentImage }` with metadata
|
||
- Comparison viewer with 4 modes: side-by-side, wipe, overlay, toggle
|
||
- SVG annotation layer with 7 tools (rect, ellipse, arrow, freehand, text, pin, screenshot paste)
|
||
- Annotation model in Prisma schema (requires `db push` to sync)
|
||
- Annotation API: GET/POST `/api/revisions/[id]/annotations`, PATCH/DELETE `/api/revisions/[id]/annotations/[id]`
|
||
- Annotations linked to comments (transactional create), undo/redo stack
|
||
- Screenshot paste: Cmd+V pastes clipboard image as draggable/resizable callout
|
||
- "Review" button on stage cards in deliverable detail page
|
||
|
||
**New dependency for all stages:** `sharp` (server-side PNG alpha compositing + image processing)
|
||
|
||
---
|
||
|
||
#### A1 — Review Viewer & Image Upload `[x]`
|
||
|
||
The foundation. A dedicated review page with a high-fidelity image viewer and the upload infrastructure to get images into the system.
|
||
|
||
**What gets built:**
|
||
- **Review page** at `/projects/[projectId]/deliverables/[deliverableId]/review` — full-width layout with image viewer as the centerpiece, toolbar at top, panels on the sides
|
||
- **Image viewer** — canvas-based with WebGL acceleration for large CG renders (4000×4000px+)
|
||
- Zoom: scroll wheel, pinch gesture, keyboard (+/-), toolbar presets (Fit, 50%, 100%, 150%, 200%)
|
||
- Pan: click-drag when zoomed, minimap overlay showing viewport position
|
||
- Pixel info: coordinate display (x, y) + color readout (RGB/Hex) in status bar
|
||
- High-DPI (retina) support with proper pixel ratio handling
|
||
- **Image upload** — drag-and-drop zone + click-to-browse for reference and current render per revision round
|
||
- Supports PNG, TIFF, JPEG, WebP up to 50MB
|
||
- **PNG alpha compositing on upload** — flatten transparent PNGs onto white (#FFF) background server-side using `sharp`, so CG renders with semi-transparent drop shadows display correctly in all comparison and overlay modes
|
||
- Store flattened version for viewing + optionally keep original transparent PNG for download
|
||
- Extend `Revision.attachments` JSON: `{ referenceImage?: { url, filename, size, uploadedAt, originalUrl? }, currentImage?: { ... } }`
|
||
- **Image gallery** — thumbnail strip of all uploaded images across revision rounds, with round number labels. Click any to load it in the viewer.
|
||
- **"Review" button** on stage cards in the deliverable detail page — opens the review page for that stage
|
||
|
||
**New API endpoints:**
|
||
- `POST /api/stages/[stageId]/revisions/[revisionId]/upload` — multipart form upload (type: "reference" | "current")
|
||
- `DELETE /api/stages/[stageId]/revisions/[revisionId]/upload` — remove an uploaded image
|
||
|
||
**Key files:**
|
||
- `src/app/(app)/projects/[projectId]/deliverables/[deliverableId]/review/page.tsx` — Review page
|
||
- `src/components/review/image-viewer.tsx` — Core canvas viewer
|
||
- `src/components/review/zoom-controls.tsx` — Zoom toolbar + keyboard handler
|
||
- `src/components/review/minimap.tsx` — Navigation minimap overlay
|
||
- `src/components/review/image-upload-zone.tsx` — Drag-and-drop upload
|
||
- `src/components/review/image-gallery.tsx` — Thumbnail strip across rounds
|
||
- `src/hooks/use-image-viewer.ts` — Pan/zoom state management
|
||
- `src/lib/services/upload-service.ts` — File storage + PNG alpha compositing
|
||
|
||
---
|
||
|
||
#### A2 — Version Comparison `[x]`
|
||
|
||
Compare two revisions of the same deliverable stage. This is the daily workhorse — producers and artists check what changed between rounds.
|
||
|
||
**What gets built:**
|
||
- **Comparison modes** (toolbar toggle in the review page):
|
||
- **Side-by-side** — dual panes with synced zoom/pan, version labels
|
||
- **A-B Slider (wipe)** — draggable vertical/horizontal divider revealing one image on each side
|
||
- **Overlay** — second image overlaid with adjustable opacity (0–100%)
|
||
- **Toggle** — click or press Space to crossfade between images (default on narrow screens)
|
||
- **Revision selectors** — dropdowns for left/right revision (default: previous round vs. current)
|
||
- **Synced navigation** — zoom/pan one pane, both move together across all modes
|
||
- **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
|
||
|
||
**Dependencies:** Requires A1
|
||
|
||
---
|
||
|
||
#### A3 — Annotations `[x]`
|
||
|
||
Draw pixel-accurate annotations directly on images. Each annotation is anchored to image coordinates so it stays accurate at any zoom level, and is linked to a comment for context.
|
||
|
||
**What gets built:**
|
||
- **SVG overlay layer** on top of the canvas viewer (annotations in SVG for crisp scaling, image in canvas for performance)
|
||
- **Annotation tools** — toolbar with: rectangle, ellipse, arrow, freehand path, text label, pin (point marker)
|
||
- **Screenshot paste callouts** — Cmd+V / Ctrl+V pastes a clipboard image directly onto the review image as a floating, repositionable callout. Use case: paste a screenshot of a Maya attribute editor panel, a Photoshop layer setting, or a cropped reference to show the artist exactly what you mean. Callouts can be:
|
||
- **Moved** — drag to reposition anywhere on the image
|
||
- **Resized** — corner handles to scale up/down
|
||
- **Bordered** — automatic contrast border so the callout stands out against the render
|
||
- **Linked to a comment** — same as other annotations, the pasted screenshot becomes part of the feedback thread
|
||
- Stored as a small image (uploaded to server, URL in annotation data) anchored to image coordinates like any other annotation
|
||
- **Color picker** for annotation stroke (default: accent red for visibility against CG renders)
|
||
- **Image-coordinate anchoring** — annotations stored in image space, rendered correctly at any zoom
|
||
- **Comment linking** — each annotation creates or attaches to a Comment record; clicking an annotation highlights its comment in the sidebar, and vice versa
|
||
- **Visibility controls** — show/hide all, show/hide per revision round, show resolved vs. open
|
||
- **Undo/redo** for drawing sessions
|
||
|
||
**New data model:**
|
||
```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
|
||
data Json // { x, y, width, height, points[], text, color, strokeWidth, imageUrl? }
|
||
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 SCREENSHOT }
|
||
```
|
||
|
||
**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 shapes
|
||
- `src/components/review/screenshot-callout.tsx` — Pasted screenshot with drag/resize handles
|
||
- `src/lib/services/annotation-service.ts` — CRUD
|
||
- `src/lib/validators/annotation.ts` — Zod schemas
|
||
- `src/hooks/use-annotations.ts` — TanStack Query hook
|
||
|
||
**Dependencies:** Requires A1
|
||
|
||
---
|
||
|
||
#### A4 — Revision History Timeline `[x]`
|
||
|
||
A collapsible sidebar panel in the review page showing the full version history for a deliverable stage. The connective tissue between annotations, comparison, and feedback — provides the longitudinal view across all rounds.
|
||
|
||
**What gets built:**
|
||
- **Vertical timeline** in a collapsible right-side panel, each revision round as a node:
|
||
- Thumbnail preview of that round's submitted image
|
||
- Round number + status badge (Submitted, Changes Requested, Approved)
|
||
- Submitted by (name + avatar) + timestamp
|
||
- Annotation count (clickable to filter annotation layer to that round)
|
||
- Comment thread summary — first line + total count
|
||
- Decision record — who approved/rejected, when, with what note
|
||
- **Click any round** to load that version in the viewer with its annotations
|
||
- **Keyboard navigation** — up/down arrows to move through rounds
|
||
- **Comparison integration** — select two rounds from the timeline to open them in comparison mode (A2)
|
||
- **Filtering** — show all rounds, show only rounds with feedback, show only decision points
|
||
|
||
**No new data model** — read-only aggregation over existing `Revision`, `Comment`, and `Annotation` records.
|
||
|
||
**Key files:**
|
||
- `src/components/review/revision-timeline.tsx` — Main timeline panel
|
||
- `src/components/review/revision-node.tsx` — Individual round node
|
||
- `src/components/review/revision-comments.tsx` — Per-round comment display
|
||
- `src/components/review/revision-annotations-summary.tsx` — Annotation count + filters
|
||
- `src/hooks/use-revision-history.ts` — TanStack Query hook aggregating revisions + comments + annotations
|
||
|
||
**Dependencies:** Requires A1. Enhanced by A3 (annotation counts and filtering).
|
||
|
||
---
|
||
|
||
#### A5 — Feedback Checklist (Artist Action Items) `[x]`
|
||
|
||
Every annotation and actionable comment becomes a structured to-do item on a checklist for the assigned artist. Closes the feedback-to-fix loop.
|
||
|
||
**The feedback loop:**
|
||
1. Reviewer draws annotation or posts actionable comment
|
||
2. System auto-creates a FeedbackItem linked to the annotation/comment
|
||
3. Artist sees checklist — action items with direct links to annotations on the image
|
||
4. Artist works through items — checks each off with optional resolution note
|
||
5. Artist submits new revision — unchecked action items carry forward with a warning
|
||
6. Reviewer verifies — can confirm resolution or reopen
|
||
|
||
**Two item types (simplified from 4-level severity):**
|
||
- **Action Item** (default) — something the artist needs to fix. Has checkbox, can be resolved/verified.
|
||
- **Info Callout** — context or reference that doesn't require action (e.g., "FYI the client prefers warmer tones"). No checkbox. Can be toggled from action item and vice versa.
|
||
|
||
**Where the checklist appears (3 locations):**
|
||
1. **Review page — Feedback Panel** (primary): full checklist with action items first, then info callouts. Progress bar counts only action items. Filter by type and status.
|
||
2. **My Work page** — feedback badge per assignment ("5 open items")
|
||
3. **Stage card on deliverable page** — compact badge ("4/7 resolved") for action items
|
||
|
||
**New data model:**
|
||
```prisma
|
||
model FeedbackItem {
|
||
id String @id @default(cuid())
|
||
deliverableStageId String
|
||
deliverableStage DeliverableStage @relation(...)
|
||
revisionId String
|
||
revision Revision @relation(...)
|
||
annotationId String?
|
||
annotation Annotation? @relation(...)
|
||
commentId String?
|
||
comment Comment? @relation(...)
|
||
summary String
|
||
isActionItem Boolean @default(true)
|
||
status FeedbackStatus @default(OPEN)
|
||
sortOrder Int @default(0)
|
||
assignedToId String?
|
||
createdById String
|
||
resolvedById String?
|
||
resolvedAt DateTime?
|
||
resolutionNote String?
|
||
verifiedById String?
|
||
verifiedAt DateTime?
|
||
carriedFromId String? // carried forward from prior round
|
||
createdAt DateTime @default(now())
|
||
updatedAt DateTime @updatedAt
|
||
@@map("feedback_items")
|
||
}
|
||
|
||
enum FeedbackStatus { OPEN IN_PROGRESS RESOLVED VERIFIED REOPENED }
|
||
```
|
||
|
||
**Key files:**
|
||
- `src/components/review/feedback-checklist.tsx` — Main checklist panel
|
||
- `src/components/review/feedback-item.tsx` — Individual item with resolve action
|
||
- `src/components/review/feedback-progress-bar.tsx` — Progress bar
|
||
- `src/components/my-work/feedback-summary.tsx` — Inline checklist on My Work
|
||
- `src/components/stages/feedback-indicator.tsx` — Compact badge for stage cards
|
||
- `src/lib/services/feedback-service.ts` — CRUD, auto-creation, carry-forward logic
|
||
- `src/hooks/use-feedback-items.ts`
|
||
|
||
**Dependencies:** Requires A3 (annotations to generate items from) + A4 (timeline for round context)
|
||
|
||
---
|
||
|
||
#### A6 — Review Sessions & Playlists `[ ]`
|
||
|
||
Curate a batch of deliverables into a structured review session. Walk through them sequentially in presenter mode with per-item decisions. The formal review workflow for HP stakeholder reviews.
|
||
|
||
**What gets built:**
|
||
- **Session builder** — pick deliverables/stages to include, drag to reorder, auto-generate from filters ("all Catalog Images in Review for Project X")
|
||
- **Presenter mode** — full-screen, navigate with arrow keys, image viewer with annotations, comment sidebar, prominent approve/request-changes/reject buttons per item
|
||
- **Summary view** — thumbnail grid with decision status badges, overall session progress
|
||
- **Session states** — DRAFT → IN_PROGRESS → COMPLETED
|
||
- **Shareable link** with optional expiry and access control
|
||
|
||
**New data model:**
|
||
```prisma
|
||
model ReviewSession {
|
||
id String @id @default(cuid())
|
||
name String
|
||
status ReviewSessionStatus @default(DRAFT)
|
||
createdById String
|
||
organizationId String
|
||
shareToken String? @unique
|
||
expiresAt DateTime?
|
||
items ReviewSessionItem[]
|
||
createdAt DateTime @default(now())
|
||
updatedAt DateTime @updatedAt
|
||
}
|
||
|
||
model ReviewSessionItem {
|
||
id String @id @default(cuid())
|
||
sessionId String
|
||
deliverableStageId String
|
||
revisionId String?
|
||
sortOrder Int
|
||
decision ReviewDecision?
|
||
decisionNote String?
|
||
decidedById String?
|
||
decidedAt DateTime?
|
||
}
|
||
|
||
enum ReviewSessionStatus { DRAFT IN_PROGRESS COMPLETED }
|
||
enum ReviewDecision { APPROVED CHANGES_REQUESTED REJECTED }
|
||
```
|
||
|
||
**Key files:**
|
||
- `src/app/(app)/reviews/page.tsx` — Session list
|
||
- `src/app/(app)/reviews/[sessionId]/page.tsx` — Session presenter view
|
||
- `src/components/review/session-builder.tsx` — Create/edit session
|
||
- `src/components/review/session-presenter.tsx` — Full-screen walkthrough
|
||
- `src/components/review/session-summary.tsx` — Thumbnail grid with decisions
|
||
- `src/lib/services/review-session-service.ts`
|
||
|
||
**Dependencies:** Requires A1 + A3
|
||
|
||
---
|
||
|
||
### B. Collaboration Enhancements
|
||
|
||
---
|
||
|
||
#### B1 — Rich @Mentions with Deep Linking
|
||
|
||
**What:** `@` trigger in comment input opens user autocomplete. Mentioned users get a notification with a direct link to the comment.
|
||
|
||
**Key files:**
|
||
- `src/components/comments/mention-input.tsx`
|
||
- `src/components/comments/mention-renderer.tsx`
|
||
- Update `src/lib/services/comment-service.ts` — extract mentions + create notifications
|
||
|
||
---
|
||
|
||
#### B2 — Project Activity Feed
|
||
|
||
**What:** Unified chronological stream of all activity on a project — status changes, comments, uploads, assignments, approvals.
|
||
|
||
**New data model:**
|
||
```prisma
|
||
model ActivityEntry {
|
||
id String @id @default(cuid())
|
||
projectId String
|
||
deliverableId String?
|
||
stageId String?
|
||
userId String
|
||
type ActivityType
|
||
summary String
|
||
metadata Json?
|
||
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`
|
||
- `src/components/activity/activity-entry.tsx`
|
||
- `src/lib/services/activity-service.ts`
|
||
- `src/app/api/projects/[projectId]/activity/route.ts`
|
||
|
||
---
|
||
|
||
#### B3 — External Review Links
|
||
|
||
**What:** Token-based URLs for external HP stakeholders to view specific deliverables without an account. Optional watermark (reviewer name, date, CONFIDENTIAL), configurable expiry, access logging, revoke capability.
|
||
|
||
**Key files:**
|
||
- `src/app/(external)/review/[token]/page.tsx`
|
||
- `src/components/review/watermark-overlay.tsx`
|
||
- `src/lib/services/external-link-service.ts`
|
||
|
||
---
|
||
|
||
### C. Reporting Completions
|
||
|
||
---
|
||
|
||
#### C1 — Velocity & Throughput Metrics
|
||
|
||
**What:** Deliverables completed per week, average time per stage, bottleneck detection. Trend charts over 4/8/12/26-week windows.
|
||
|
||
**Key files:**
|
||
- `src/components/dashboard/velocity-chart.tsx`
|
||
- `src/components/dashboard/cycle-time-chart.tsx`
|
||
- `src/components/dashboard/bottleneck-chart.tsx`
|
||
- `src/lib/services/analytics-service.ts`
|
||
|
||
---
|
||
|
||
#### C2 — Burndown Charts
|
||
|
||
**What:** Per-project burndown with ideal line, actual line, and velocity-based projection with confidence interval. Warning when projection exceeds deadline.
|
||
|
||
**Key files:**
|
||
- `src/components/dashboard/burndown-chart.tsx`
|
||
- `src/components/dashboard/projection-engine.ts`
|
||
|
||
---
|
||
|
||
#### C3 — Client-Facing Dashboard (Read-Only Portal)
|
||
|
||
**What:** Simplified read-only view for HP stakeholders via secure share link. No account required. Configurable visibility, optional password + expiry.
|
||
|
||
**New data model:**
|
||
```prisma
|
||
model PortalLink {
|
||
id String @id @default(cuid())
|
||
token String @unique
|
||
organizationId String
|
||
projectIds String[]
|
||
createdById String
|
||
password String?
|
||
expiresAt DateTime?
|
||
lastAccessedAt DateTime?
|
||
accessCount Int @default(0)
|
||
isActive Boolean @default(true)
|
||
createdAt DateTime @default(now())
|
||
}
|
||
```
|
||
|
||
**Key files:**
|
||
- `src/app/(portal)/[token]/page.tsx`
|
||
- `src/app/(portal)/[token]/projects/[projectId]/page.tsx`
|
||
- `src/components/portal/portal-header.tsx`
|
||
- `src/lib/services/portal-service.ts`
|
||
|
||
**New dependency:** `bcryptjs` (password hashing for portal links)
|
||
|
||
---
|
||
|
||
#### C4 — SLA Tracking
|
||
|
||
**What:** Target turnaround times per stage type. Real-time on-track / at-risk / breached status. Business-hours-aware calculation. Compliance dashboard widget.
|
||
|
||
**New data model:**
|
||
```prisma
|
||
model SLATarget {
|
||
id String @id @default(cuid())
|
||
organizationId String
|
||
stageType String
|
||
targetHours Int
|
||
warningThreshold Float @default(0.75)
|
||
isActive Boolean @default(true)
|
||
createdAt DateTime @default(now())
|
||
}
|
||
```
|
||
|
||
**Key files:**
|
||
- `src/app/(app)/settings/sla/page.tsx`
|
||
- `src/components/dashboard/sla-compliance-chart.tsx`
|
||
- `src/components/stages/sla-indicator.tsx`
|
||
- `src/lib/services/sla-service.ts`
|
||
|
||
---
|
||
|
||
### D. Automation Completions
|
||
|
||
The automation rule engine (Phase 7.1) is fully built. These features extend it.
|
||
|
||
---
|
||
|
||
#### D1 — Automation Rules UI
|
||
|
||
**What:** Admin interface to create, edit, enable/disable automation rules. The engine exists — this is the management UI it's missing.
|
||
|
||
**Key files:**
|
||
- `src/app/(app)/settings/automations/page.tsx`
|
||
- `src/components/automations/rule-builder.tsx`
|
||
- `src/components/automations/execution-log.tsx`
|
||
|
||
---
|
||
|
||
#### D2 — Multi-Level Approval Chains
|
||
|
||
**What:** Approval workflows requiring sign-off from multiple stakeholders in sequence. Each step: approver role/user, required/optional, auto-advance on approve. Visual progress indicator.
|
||
|
||
**New data model:**
|
||
```prisma
|
||
model ApprovalChain {
|
||
id String @id @default(cuid())
|
||
name String
|
||
organizationId String
|
||
stageType String?
|
||
steps ApprovalStep[]
|
||
createdAt DateTime @default(now())
|
||
}
|
||
|
||
model ApprovalStep {
|
||
id String @id @default(cuid())
|
||
chainId String
|
||
stepOrder Int
|
||
approverRole Role?
|
||
approverUserId String?
|
||
isRequired Boolean @default(true)
|
||
autoAdvance Boolean @default(true)
|
||
approvalRecords ApprovalRecord[]
|
||
}
|
||
|
||
model ApprovalRecord {
|
||
id String @id @default(cuid())
|
||
deliverableStageId String
|
||
stepId String
|
||
decision ReviewDecision
|
||
note String?
|
||
decidedById String
|
||
decidedAt DateTime @default(now())
|
||
}
|
||
```
|
||
|
||
**Key files:**
|
||
- `src/app/(app)/settings/approvals/page.tsx`
|
||
- `src/components/approvals/chain-builder.tsx`
|
||
- `src/components/approvals/approval-progress.tsx`
|
||
- `src/lib/services/approval-service.ts`
|
||
|
||
---
|
||
|
||
#### D3 — Project Templates
|
||
|
||
**What:** Save a full project configuration (deliverables, stage settings, default assignments) as a reusable template. One-click project creation for repeat HP SKU types.
|
||
|
||
**New data model:**
|
||
```prisma
|
||
model ProjectTemplate {
|
||
id String @id @default(cuid())
|
||
name String
|
||
description String?
|
||
organizationId String
|
||
createdById String
|
||
isShared Boolean @default(true)
|
||
configuration Json
|
||
deliverables ProjectTemplateDeliverable[]
|
||
createdAt DateTime @default(now())
|
||
updatedAt DateTime @updatedAt
|
||
}
|
||
|
||
model ProjectTemplateDeliverable {
|
||
id String @id @default(cuid())
|
||
templateId String
|
||
name String
|
||
type String?
|
||
priority Priority @default(MEDIUM)
|
||
defaultAssignments Json?
|
||
sortOrder Int
|
||
}
|
||
```
|
||
|
||
**Key files:**
|
||
- `src/app/(app)/templates/page.tsx`
|
||
- `src/components/templates/template-card.tsx`
|
||
- `src/components/templates/template-builder.tsx`
|
||
- `src/lib/services/template-service.ts`
|
||
|
||
---
|
||
|
||
### E. Asset Intelligence
|
||
|
||
---
|
||
|
||
#### E1 — File Validation on Upload
|
||
|
||
**What:** Automatically validate uploaded files against spec requirements (resolution, color space, format, file size, aspect ratio). Reject non-conforming files with clear error messages. Override option for producers.
|
||
|
||
**New data model:**
|
||
```prisma
|
||
model AssetSpec {
|
||
id String @id @default(cuid())
|
||
organizationId String
|
||
stageType String
|
||
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
|
||
specId String
|
||
passed Boolean
|
||
results Json // [{ check, expected, actual, passed }]
|
||
overrideById String?
|
||
overrideReason String?
|
||
validatedAt DateTime @default(now())
|
||
}
|
||
```
|
||
|
||
**Key files:**
|
||
- `src/app/(app)/settings/asset-specs/page.tsx`
|
||
- `src/components/upload/file-validator.tsx`
|
||
- `src/lib/services/asset-validation-service.ts`
|
||
|
||
**New dependency:** `sharp` (already needed for A1 PNG compositing)
|
||
|
||
---
|
||
|
||
#### E2 — Thumbnail & Preview Generation
|
||
|
||
**What:** Auto-generate web-optimized thumbnails (200px), previews (1200px), and full copies from uploaded high-res assets. Background processing queue.
|
||
|
||
**Key files:**
|
||
- `src/lib/services/preview-service.ts`
|
||
- `src/lib/jobs/generate-previews.ts`
|
||
- `src/components/common/optimized-image.tsx`
|
||
|
||
---
|
||
|
||
#### E3 — AI Review Engine Integration Point
|
||
|
||
**What:** Webhook endpoint for an external AI Review Engine to post structured quality analysis results. AI-flagged regions rendered as dashed-border annotations in the viewer. Configuration per stage type.
|
||
|
||
**New data model:**
|
||
```prisma
|
||
model AIReviewResult {
|
||
id String @id @default(cuid())
|
||
revisionId String
|
||
overallScore Float
|
||
passed Boolean
|
||
checks Json
|
||
flaggedRegions Json
|
||
engineVersion String
|
||
processingTimeMs Int
|
||
createdAt DateTime @default(now())
|
||
}
|
||
```
|
||
|
||
**Key files:**
|
||
- `src/app/api/webhooks/ai-review/route.ts`
|
||
- `src/components/review/ai-review-overlay.tsx`
|
||
- `src/components/review/ai-review-summary.tsx`
|
||
- `src/lib/services/ai-review-service.ts`
|
||
|
||
---
|
||
|
||
### F. Quality of Life
|
||
|
||
---
|
||
|
||
#### F1 — Saved Filters & Custom Views
|
||
|
||
**What:** Save current filter/sort/column config as a named view. Personal and shared views. URL-encodable for link sharing.
|
||
|
||
**New data model:**
|
||
```prisma
|
||
model SavedView {
|
||
id String @id @default(cuid())
|
||
name String
|
||
userId String
|
||
organizationId String
|
||
projectId String?
|
||
viewType ViewType
|
||
configuration Json
|
||
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`
|
||
- `src/components/views/save-view-dialog.tsx`
|
||
- `src/lib/services/saved-view-service.ts`
|
||
|
||
---
|
||
|
||
#### F2 — Skill-Based Assignment UI
|
||
|
||
**What:** The Skill / UserSkill / StageSkillRequirement data models already exist. This adds the UI: skill tags on user profiles, skill requirements on stage templates, and best-fit artist suggestions in the assignment dialog (sorted by skill match + lowest current load).
|
||
|
||
**Key files:**
|
||
- `src/app/(app)/settings/skills/page.tsx`
|
||
- `src/components/assignments/skill-match-suggestions.tsx`
|
||
- `src/lib/services/skill-service.ts` — matching algorithm
|
||
|
||
---
|
||
|
||
#### F3 — Batch Upload with Auto-Matching
|
||
|
||
**What:** Drop multiple files onto a project; auto-match to deliverables by file naming convention (configurable regex). Preview table shows match confidence, manual override available.
|
||
|
||
**Key files:**
|
||
- `src/components/upload/batch-upload-zone.tsx`
|
||
- `src/components/upload/file-matcher.tsx`
|
||
- `src/lib/services/file-matching-service.ts`
|
||
|
||
---
|
||
|
||
#### F4 — Extended Command Palette Actions
|
||
|
||
**What:** Add quick-action commands to the existing Cmd+K palette: "approve and advance," "assign to me," "mark blocked," "start review session." Context-aware based on current page.
|
||
|
||
**Key files:**
|
||
- Update `src/components/layout/command-palette.tsx`
|
||
- `src/lib/commands/action-registry.ts`
|
||
|
||
---
|
||
|
||
### G. Docker Deployment
|
||
|
||
---
|
||
|
||
#### G1 — Docker Compose Stack
|
||
|
||
**What:** `docker-compose.yml` with three services — Next.js app, PostgreSQL + pgvector, Ollama with pre-configured models. One `docker compose up` starts everything.
|
||
|
||
Note: `Dockerfile` and `docker-compose.yml` already exist in the repo root — review and complete as needed.
|
||
|
||
**Services:**
|
||
|
||
| Service | Image | Purpose |
|
||
|---|---|---|
|
||
| `app` | Custom Dockerfile | Next.js production build |
|
||
| `db` | `pgvector/pgvector:pg17` | PostgreSQL with pgvector |
|
||
| `ollama` | `ollama/ollama:latest` | Local AI (nomic-embed-text + qwen3.5:9b) |
|
||
|
||
**Key files:**
|
||
- `Dockerfile` — multi-stage Next.js build (review existing)
|
||
- `docker-compose.yml` — full stack (review existing)
|
||
- `docker/ollama-entrypoint.sh` — model bootstrap script
|
||
- `docker/db-init.sql` — `CREATE EXTENSION IF NOT EXISTS vector;`
|
||
- `.env.example` — environment template
|
||
|
||
---
|
||
|
||
#### G2 — Health Checks & Startup Orchestration
|
||
|
||
**What:** `pg_isready` health check on `db`, Ollama API health check, `prisma migrate deploy` runs on app startup before `next start`. `depends_on: condition: service_healthy` ensures correct start order.
|
||
|
||
---
|
||
|
||
#### G3 — Dev Environment Override
|
||
|
||
**What:** `docker-compose.dev.yml` that mounts source code and runs `next dev` for hot reloading, while keeping database and Ollama in containers.
|
||
|
||
**Key files:**
|
||
- `docker-compose.dev.yml`
|
||
|
||
---
|
||
|
||
## Data Model Status
|
||
|
||
### Models Currently in Schema
|
||
|
||
| Model | Status |
|
||
|---|---|
|
||
| Organization, User, Account, Session | ✅ |
|
||
| PipelineStageTemplate, PipelineStageDependency | ✅ (legacy global, kept for backward compat) |
|
||
| PipelineTemplate, PipelineStageDefinition, PipelineStageDependencyV2 | ✅ (Phase 2 — org-scoped dynamic pipelines) |
|
||
| OrgRolePermission | ✅ (Phase 2 — RBAC) |
|
||
| Invitation | ✅ (Phase 2 — invite system) |
|
||
| CustomFieldDefinition | ✅ (Phase 2 — custom fields) |
|
||
| NotificationRule | ✅ (Phase 2 — notification rules) |
|
||
| Project, Deliverable, DeliverableStage | ✅ (with pgvector, customFields JSON, org denormalization) |
|
||
| StageAssignment, Revision, Comment | ✅ |
|
||
| Notification | ✅ |
|
||
| AutomationRule, AutomationExecution | ✅ |
|
||
| Skill, UserSkill, StageSkillRequirement | ✅ |
|
||
| SearchLog | ✅ |
|
||
| ChatMessage | ✅ |
|
||
|
||
### Models Needed (not yet in schema)
|
||
|
||
| Model | Feature |
|
||
|---|---|
|
||
| Annotation | A3 |
|
||
| FeedbackItem | A5 |
|
||
| ReviewSession, ReviewSessionItem | A6 |
|
||
| ApprovalChain, ApprovalStep, ApprovalRecord | D2 |
|
||
| ProjectTemplate, ProjectTemplateDeliverable | D3 |
|
||
| AssetSpec, AssetValidationResult | E1 |
|
||
| AIReviewResult | E3 |
|
||
| PortalLink | C3 |
|
||
| SLATarget | C4 |
|
||
| ActivityEntry | B2 |
|
||
| SavedView | F1 |
|
||
|
||
---
|
||
|
||
## Architecture Reference
|
||
|
||
```
|
||
src/
|
||
├── app/
|
||
│ ├── (auth)/login/ # SSO login
|
||
│ ├── (app)/ # Authenticated routes
|
||
│ │ ├── dashboard/
|
||
│ │ ├── projects/[projectId]/
|
||
│ │ │ ├── table/ board/ timeline/
|
||
│ │ │ └── deliverables/[deliverableId]/
|
||
│ │ ├── my-work/
|
||
│ │ ├── workload/ # ✅ Capacity grid + heatmap
|
||
│ │ ├── calendar/ # ✅ Calendar view
|
||
│ │ ├── reports/weekly/ # ✅ Weekly executive report
|
||
│ │ ├── reviews/ # A7 Review sessions
|
||
│ │ ├── templates/ # D3 Project templates
|
||
│ │ └── settings/
|
||
│ │ ├── permissions/ # ✅ Phase 2 RBAC matrix
|
||
│ │ ├── pipelines/ # ✅ Phase 2 Pipeline builder
|
||
│ │ ├── team/ # ✅ Phase 2 Team + invitations
|
||
│ │ ├── fields/ # ✅ Phase 2 Custom fields
|
||
│ │ ├── notifications/ # ✅ Phase 2 Notification rules
|
||
│ │ └── skills/ # ✅ Skills management
|
||
│ ├── (portal)/[token]/ # C3 Client portal (external)
|
||
│ ├── (external)/review/ # B3 External review links
|
||
│ └── api/
|
||
├── components/
|
||
│ ├── ui/ # shadcn/ui primitives
|
||
│ ├── layout/ # Sidebar, topbar, command palette
|
||
│ ├── views/ # Table, Board, Timeline, Dashboard
|
||
│ ├── workload/ # ✅ Capacity grid + heatmap components
|
||
│ ├── calendar/ # ✅ Calendar components
|
||
│ ├── reports/weekly/ # ✅ Weekly report components
|
||
│ ├── pipeline-builder/ # ✅ Phase 2 Pipeline graph + stage list
|
||
│ ├── revisions/ # A1 Image comparison (to build)
|
||
│ ├── review/ # A2-A7 Full review viewer (to build)
|
||
│ ├── automations/ # D1 Automation UI (to build)
|
||
│ └── search/ # ✅ Smart search panel
|
||
├── lib/
|
||
│ ├── pipeline/ # ✅ Dependency engine + stage machine + stage resolver
|
||
│ ├── rbac/ # ✅ Phase 2 permissions + org scope + requireAuth
|
||
│ ├── automation/ # ✅ Event bus + rule engine + executor
|
||
│ ├── services/ # Business logic per entity
|
||
│ └── validators/ # Zod schemas
|
||
├── hooks/ # TanStack Query hooks
|
||
└── stores/ # Zustand (UI state, filters)
|
||
```
|
||
|
||
### Key Patterns
|
||
- **Thin API routes** → delegate to `lib/services/` for all business logic
|
||
- **Service layer** → Prisma queries + business rules (testable, reusable)
|
||
- **URL-synced filters** via `nuqs` — views are shareable/bookmarkable
|
||
- **Server Components** for initial fetch, **TanStack Query** for mutations/cache
|
||
- **`npx prisma db push`** for schema changes (no migrations dir — use db push)
|
||
|
||
### Local Dev
|
||
```bash
|
||
# Start DB
|
||
brew services start postgresql@17
|
||
|
||
# Start app (must source nvm)
|
||
export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" && npm run dev
|
||
```
|
||
|
||
### Third-Party Libraries Needed for Remaining Work
|
||
|
||
| Library | Purpose | Feature |
|
||
|---|---|---|
|
||
| `@xyflow/react` | Pipeline dependency graph visualization | ✅ Phase 2 WP5 (installed) |
|
||
| `sharp` | PNG alpha compositing + image validation + thumbnail generation | A1, E1, E2 |
|
||
| `bcryptjs` | Password hashing for portal links | C3 |
|
||
| `@react-pdf/renderer` | PDF export for weekly report download button | C — weekly report enhancement |
|
||
|
||
---
|
||
|
||
*Document version: 1.1 — Updated 2026-03-14 (Phase 2: Dynamic Pipelines complete)*
|
||
*To be updated as features are built and priorities shift.*
|