seubert-claims/tasks/tasks-prd-ondeck-policy-renewal.md

# Tasks: OnDeck Policy Renewal Workflow Management System

> Generated from: `prd-ondeck-policy-renewal.md`

## Relevant Files

- `package.json` - Project dependencies and scripts
- `docker-compose.yml` - Docker configuration for app and PostgreSQL
- `Dockerfile` - Container build configuration
- `.env.example` - Environment variable template
- `prisma/schema.prisma` - Database schema definition
- `prisma/migrations/` - Database migration files
- `prisma/seed.ts` - Database seeding script
- `src/app/layout.tsx` - Root layout with providers
- `src/app/page.tsx` - Landing/redirect page
- `src/app/api/auth/[...nextauth]/route.ts` - NextAuth.js API route for Entra ID
- `src/app/api/auth/[...nextauth]/route.test.ts` - Tests for auth route
- `src/lib/auth.ts` - NextAuth configuration and helpers
- `src/lib/auth.test.ts` - Tests for auth helpers
- `src/middleware.ts` - Auth and RBAC middleware
- `src/middleware.test.ts` - Tests for middleware
- `src/app/api/sync/route.ts` - Manual sync trigger endpoint
- `src/app/api/sync/route.test.ts` - Tests for sync endpoint
- `src/lib/sync/sync-engine.ts` - AFW sync logic
- `src/lib/sync/sync-engine.test.ts` - Tests for sync engine
- `src/lib/sync/scheduler.ts` - Cron-based sync scheduler
- `src/lib/sync/afw-connection.ts` - SQL Server connection to AFW
- `src/lib/sync/afw-connection.test.ts` - Tests for AFW connection
- `src/lib/sync/mappers.ts` - AFW to local data mappers
- `src/lib/sync/mappers.test.ts` - Tests for data mappers
- `src/app/(dashboard)/layout.tsx` - Dashboard layout with sidebar
- `src/app/(dashboard)/dashboard/page.tsx` - Personal dashboard
- `src/app/(dashboard)/dashboard/page.test.tsx` - Tests for personal dashboard
- `src/app/(dashboard)/clients/page.tsx` - Client list page
- `src/app/(dashboard)/clients/page.test.tsx` - Tests for client list
- `src/app/(dashboard)/clients/[id]/page.tsx` - Client detail page
- `src/app/(dashboard)/clients/[id]/page.test.tsx` - Tests for client detail
- `src/app/(dashboard)/tasks/page.tsx` - Task list page
- `src/app/(dashboard)/tasks/page.test.tsx` - Tests for task list
- `src/app/(dashboard)/manager/page.tsx` - Manager dashboard
- `src/app/(dashboard)/manager/page.test.tsx` - Tests for manager dashboard
- `src/app/(dashboard)/admin/page.tsx` - Admin dashboard
- `src/app/(dashboard)/admin/shapes/page.tsx` - Shape management page
- `src/app/(dashboard)/admin/templates/page.tsx` - Task template management
- `src/app/(dashboard)/admin/sync/page.tsx` - Sync configuration page
- `src/app/(dashboard)/admin/users/page.tsx` - User/role management page
- `src/app/api/clients/route.ts` - Clients API endpoints
- `src/app/api/clients/route.test.ts` - Tests for clients API
- `src/app/api/clients/[id]/route.ts` - Single client API
- `src/app/api/tasks/route.ts` - Tasks API endpoints
- `src/app/api/tasks/route.test.ts` - Tests for tasks API
- `src/app/api/tasks/[id]/route.ts` - Single task API
- `src/app/api/shapes/route.ts` - Shapes API endpoints
- `src/app/api/shapes/route.test.ts` - Tests for shapes API
- `src/app/api/templates/route.ts` - Task templates API
- `src/app/api/templates/route.test.ts` - Tests for templates API
- `src/app/api/notifications/route.ts` - Notifications API
- `src/app/api/admin/sync-config/route.ts` - Sync configuration API
- `src/app/api/admin/roles/route.ts` - Role mapping API
- `src/components/ui/` - shadcn/ui components directory
- `src/components/layout/sidebar.tsx` - Navigation sidebar component
- `src/components/layout/header.tsx` - Header with user menu
- `src/components/clients/client-list.tsx` - Client list component
- `src/components/clients/client-detail.tsx` - Client detail component
- `src/components/clients/shape-selector.tsx` - Shape dropdown component
- `src/components/clients/personnel-picker.tsx` - Entra user picker
- `src/components/tasks/task-list.tsx` - Task list component
- `src/components/tasks/task-card.tsx` - Individual task card
- `src/components/tasks/task-form.tsx` - Task create/edit form
- `src/components/tasks/status-select.tsx` - Status dropdown with N/A notes
- `src/components/dashboard/kpi-card.tsx` - KPI display card
- `src/components/dashboard/task-summary.tsx` - Task summary widget
- `src/components/dashboard/workload-chart.tsx` - Workload distribution chart
- `src/components/notifications/notification-bell.tsx` - Notification icon/dropdown
- `src/components/admin/shape-form.tsx` - Shape create/edit form
- `src/components/admin/template-form.tsx` - Template create/edit form
- `src/components/admin/sync-status.tsx` - Sync health widget
- `src/lib/db.ts` - Prisma client singleton
- `src/lib/utils.ts` - Utility functions
- `src/types/index.ts` - TypeScript type definitions
- `src/types/enums.ts` - Enum definitions matching Prisma
- `tailwind.config.ts` - Tailwind CSS configuration
- `jest.config.js` - Jest test configuration
- `jest.setup.js` - Jest setup file

### Notes

- Unit tests should typically be placed alongside the code files they are testing (e.g., `MyComponent.tsx` and `MyComponent.test.tsx` in the same directory).
- Use `npx jest [optional/path/to/test/file]` to run tests. Running without a path executes all tests found by the Jest configuration.
- This project uses Next.js App Router with server components by default.
- shadcn/ui components are installed via `npx shadcn-ui@latest add [component-name]`.
- Environment variables should never be committed; use `.env.example` as a template.

## Tasks

- [x] 1.0 Project Setup & Infrastructure
  - [x] 1.1 Initialize Next.js project with TypeScript (`npx create-next-app@latest ondeck --typescript --tailwind --eslint --app --src-dir`)
  - [x] 1.2 Install and configure shadcn/ui (`npx shadcn-ui@latest init`)
  - [x] 1.3 Install core shadcn/ui components (button, card, input, select, table, dialog, dropdown-menu, tabs, badge, toast, avatar, skeleton)
  - [x] 1.4 Create `docker-compose.yml` with app service and PostgreSQL service (use ondeck database credentials)
  - [x] 1.5 Create `Dockerfile` for Next.js production build
  - [x] 1.6 Create `.env.example` with all required environment variables (DATABASE_URL, NEXTAUTH_*, AZURE_AD_*, AFW_*)
  - [x] 1.7 Configure Tailwind with custom theme colors for Shape designations
  - [x] 1.8 Set up Jest testing framework with React Testing Library
  - [x] 1.9 Create base project folder structure (`src/app`, `src/components`, `src/lib`, `src/types`)
  - [x] 1.10 Create `src/lib/utils.ts` with common utility functions (cn, formatDate, etc.)

- [x] 2.0 Authentication & Authorization (Entra ID)
  - [x] 2.1 Install NextAuth.js and Azure AD provider (`npm install next-auth @azure/msal-node`)
  - [x] 2.2 Create NextAuth configuration in `src/lib/auth.ts` with Azure AD provider
  - [x] 2.3 Configure Azure AD provider to request group claims in token
  - [x] 2.4 Create `src/app/api/auth/[...nextauth]/route.ts` API route
  - [x] 2.5 Create auth session provider wrapper component
  - [x] 2.6 Implement user upsert on first login (create user record from Entra token)
  - [x] 2.7 Create role resolution logic (map Entra groups to app roles from entra_group_role_mappings table)
  - [x] 2.8 Create `src/middleware.ts` for route protection and RBAC enforcement
  - [x] 2.9 Define permission sets per role (Admin, Manager, Account Executive, Claims) in constants
  - [x] 2.10 Create `useSession` and `usePermissions` custom hooks for client components
  - [x] 2.11 Create higher-order component or wrapper for role-based UI rendering
  - [x] 2.12 Write unit tests for auth helpers and role resolution logic

- [x] 3.0 Database Schema & ORM Setup
  - [x] 3.1 Install Prisma (`npm install prisma @prisma/client`)
  - [x] 3.2 Initialize Prisma with PostgreSQL (`npx prisma init --datasource-provider postgresql`)
  - [x] 3.3 Define User model with Entra fields (entra_oid, email, display_name, department, is_active, last_login_at)
  - [x] 3.4 Define Role model with permissions JSONB field
  - [x] 3.5 Define EntraGroupRoleMapping model for group-to-role configuration
  - [x] 3.6 Define UserRole junction table for direct role assignments
  - [x] 3.7 Define Shape model with name, description, color, rules, display_order, is_active
  - [x] 3.8 Define Client model with AMS sync fields and custom fields (shape_id, shape2_id, primary_personnel_id, notes, custom_fields JSONB)
  - [x] 3.9 Define ClientPersonnel junction table for additional personnel assignments
  - [x] 3.10 Define Policy model with AMS sync fields and expiration_date index
  - [x] 3.11 Define TaskStatus and TaskPriority enums (include NA status)
  - [x] 3.12 Define TaskTemplate model with department, timing, days_offset, default_priority
  - [x] 3.13 Define Task model with all fields including na_reason, cancelled_reason
  - [x] 3.14 Define TaskAssignment junction table for multi-user assignment
  - [x] 3.15 Define SyncLog model for sync run tracking
  - [x] 3.16 Define SyncConfig model for admin-configurable sync settings
  - [x] 3.17 Define AuditLog model for change tracking
  - [x] 3.18 Define Notification model for in-app notifications
  - [x] 3.19 Define NotificationPreference model for user notification settings
  - [x] 3.20 Create initial migration (`npx prisma migrate dev --name init`)
  - [x] 3.21 Create `src/lib/db.ts` Prisma client singleton
  - [x] 3.22 Create `prisma/seed.ts` with default roles, initial shapes, and sample task templates
  - [x] 3.23 Run seed script (`npx prisma db seed`)

- [x] 4.0 AFW Data Sync Engine
  - [x] 4.1 Install SQL Server driver (`npm install mssql`)
  - [x] 4.2 Create `src/lib/sync/afw-connection.ts` with connection pool management
  - [x] 4.3 Create AFW query functions for: AFW_Customer, AFW_BasicPolInfo, AFW_Employee, AFW_GeneralLedgerDepartment, AFW_Company, AFW_PRCode
  - [x] 4.4 Implement date filter for policies (current year + 24 months expiration)
  - [x] 4.5 Create `src/lib/sync/mappers.ts` with AFW-to-local data transformation functions
  - [x] 4.6 Create `src/lib/sync/sync-engine.ts` with main sync orchestration logic
  - [x] 4.7 Implement incremental sync based on ChangedDate/ModifiedDate fields
  - [x] 4.8 Implement upsert logic (insert new, update existing based on ams_*_id)
  - [x] 4.9 Implement soft-delete handling (mark inactive if removed from AFW, never hard delete)
  - [x] 4.10 Create SyncLog entries for each sync run (start, end, counts, errors)
  - [x] 4.11 Implement retry logic with exponential backoff (3 attempts)
  - [x] 4.12 Create `src/lib/sync/scheduler.ts` using node-cron for scheduled sync
  - [x] 4.13 Read sync schedule from SyncConfig table (default 2 AM)
  - [x] 4.14 Create `src/app/api/sync/route.ts` POST endpoint for manual sync trigger (Admin only)
  - [x] 4.15 Create `src/app/api/sync/status/route.ts` GET endpoint for sync status
  - [x] 4.16 Write unit tests for mappers and sync logic (mock AFW connection)

- [x] 5.0 Client Management Module
  - [x] 5.1 Create `src/app/api/clients/route.ts` with GET (list with pagination, filtering) and search
  - [x] 5.2 Implement client list filters: department, shape, personnel, search term
  - [x] 5.3 Create `src/app/api/clients/[id]/route.ts` with GET (detail), PATCH (update custom fields)
  - [x] 5.4 Create `src/app/api/clients/[id]/personnel/route.ts` for managing additional personnel
  - [x] 5.5 Implement RBAC filtering (users see only assigned clients unless Manager/Admin)
  - [x] 5.6 Create `src/components/clients/client-list.tsx` with data table, sorting, filtering
  - [x] 5.7 Create `src/components/clients/client-card.tsx` for list item display with Shape color badge
  - [x] 5.8 Create `src/app/(dashboard)/clients/page.tsx` client list page
  - [x] 5.9 Create `src/app/(dashboard)/clients/[id]/page.tsx` client detail page
  - [x] 5.10 Create `src/components/clients/client-detail.tsx` with tabs for policies, tasks, personnel
  - [x] 5.11 Create `src/components/clients/shape-selector.tsx` dropdown with color swatches
  - [x] 5.12 Create `src/components/clients/personnel-picker.tsx` searchable Entra user selector
  - [x] 5.13 Implement audit logging for client modifications
  - [x] 5.14 Create policies sub-section showing all client policies with days-until-renewal
  - [x] 5.15 Write unit tests for client components and API routes

- [x] 6.0 Shape/Designation Management
  - [x] 6.1 Create `src/app/api/shapes/route.ts` with GET (list) and POST (create) - Admin only
  - [x] 6.2 Create `src/app/api/shapes/[id]/route.ts` with GET, PATCH (update), DELETE (soft delete/deactivate)
  - [x] 6.3 Create `src/components/admin/shape-form.tsx` with fields: name, description, color picker, rules, display_order, is_active
  - [x] 6.4 Create `src/components/admin/shape-list.tsx` with drag-and-drop reordering
  - [x] 6.5 Create `src/app/(dashboard)/admin/shapes/page.tsx` Shape management page
  - [x] 6.6 Implement color picker component for Shape color selection
  - [x] 6.7 Add validation to prevent deleting Shapes that are in use (only deactivate)
  - [x] 6.8 Design UI to be extensible for future designation types (abstract designation pattern)
  - [x] 6.9 Write unit tests for Shape API and components

- [x] 7.0 Task Management & Templates
  - [x] 7.1 Create `src/app/api/templates/route.ts` with GET (list by department) and POST (create) - Admin/Manager
  - [x] 7.2 Create `src/app/api/templates/[id]/route.ts` with GET, PATCH, DELETE
  - [x] 7.3 Create `src/components/admin/template-form.tsx` with fields: name, description, department, timing, days_offset, default_priority
  - [x] 7.4 Create `src/app/(dashboard)/admin/templates/page.tsx` template management page grouped by department
  - [x] 7.5 Create `src/app/api/tasks/route.ts` with GET (list with filters) and POST (create)
  - [x] 7.6 Create `src/app/api/tasks/[id]/route.ts` with GET, PATCH (update status, reassign), DELETE
  - [x] 7.7 Create `src/app/api/tasks/bulk/route.ts` for bulk status update and reassignment
  - [x] 7.8 Implement task due_date calculation: policy.expiration_date + days_offset
  - [x] 7.9 Create `src/components/tasks/status-select.tsx` with N/A option that shows notes modal
  - [x] 7.10 Implement N/A status validation (require na_reason when status = NA)
  - [x] 7.11 Implement CANCELLED status validation (require cancelled_reason)
  - [x] 7.12 Create `src/components/tasks/task-list.tsx` with filtering, sorting, status badges
  - [x] 7.13 Create `src/components/tasks/task-card.tsx` with priority indicator, due date, assignees
  - [x] 7.14 Create `src/components/tasks/task-form.tsx` for create/edit with client/policy selection
  - [x] 7.15 Create `src/app/(dashboard)/tasks/page.tsx` task list page
  - [x] 7.16 Create `src/lib/tasks/auto-generate.ts` task auto-generation logic from templates
  - [x] 7.17 Implement renewal window detection (configurable days before expiration, default 90)
  - [x] 7.18 Implement duplicate prevention (check existing tasks for same policy/template)
  - [x] 7.19 Auto-assign generated tasks to client's primary_personnel_id
  - [x] 7.20 Create cron job or trigger for daily task auto-generation check
  - [x] 7.21 Implement audit logging for task changes
  - [x] 7.22 Write unit tests for task API, auto-generation, and components

- [x] 8.0 Dashboards & Reporting
  - [x] 8.1 Create `src/components/dashboard/kpi-card.tsx` reusable KPI display component
  - [x] 8.2 Create `src/components/dashboard/task-summary.tsx` showing overdue, due today, due this week, upcoming
  - [x] 8.3 Create `src/components/dashboard/renewal-calendar.tsx` mini calendar showing upcoming renewals
  - [x] 8.4 Create `src/app/api/dashboard/personal/route.ts` aggregating personal KPIs
  - [x] 8.5 Create `src/app/(dashboard)/dashboard/page.tsx` personal dashboard with My Tasks, My Clients, Quick Stats
  - [x] 8.6 Create `src/components/dashboard/workload-chart.tsx` bar chart for tasks per team member
  - [x] 8.7 Create `src/components/dashboard/completion-chart.tsx` line chart for completion trends
  - [x] 8.8 Create `src/components/dashboard/status-pie-chart.tsx` pie chart for task status distribution
  - [x] 8.9 Create `src/app/api/dashboard/manager/route.ts` aggregating team KPIs
  - [x] 8.10 Create `src/app/(dashboard)/manager/page.tsx` manager dashboard with team overview, department metrics
  - [x] 8.11 Implement drill-down from aggregate metrics to individual user/task lists
  - [x] 8.12 Create `src/components/admin/sync-status.tsx` widget showing last sync, status, row counts
  - [x] 8.13 Create `src/app/api/dashboard/admin/route.ts` aggregating system health and cross-department metrics
  - [x] 8.14 Create `src/app/(dashboard)/admin/page.tsx` admin dashboard with system health, sync status, user activity
  - [x] 8.15 Implement dashboard data caching for <2 second load times
  - [x] 8.16 Install charting library (recharts or chart.js) for visualizations
  - [x] 8.17 Write unit tests for dashboard components and API routes

- [x] 9.0 Notifications System
  - [x] 9.1 Create `src/app/api/notifications/route.ts` with GET (list user notifications) and PATCH (mark read)
  - [x] 9.2 Create `src/app/api/notifications/[id]/route.ts` for individual notification actions
  - [x] 9.3 Create Notification model entries for: task_assigned, task_overdue, task_completed, sync_failed
  - [x] 9.4 Create `src/components/notifications/notification-bell.tsx` with unread count badge
  - [x] 9.5 Create `src/components/notifications/notification-dropdown.tsx` showing recent notifications
  - [x] 9.6 Create `src/components/notifications/notification-item.tsx` individual notification display
  - [x] 9.7 Implement notification creation triggers (on task assignment, status change, overdue detection)
  - [x] 9.8 Create daily job to generate overdue task notifications
  - [x] 9.9 Create `src/app/api/notifications/preferences/route.ts` for user notification settings
  - [x] 9.10 Create notification preferences UI in user settings
  - [x] 9.11 Design notification system to support future Teams/Email channels (abstract notification sender)
  - [x] 9.12 Write unit tests for notification components and API

- [x] 10.0 Admin Configuration & System Health
  - [x] 10.1 Create `src/app/api/admin/sync-config/route.ts` GET and PATCH for sync settings
  - [x] 10.2 Create `src/app/(dashboard)/admin/sync/page.tsx` with sync time picker, enable/disable toggle, manual trigger button
  - [x] 10.3 Create `src/app/api/admin/sync-logs/route.ts` GET for sync history with pagination
  - [x] 10.4 Display sync log history with status, duration, row counts, errors
  - [x] 10.5 Create `src/app/api/admin/roles/route.ts` for Entra group-to-role mapping CRUD
  - [x] 10.6 Create `src/app/(dashboard)/admin/users/page.tsx` showing users, their roles, last login
  - [x] 10.7 Create UI for managing Entra Group → Role mappings
  - [x] 10.8 Create `src/app/api/admin/audit-logs/route.ts` GET for audit log viewing
  - [x] 10.9 Create audit log viewer with filtering by user, entity type, date range
  - [x] 10.10 Implement audit log creation middleware/helper for sensitive operations
  - [x] 10.11 Implement system health checks (DB connection, AFW connection, last sync status)
  - [x] 10.12 Write unit tests for admin API routes and components