vfxreview/Shot task workflow.md

Shot / Task / Version & Approval Status Workflow

Core Entities & Status Fields

Entity	Status Field	Enum
Shot	status (derived)	ShotStatus
Shot	shotApprovalStatus	ShotApprovalStatus
Task	status	TaskStatus
Version	approvalStatus	ApprovalStatus
Version	reviewStatus	ReviewStatus (lightly used)

---

Data Model & Enums

Enum	States	Purpose
ShotStatus	WAITING, IN_PROGRESS, INTERNAL_REVIEW, READY_FOR_CLIENT, CLIENT_REVIEW, REVISIONS, COMPLETE	Derived shot state (read-only, calculated)
ShotApprovalStatus	PENDING, INTERNALLY_APPROVED, CLIENT_APPROVED	Shot-level approval stage (manually set)
TaskStatus	TODO, IN_PROGRESS, INTERNAL_REVIEW, CLIENT_REVIEW, CHANGES, DONE	Task execution state
ApprovalStatus	PENDING_REVIEW, APPROVED, REJECTED, NEEDS_CHANGES	Version review decision
ReviewStatus	PENDING, INTERNAL_APPROVED, CLIENT_APPROVED, NEEDS_CHANGES, FINAL_APPROVED	Version review progression (legacy/parallel)

Core Relationships

Project → Shot (1:N)
   ↓
Shot → Task (1:N)
   ↓
Task → Version (1:N)
   ↓
Version → Approval (1:N, one per reviewer)

---

Shot Status is Derived, Not Set Directly

ShotStatus is computed by deriveShotStatus() in lib/shot-status.ts from task states and approval fields. It is recalculated via recalcShotStatus() whenever a task, version, or approval changes.

Priority rules (highest wins):

REVISIONS         ← any task is CHANGES
COMPLETE          ← shotApprovalStatus === CLIENT_APPROVED
CLIENT_REVIEW     ← INTERNALLY_APPROVED + sharedWithClient = true
READY_FOR_CLIENT  ← INTERNALLY_APPROVED + sharedWithClient = false
IN_PROGRESS       ← any task is TODO or IN_PROGRESS
INTERNAL_REVIEW   ← tasks exist, none blocking (approval still PENDING)
WAITING           ← no tasks

recalcShotStatus() is automatically triggered on:

• Task creation (added to shot)
• Task status update
• Approval submission

---

Version → Approval → Task Pipeline

Artist uploads Version
    → all prior versions: isLatest = false
    → new Version: approvalStatus = PENDING_REVIEW, isLatest = true
    → Task auto-moves → INTERNAL_REVIEW
    → Shot recalculated → INTERNAL_REVIEW
    → Notifications sent to supervisors/producers
         ↓
Reviewer submits Approval (creates Approval record)
    → Version.approvalStatus updated
    → APPROVED             → Task → DONE
    → REJECTED             → Task → CHANGES
    → NEEDS_CHANGES        → Task → CHANGES
    → Shot recalculated
    → Notifications sent (artist, Slack webhook)

Approval Status Mapping

Version.approvalStatus	Task.status	Shot.status (if isolated)
PENDING_REVIEW	INTERNAL_REVIEW	INTERNAL_REVIEW
APPROVED	DONE	depends on other tasks
REJECTED	CHANGES	REVISIONS
NEEDS_CHANGES	CHANGES	REVISIONS

Role-Based Access for Approvals

• Only ADMIN, PRODUCER, SUPERVISOR, CLIENT can approve
• Client can only approve if shot is shared (sharedWithClient = true)
• Approval records are append-only — each review creates a new Approval row; the latest one wins

---

Task Status Transitions

TODO
  ↓ (artist starts work / uploads version)
IN_PROGRESS / INTERNAL_REVIEW
  ↓ (approval submitted)
  ├─→ DONE        (if APPROVED)
  └─→ CHANGES     (if REJECTED or NEEDS_CHANGES)
         ↓
CLIENT_REVIEW     (when shot is shared with client)

Action	Trigger	Effect
createTask()	Producer creates task	Creates in TODO; calls recalcShotStatus()
updateTaskStatus()	Manual status change	Updates task; triggers notifications + shot recalc
Task → INTERNAL_REVIEW	Version uploaded	Auto-triggered in actions/versions.ts
Task → CLIENT_REVIEW	Shot shared with client	Auto-triggered in actions/shots.ts
Task → DONE	Version approved	Auto-triggered in actions/approvals.ts
Task → CHANGES	Version rejected/needs changes	Auto-triggered in actions/approvals.ts

Permissions: ADMIN, PRODUCER, SUPERVISOR can create/update tasks.

---

Shot-Level Approval Lifecycle

PENDING (initial)
    ↓ internallyApproveShot()  [ADMIN / PRODUCER / SUPERVISOR]
INTERNALLY_APPROVED  →  Shot status: READY_FOR_CLIENT
    ↓ shareWithClient()
sharedWithClient = true  →  Shot status: CLIENT_REVIEW
    latest versions: isClientVisible = true, sharedAt = now
         ↓                               ↓
clientApproveShot()           clientRequestsChanges()
shotApprovalStatus =          shotApprovalStatus = PENDING
CLIENT_APPROVED               sharedWithClient = false
Shot status: COMPLETE         isClientVisible = false (all task versions)
                              Shot status: REVISIONS (if tasks have CHANGES)

State Details

State	shotApprovalStatus	sharedWithClient	Shot.status
Initial	PENDING	false	WAITING / IN_PROGRESS / INTERNAL_REVIEW
Internally approved	INTERNALLY_APPROVED	false	READY_FOR_CLIENT
Shared with client	INTERNALLY_APPROVED	true	CLIENT_REVIEW
Client approved	CLIENT_APPROVED	true	COMPLETE
Revisions requested	PENDING	false	REVISIONS

---

Key Implementation Files

Concern	File
Status derivation engine	lib/shot-status.ts
Shot actions (share/approve/revise)	actions/shots.ts
Approval creation + cascades	actions/approvals.ts
Version upload + task auto-transition	actions/versions.ts
Task creation / status updates	actions/tasks.ts
Shot status UI badges	components/shots/ShotCard.tsx
Task status UI badges	components/tasks/TaskCard.tsx

---

Notable Design Choices

• ShotStatus is never written directly — always a computed projection of task + approval state, preventing inconsistency.
• ReviewStatus on Version is largely redundant with approvalStatus; it appears to be a legacy/parallel field not driving much logic currently.
• Approval records are append-only — each review creates a new Approval row; the latest one wins for updating Version.approvalStatus.
• Client visibility is gated at two levels: Shot.sharedWithClient and Version.isClientVisible, both toggled atomically when sharing.
• shareWithClient() is atomic: all task versions are updated in a single transaction.

---

Unapprove / Undo Approval

Version-Level Unapprove (unapproveVersion)

Available to: ADMIN, PRODUCER, SUPERVISOR
Shown as: "Undo Approval" in the version dropdown (only visible when approvalStatus === APPROVED)
Location: VersionList.tsx → actions/approvals.ts

Version.approvalStatus === APPROVED
    ↓ unapproveVersion()
Version.approvalStatus → PENDING_REVIEW
Task.status (if DONE) → INTERNAL_REVIEW
Audit: new Approval record created with status = PENDING_REVIEW, notes = "Approval undone"
Shot recalculated

Shot-Level Unapprove (unapproveShot)

Available to: ADMIN, PRODUCER, SUPERVISOR
Shown as: "Undo Client Approval" button on the shot detail page (only when shotApprovalStatus === CLIENT_APPROVED)
Location: shots/[shotId]/page.tsx → actions/shots.ts

shotApprovalStatus === CLIENT_APPROVED  (Shot status: COMPLETE)
    ↓ unapproveShot()
shotApprovalStatus → INTERNALLY_APPROVED
Shot.status → CLIENT_REVIEW  (if still sharedWithClient)
           → READY_FOR_CLIENT (if sharedWithClient = false)

Neither unapprove action modifies the sharedWithClient flag or version visibility — only the approval state is rolled back.