Skip to content

ANALYTICS_GUIDE.md

Latest commit

 

History

History
411 lines (300 loc) · 10.2 KB

ANALYTICS_GUIDE.md

File metadata and controls

411 lines (300 loc) · 10.2 KB

📊 Analytics & Insights Guide

Feature: Comprehensive analytics dashboard for time tracking and productivity insights
Version: 1.0
Date: October 18, 2025

🎯 Overview

The Analytics page provides deep insights into your productivity patterns, focus time, and task completion metrics. Access it anytime via the chart icon (📊) in the top navbar.

🚀 Quick Access

From Main App

Click the 📊 Analytics icon in the top navigation bar

Or visit directly:

http://localhost:3000/analytics

The analytics page opens in a new tab, so you can reference your data while working on tasks!

📈 Dashboard Sections

1. Overview Stats (Top Cards)

Four key metrics at a glance:

Metric Description Icon
Total Focus Hours Cumulative time across all tasks 🕐
Pomodoros Completed Number of 25+ minute sessions ✅
Focus Sessions Total number of work sessions 📝
Avg Session Average session length (minutes) ⏱️

Use Case: Quick daily progress check

2. Time Spent by Task (Bar Chart)

What it shows:

  • Top 10 tasks by total time invested
  • Horizontal bar chart for easy comparison
  • Time displayed in hours

Insights:

  • Which tasks consume most of your time
  • Are you spending time on high-priority items?
  • Identify time sinks

Example:

Complete Project Report  ████████████ 12.5 hours
Code Review             ██████ 6.2 hours
Team Meeting            ████ 4.1 hours

3. Task Status (Pie Chart)

What it shows:

  • Split between Active and Completed tasks
  • Visual completion rate

Insights:

  • Overall task completion percentage
  • Workload balance
  • Completion momentum

Colors:

  • 🟡 Yellow = Active tasks
  • 🟢 Green = Completed tasks

4. Daily Focus Time (Line Chart)

What it shows:

  • Total focus time per day (last 30 days)
  • Trend line showing consistency
  • Date range on X-axis

Insights:

  • Daily productivity patterns
  • Consistency trends
  • Best/worst focus days
  • Identify streaks or gaps

Example Use: "I see I focus more on Tuesdays and Thursdays. Let me schedule deep work tasks on those days!"

5. Pomodoros Over Time (Line Chart)

What it shows:

  • Number of completed Pomodoros per day (last 30 days)
  • Only counts sessions ≥ 25 minutes
  • Daily totals

Insights:

  • Pomodoro completion consistency
  • Daily focus session count
  • Productivity momentum
  • Best days for deep work

Target: 4-6 Pomodoros per day = excellent productivity!

6. Session Length Distribution (Donut Chart)

What it shows:

  • Categorization of all focus sessions by duration:
    • < 5 min (Red) - Quick checks
    • 5-15 min (Yellow) - Short sessions
    • 15-25 min (Blue) - Near-pomodoros
    • 25+ min (Green) - Full pomodoros

Insights:

  • Focus Quality Score - More green = better focus
  • Are you getting interrupted frequently?
  • Session depth analysis

Ideal Distribution: Majority should be in "25+ min" category for deep work

7. Focus Time by Hour of Day (Bar Chart)

What it shows:

  • Total hours focused during each hour (0-23)
  • Aggregated across all days

Insights:

  • Peak productivity hours - When do you focus best?
  • Circadian rhythm patterns
  • Optimal meeting times (low-focus hours)
  • When to schedule deep work

Example Insights:

9 AM - 12 PM: Peak focus time
2 PM - 4 PM: Afternoon slump
7 PM - 9 PM: Evening productivity spike

Action: Schedule important tasks during your peak hours!

8. Detailed Task Statistics (Table)

Columns:

  • Task - Task name
  • Time Spent - Total time (hours + minutes)
  • Pomodoros - Count with 🍅 badge
  • Sessions - Number of work sessions
  • Importance - Star rating (1-5 stars)
  • Status - ✅ Complete or ⭕ Active

Features:

  • Sortable - Click column headers
  • Paginated - 10 tasks per page
  • Searchable - Filter tasks
  • Detailed - All metrics in one view

Use Cases:

  • Compare time investment vs. importance
  • Find neglected high-priority tasks
  • Audit time allocation
  • Export for reports

💡 Using Analytics to Improve Productivity

Daily Review (5 minutes)

  1. Check Total Focus Hours - Did I meet my goal?
  2. Review Pomodoros Completed - Hit 4-6?
  3. Look at Daily Focus Time - Any patterns?

Weekly Analysis (15 minutes)

  1. Top Tasks Review - Am I focusing on what matters?
  2. Session Length Distribution - Is my focus quality improving?
  3. Hourly Patterns - When am I most productive?
  4. Task Status - What's my completion rate?

Monthly Deep Dive (30 minutes)

  1. 30-day trends - Overall trajectory?
  2. Best/worst weeks - What caused variations?
  3. Time allocation - Does it align with goals?
  4. Adjust strategy - Based on data insights

🎯 Productivity Metrics Explained

Focus Hours (Total Time Spent)

  • What: Raw time tracked on tasks
  • Good: 4-8 hours per workday
  • Great: Consistent daily hours
  • Watch: Burnout if consistently > 10 hours

Pomodoro Count

  • What: Number of 25+ minute sessions
  • Good: 4-6 per day
  • Great: 8-10 per day
  • Watch: Quality > quantity

Focus Quality

  • Calculation: % of sessions ≥ 25 minutes
  • Poor: < 30% (too fragmented)
  • Good: 50-70%
  • Excellent: > 70% (deep focus)

Session Average

  • What: Mean session duration
  • Short: < 15 min (fragmented)
  • Ideal: 20-30 min (focused)
  • Long: > 45 min (possible fatigue)

📊 Interpreting Charts

Positive Patterns ✅

  • Upward trend in daily focus time
  • Consistent Pomodoro completions
  • Peak during your "good hours"
  • High % of 25+ min sessions
  • Balanced time on top priorities

Warning Signs ⚠️

  • Declining daily focus hours
  • Many interruptions (short sessions)
  • Mismatch between time & importance
  • Zero focus on some days
  • Late night work (poor sleep?)

Action Items 🎯

  • If fragmented: Block calendar for deep work
  • If inconsistent: Set daily Pomodoro goals
  • If misaligned: Reassess task priorities
  • If burnt out: Schedule breaks, delegate

🛠️ Technical Details

Data Sources

  • Tasks Table: total_time_spent, pomodoro_count, importance, done
  • Time Logs Table: start_time, end_time, duration, task_id

Time Calculations

// Total Focus Hours
totalHours = sum(tasks.total_time_spent) / 3600

// Pomodoros
pomodoros = count(sessions >= 1500 seconds)

// Average Session
avgSession = sum(timeLogs.duration) / count(timeLogs) / 60

Chart Library

  • Chart.js 4.4.0 - Modern, responsive charts
  • Date-fns - Date formatting
  • Vuetify 3 - UI framework

🎨 Theme Support

Analytics page supports dark mode:

  • Click 🌙 theme toggle in navbar
  • Syncs with main app theme preference
  • Saves to localStorage
  • Charts auto-update colors

📤 Future Features (Planned)

V2 Features

  • 📥 Export to CSV/PDF - Download reports
  • 📅 Custom date ranges - Week, month, year, custom
  • 🎯 Goal tracking - Set and monitor targets
  • 📈 Trend predictions - ML-based forecasts
  • 🔔 Insights notifications - "You're on track!"

V3 Features

  • 🏆 Achievements - Badges for milestones
  • 🔥 Streaks - Consecutive focus days
  • 👥 Team analytics - Collaborative metrics
  • 📊 Custom dashboards - Personalized views
  • 🔗 Integrations - Export to Notion, Todoist, etc.

🐛 Troubleshooting

No data showing

  • Check: Have you tracked any time yet?
  • Solution: Start some timers and let them run

Charts not loading

  • Check: Browser console for errors
  • Solution: Refresh page, clear cache
  • Required: Modern browser (Chrome, Firefox, Safari, Edge)

Incorrect data

  • Check: Time zone settings
  • Check: System clock accuracy
  • Solution: Re-sync by refreshing main app

Slow loading

  • Cause: Large dataset (many logs)
  • Solution: Database optimization (coming in V2)
  • Workaround: Archive old completed tasks

📚 Best Practices

For Accurate Analytics

  1. Start timers when you actually begin working
  2. Stop timers during breaks (don't leave running)
  3. Complete tasks to see completion metrics
  4. Regular reviews - Check analytics weekly
  5. Act on insights - Use data to improve

For Better Insights

  1. Set importance correctly on all tasks
  2. Use categories to group similar work
  3. Add due dates for deadline tracking
  4. Write notes to remember context
  5. Track consistently - Daily habit

🎓 Productivity Tips Based on Data

If You See...

Many short sessions (< 5 min):

  • 💡 Block calendar for deep work
  • 💡 Use "Do Not Disturb" mode
  • 💡 Batch small tasks together

No focus during mornings:

  • 💡 You might be a night owl
  • 💡 Schedule meetings in AM, deep work in PM
  • 💡 Or improve morning routine

High time on low-priority tasks:

  • 💡 Revisit priorities
  • 💡 Delegate or eliminate
  • 💡 Use Eisenhower Matrix

Declining weekly totals:

  • 💡 Check for burnout
  • 💡 Reassess workload
  • 💡 Schedule recovery time

Perfect Pomodoro completion:

  • 💡 You're doing great!
  • 💡 Maintain the momentum
  • 💡 Share your strategy

📖 Related Documentation

🎉 Summary

The Analytics dashboard transforms your raw time tracking data into actionable insights:

✅ Understand your productivity patterns
✅ Identify peak performance times
✅ Optimize task scheduling
✅ Track progress toward goals
✅ Improve focus quality
✅ Balance workload effectively

Remember: Data without action is just numbers. Use these insights to continuously improve your productivity system!

Questions or feedback? Open an issue or contribute to the project!

Made with ❤️ for productive developers