wulf-pulse/tasks/tasks-prd-time-entries-analytics.md

Relevant Files

• migrations/006_add_time_entries_table.sql - Database migration for Time Entries table with proper indexing and foreign keys
• lib/types/database.ts - TypeScript interfaces for Time Entries entity
• lib/types/autotask.ts - TypeScript interfaces for Autotask Time Entries API response
• lib/services/autotask-client.ts - Extended Autotask client with Time Entries API methods
• lib/services/entity-sync.ts - Sync service integration for Time Entries
• lib/utils/entity-mapper.ts - Entity mapping functions for Time Entries
• app/api/data/time-entries/route.ts - API endpoint for fetching Time Entries data
• app/api/sync/entity/route.ts - Updated sync endpoint to include Time Entries
• lib/services/analytics-engine.ts - Core analytics engine for scoring and analysis
• lib/services/llm-analyzer.ts - LLM integration for work pattern analysis
• lib/utils/scoring-algorithms.ts - Scoring algorithms for Activity, Content, and Timeliness scores
• components/analytics/TimelineView.tsx - Main timeline component with collapsible sections
• components/analytics/ScoreCard.tsx - Component for displaying individual and aggregate scores
• components/analytics/AnalysisPanel.tsx - Component for AI insights and recommendations
• components/analytics/TimeEntriesDashboard.tsx - Main dashboard page component
• app/admin/analytics/time-entries/page.tsx - Time Entries analytics page
• lib/utils/time-helpers.ts - Utility functions for time-based calculations and formatting
• lib/utils/chart-helpers.ts - Utility functions for chart data preparation
• hooks/use-time-entries.ts - React hook for Time Entries data fetching and state management
• hooks/use-analytics.ts - React hook for analytics calculations and scoring

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.

Tasks

• 1.0 Database Schema and Data Synchronization Setup

  • 1.1 Create Time Entries database migration with all required fields (id, resource_id, ticket_id, task_id, project_id, entry_date, hours_worked, notes, created_date, updated_date, etc.)
  • 1.2 Add proper indexing for time-based queries and foreign key relationships to existing tables
  • 1.3 Define TypeScript interfaces for Time Entries in database and Autotask API types
  • 1.4 Create entity mapping functions to convert Autotask Time Entries data to PostgreSQL schema
  • 1.5 Add Time Entries to the sync service configuration and entity types

• 2.0 Time Entries API Integration and Sync Service

  • 2.1 Extend Autotask client to support Time Entries API endpoints (query, get by ID, pagination)
  • 2.2 Implement pagination handling for large historical Time Entries datasets
  • 2.3 Add error handling for API rate limits and data inconsistencies specific to Time Entries
  • 2.4 Create API endpoint for fetching Time Entries data with filtering and sorting capabilities
  • 2.5 Implement initial historical data import and ongoing real-time synchronization
  • 2.6 Add Time Entries sync to the existing sync service and entity sync methods

• 3.0 Analytics Engine and Scoring System Development

  • 3.1 Develop core analytics engine for processing Time Entries data and generating insights
  • 3.2 Implement Activity Score calculation based on entry quality, completeness, and work patterns
  • 3.3 Implement Content Score calculation based on time entry description quality and detail
  • 3.4 Implement Timeliness Score calculation based on entry timing relative to work performed
  • 3.5 Create LLM integration service for work pattern analysis and insight generation
  • 3.6 Implement caching for AI analysis results to improve performance and reduce API costs
  • 3.7 Add background processing for batch analysis of historical Time Entries data

• 3.0 Analytics Engine and Scoring System Development

• 4.0 Timeline View and User Interface Components

  • 4.1 Create collapsible timeline component with multiple time range options (Hour, Day, Week, Month)
  • 4.2 Implement visual distinction between human and system activities with color coding
  • 4.3 Add key moment highlighting for ticket creation, status changes, and resolution events
  • 4.4 Create expandable/collapsible time period sections with smooth animations
  • 4.5 Implement time worked indicators and duration displays for each entry
  • 4.6 Create Score Card components for displaying individual and aggregate scores
  • 4.7 Build Analysis Panel component for AI insights and recommendations
  • 4.8 Implement responsive design for desktop and tablet viewing

• 5.0 Analytics Dashboard and Integration

  • 5.1 Create main Time Entries analytics dashboard page accessible from admin menu
  • 5.2 Implement filtering capabilities by resource, project, ticket, task, and activity type
  • 5.3 Build both detailed single-ticket views and summary dashboard views
  • 5.4 Add export capabilities for analysis results and reports (CSV, Excel, PDF)
  • 5.5 Integrate Time Entries analytics with existing entities for enriched analysis
  • 5.6 Create React hooks for Time Entries data fetching and analytics state management
  • 5.7 Add Time Entries analytics to the admin navigation and data browser if applicable
  • 5.8 Implement performance optimizations for large datasets and caching strategies

• 5.0 Analytics Dashboard and Integration