hp-prod-tracker/IMPLEMENTATION_PLAN.md

HP CG Production Tracker — Implementation Plan

Context

The CG department creates product renders for HP. Producers currently manage projects across fragmented tools (Workfront, Excel, OMG platform) with no unified view of pipeline status, artist workload, or delivery timelines. This app replaces that fragmentation with a single purpose-built tracker — similar to Monday.com but tailored to the department's specific CG pipeline stages and dependency rules.

---

Confirmed Requirements

Aspect	Decision
Platform	Web app (browser)
Framework	Next.js 15 (App Router, full-stack)
Database	PostgreSQL + Prisma ORM
Auth	SSO (Google / Microsoft Entra ID) via Auth.js v5
Team size	10-30 concurrent users
Roles	Producer (manage everything) + Artist (view assignments, update status)
Real-time	Not needed V1 (manual refresh)
Notifications	In-app only (bell icon)
Integrations V1	Excel import/export
Revisions	Track rounds with feedback notes, version history, round count
Theme	Light + Dark mode with system preference detection
Design style	Oliver Agency / Brandtech Group — corporate-minimalist, Montserrat + Inter

---

Pipeline Stages & Dependencies

Brief Intake → File Delivery → Model Prep ──→ Early Images (optional)
                                    │ GATE
                                    ▼
                              Catalog Images
                                    │ GATE
                    ┌───────┬───────┼───────┬──────────┐
                    ▼       ▼       ▼       ▼          ▼
                  Hero   Packaging  Photo   360 Spin  Dynamic
                 Images   Images   comps   Animations  Spin

• Nothing starts without Brief + Model Prep complete
• Catalog Images must be approved before Hero, Packaging, Photocomps, or Animations can begin
• Early Images is optional (can be skipped)
• Stages 6-10 run in parallel once Catalog is approved

---

Tech Stack

Core

• Next.js 15 — App Router, React Server Components, Turbopack
• TypeScript 5.x — Full type safety
• PostgreSQL 16 + Prisma 6.x — Relational data model with type-safe queries
• Auth.js v5 + @auth/prisma-adapter — SSO (Google + Microsoft Entra ID)

UI

• shadcn/ui — Component library (Radix + Tailwind)
• Tailwind CSS 4.x — Styling
• @tanstack/react-table v8 — Table/spreadsheet view
• @hello-pangea/dnd — Kanban drag-and-drop
• recharts — Dashboard charts
• @svar/react-gantt — Timeline/Gantt view

State & Data

• @tanstack/react-query v5 — Server state (fetching, caching, mutations)
• zustand — Client UI state (sidebar, view mode, filters)
• nuqs — URL-synced filter/sort state

Excel

• exceljs — Server-side Excel generation (export)
• xlsx (SheetJS) — Client-side Excel parsing (import)

Forms & Validation

• zod — Schema validation (API + forms + Excel rows)
• react-hook-form + @hookform/resolvers — Form management

Utilities

• date-fns — Date formatting
• sonner — Toast notifications
• cmdk — Command palette (Cmd+K)
• lucide-react — Icons
• next-themes — Light/dark mode toggle with system preference detection

---

Design System

Inspired by the Oliver Agency / Brandtech Group visual identity: corporate-minimalist, clean geometry, strong typographic hierarchy, generous whitespace. Adapted for a production-tracking tool with data-dense views.

Typography

Role	Font	Weight	Notes
Headings	Montserrat	600, 700	Oliver's primary brand font (Google Fonts)
Body / UI	Inter	400, 500, 600	Highly legible at small sizes for tables and data
Monospace	JetBrains Mono	400	Project codes, timestamps, technical data

Color Palette

Light Mode

Token	Hex	Usage
--background	#FFFFFF	Page background
--foreground	#0A0A0A	Primary text
--muted	#F5F5F5	Secondary backgrounds (sidebar, cards)
--muted-foreground	#6B7280	Secondary text, placeholders
--border	#E5E7EB	Dividers, card borders
--primary	#08402C	Primary actions (Oliver teal-green)
--primary-foreground	#FFFFFF	Text on primary
--accent	#EE5540	Alerts, urgent items, notifications (Oliver flamingo)
--accent-foreground	#FFFFFF	Text on accent
--ring	#08402C	Focus rings

Dark Mode

Token	Hex	Usage
--background	#0A0A0A	Page background
--foreground	#F5F5F5	Primary text
--muted	#171717	Secondary backgrounds (sidebar, cards)
--muted-foreground	#9CA3AF	Secondary text
--border	#262626	Dividers, card borders
--primary	#0FA968	Primary actions (teal-green, brightened for dark bg)
--primary-foreground	#FFFFFF	Text on primary
--accent	#F2725E	Alerts, urgent items (flamingo, softened for dark bg)
--accent-foreground	#FFFFFF	Text on accent
--ring	#0FA968	Focus rings

Semantic Status Colors (both modes)

Status	Light	Dark	Usage
Blocked	#DC2626	#EF4444	Blocked stages
Not Started	#6B7280	#9CA3AF	Pending work
In Progress	#2563EB	#60A5FA	Active work
In Review	#D97706	#FBBF24	Awaiting approval
Approved	#16A34A	#4ADE80	Completed/approved
Skipped	#9CA3AF	#6B7280	Optional stages skipped

Design Principles

1. Corporate-minimalist — Clean lines, no decorative elements, content-first
2. Dense but breathable — Tables and boards show lots of data with consistent spacing (8px grid)
3. Strong hierarchy — Montserrat bold headings, clear size steps (14/16/20/24/32px)
4. Restrained color — Mostly neutral with teal-green for primary actions, flamingo reserved for urgency/alerts
5. Photography-free — Icons and data visualization only, no stock imagery

Component Styling

• Cards — border color border, subtle shadow in light mode (shadow-sm), no shadow in dark mode
• Buttons — Primary: teal-green bg, white text, no border-radius excess (rounded-md). Secondary: ghost/outline style
• Tables — Alternating row shading using muted, sticky headers, compact row height (40px)
• Sidebar — muted background, 256px width, collapsible to 64px icon-only
• Navigation — Horizontal topbar with breadcrumbs, sticky at top
• Status badges — Pill-shaped, semantic color bg with matching text, uppercase small font
• Kanban cards — White/dark card on muted board bg, left border accent by status color

Theme Toggle

• next-themes with attribute="class" strategy for Tailwind dark mode
• Three options: Light / Dark / System
• Toggle in topbar settings area
• Persisted in localStorage, respects prefers-color-scheme on first visit

---

Data Model (Prisma)

Key Entities

Organization → has many Users, Projects User → role (ADMIN/PRODUCER/ARTIST), SSO accounts, assignments, notifications Project → projectCode, status, priority, dates → has many Deliverables Deliverable → name, status, priority, dueDate → has many DeliverableStages (auto-created: all 10) PipelineStageTemplate → seed data for 10 stages + dependency rules (isCriticalGate, isOptional) PipelineStageDependency → which stages depend on which (seed data) DeliverableStage → instance per deliverable, tracks status/dates/revisionRound → has Assignments, Revisions, Comments StageAssignment → links User to DeliverableStage with optional role ("Lead"/"Support") Revision → round number, status, feedback notes, internal notes, attachments (JSON) Comment → threaded (parentId), per stage Notification → type, title, message, link, isRead

Dependency Enforcement Logic

1. When a deliverable is created → auto-create 10 DeliverableStage records. Stages with unmet prerequisites start as BLOCKED
2. Before a stage moves to IN_PROGRESS → check all prerequisite stages are APPROVED (or SKIPPED if optional)
3. When a critical gate is APPROVED → automatically unblock downstream stages (BLOCKED → NOT_STARTED)

---

Application Architecture

Folder Structure (abbreviated)

src/
├── app/
│   ├── (auth)/login/          # SSO login page
│   ├── (app)/                 # Authenticated routes
│   │   ├── dashboard/         # KPI dashboard
│   │   ├── projects/          # Project list + CRUD
│   │   │   └── [projectId]/   # Project detail + views
│   │   │       ├── table/     # Spreadsheet view
│   │   │       ├── board/     # Kanban view
│   │   │       ├── timeline/  # Gantt view
│   │   │       └── deliverables/[deliverableId]/  # Pipeline stages
│   │   ├── my-work/           # Artist's assignments
│   │   ├── notifications/     # Notification history
│   │   └── settings/          # User + org settings
│   └── api/                   # REST API routes
│       ├── auth/[...nextauth]/
│       ├── projects/          # CRUD + nested deliverables/stages
│       ├── users/             # List org users
│       ├── notifications/     # List + mark read
│       ├── import/excel/      # Upload + parse
│       ├── export/excel/      # Generate + download
│       └── dashboard/stats/   # KPI aggregations
├── components/
│   ├── ui/                    # shadcn/ui primitives
│   ├── layout/                # Sidebar, topbar, breadcrumbs, notification bell
│   ├── views/                 # Table, Board, Timeline, Dashboard view components
│   ├── deliverables/          # Pipeline progress visualizer
│   ├── stages/                # Stage cards, status badges, dependency graph
│   ├── revisions/             # Revision timeline, forms
│   └── excel/                 # Import dialog, export button, column mapper
├── lib/
│   ├── auth.ts                # Auth.js config
│   ├── prisma.ts              # Singleton client
│   ├── pipeline/
│   │   ├── dependency-engine.ts  # Pure dependency validation functions
│   │   └── stage-machine.ts     # State transitions
│   ├── services/              # Business logic (project, deliverable, stage, revision, notification, excel, dashboard)
│   └── validators/            # Zod schemas
├── hooks/                     # TanStack Query hooks per entity
├── stores/                    # Zustand (UI state, filter state)
└── types/                     # Shared TypeScript types

Key Patterns

• Thin API routes → delegate to service layer for all business logic
• Service layer → encapsulates Prisma queries + business rules (testable, reusable)
• Dependency engine as pure functions → canStageStart() returns { allowed, reason }, used both server-side and potentially client-side
• URL-synced filters via nuqs → views are shareable/bookmarkable
• Server Components for initial data fetch, TanStack Query for client-side mutations/cache

---

Four Main Views

1. Table View — TanStack Table + shadcn/ui. Server-side pagination. Multi-column sort, faceted filters (status, stage, artist, priority, date). Column visibility toggle. URL-persisted state.

2. Board View — Kanban with drag-and-drop. Group by Status or by Stage. Drag triggers PATCH with dependency validation; blocked moves snap back with toast error.

3. Timeline View — Gantt chart (SVAR). Deliverables as rows, stages as task bars. Dependency arrows. Color-coded by status. Day/week/month zoom. Read-only V1.

4. Dashboard View — KPI cards (active projects, in-progress, overdue, avg revisions). Charts: deliverables by stage, delivery trend, on-time rate, artist workload. Overdue alerts list.

---

Phased Build Plan

Phase 1: Foundation

• Project scaffolding (Next.js, TS, Tailwind, ESLint, Prettier)
• Design system setup (Tailwind theme tokens, Montserrat + Inter fonts, light/dark CSS variables)
• next-themes integration with light/dark/system toggle
• Prisma schema + migrations + seed (pipeline templates + dependencies)
• Auth.js SSO (Google + Microsoft) with domain validation
• shadcn/ui component installation + theme customization to match design system
• App shell layout (sidebar, topbar, breadcrumbs, theme toggle)
• Project CRUD (API + pages + forms)
• Deliverable CRUD (API + pages, auto-create 10 stages)
• User management (list, role assignment)

Phase 2: Core Pipeline & Views

• Dependency engine + stage state machine
• Stage status management with dependency enforcement
• Artist assignment system + "My Work" page
• Table View (full TanStack Table implementation)
• Board View (Kanban with drag-and-drop)
• Timeline View (Gantt chart)
• Pipeline progress visualizer component
• TanStack Query hooks + optimistic updates

Phase 3: Advanced Features

• Revision tracking (rounds, feedback, history timeline)
• Threaded comment system on stages
• Notification system (in-app bell + full page, auto-generated on key events)
• Dashboard view (KPIs, charts, overdue alerts)
• Excel import (upload, preview, column mapping, validation, transactional commit)
• Excel export (multi-sheet styled workbook)
• Deadline tracking (approaching/overdue detection + notifications)

Phase 4: Polish

• Command palette (Cmd+K search)
• Bulk operations (multi-select in table → bulk status/assignment/priority)
• Loading skeletons, error boundaries, empty states
• Responsive design (mobile sidebar, stacked Kanban)
• Performance (query optimization, virtual scrolling, dynamic imports)
• Accessibility audit
• Edge cases (concurrent edits, rate limiting, session expiry)
• Documentation + deployment config

---

Verification Plan

1. Auth flow: Log in via Google/Microsoft SSO → verify session contains role + org → verify unauthorized domains are rejected
2. Pipeline dependencies: Create a deliverable → verify stages 6-10 are BLOCKED → approve Model Prep → verify still blocked → approve Catalog → verify stages 6-10 become NOT_STARTED
3. CRUD: Create project → add deliverables → assign artists → update statuses → delete → verify cascade
4. Views: Switch between Table/Board/Timeline/Dashboard → verify data consistency → test filters/sorts persist in URL
5. Revisions: Submit revision on a stage → request changes → submit round 2 → approve → verify round count
6. Excel: Import a sample spreadsheet → map columns → preview → commit → verify data created. Export → verify multi-sheet workbook with correct data
7. Notifications: Assign an artist → verify notification appears → mark read → verify count decreases