life-docs/features/analytics.md

Feature — Analytics & Suggestion Engine

Cross-domain analytics dashboard with charts and a "what should I do next?" suggestion engine.

---

API

Analytics Endpoints

Method	Endpoint	Description
GET	/api/analytics/overview	Cross-domain summary (tasks, habits, goals, income)
GET	/api/analytics/domain/:id	Domain-specific analytics
GET	/api/analytics/trends	Time-series data — ?metric=income|tasks_completed|habit_adherence|time_tracked, ?period=day|week|month, ?domainId=, ?startDate=&endDate=
GET	/api/analytics/habits/adherence	Habit adherence rates — ?period=month

Suggestion Engine

Method	Endpoint	Description
GET	/api/today/next-action	Suggested next task based on scoring algorithm

Overview Response

{
  "period": "month",
  "tasks": { "completed": 45, "created": 52, "overdue": 3, "byDomain": [...] },
  "habits": { "adherenceRate": 0.82, "activeStreaks": 5, "longestStreak": 30 },
  "goals": { "active": 12, "completed": 3, "averageProgress": 45 },
  "income": { "total": "3420.00", "currency": "GBP", "byDomain": [...] }
}

Trends Response

{
  "metric": "income",
  "period": "week",
  "dataPoints": [
    { "date": "2026-02-03", "value": 820 },
    { "date": "2026-02-10", "value": 1050 }
  ]
}

Next Action Response

{
  "task": {
    "id": "uuid",
    "title": "Design review for Christine",
    "domain": { "name": "Christine's Startup", "color": "#4A90D9" },
    "priority": "high",
    "energyLevel": "high",
    "estimatedMinutes": 60
  },
  "score": 65,
  "reason": "This is overdue and matches your current energy level"
}

---

Backend Module

AnalyticsModule — read-only, imports all feature modules.

• Aggregation queries across Tasks, Habits, Goals, Income
• No entities of its own
• Listens to events: TaskCompletedEvent, HabitCheckedInEvent, IncomeCreatedEvent

Suggestion algorithm (scoring):

• Overdue bonus: +20 points
• Priority: critical +15, high +10, medium +5, low +0
• Energy match: task energy = current energy → +10 points
• Time of day: morning tasks scored higher in AM, evening in PM
• Domain balance: bonus for neglected domains
• Quick win bonus: +5 when energy is low
• Simple weighted scoring — no ML

---

Frontend

Route

• /analytics — Cross-domain analytics dashboard

Components

• PeriodSelector — this month / last month / quarter / year
• OverviewCards — 4 StatCards (tasks completed, habit adherence, income, goal progress) with deltas
• TaskCompletionChart — LineChart: completed vs created per week
• HabitAdherenceChart — horizontal BarChart sorted by adherence %
• DomainActivityChart — horizontal bars (% of time blocks per domain)
• IncomeTrendChart — AreaChart (monthly)
• GoalProgressList — domain badge + title + progress bar per goal

Data

const { data: overview } = useAnalyticsOverview({ period });
const { data: taskTrend } = useTrends({ metric: 'tasks_completed', period: 'week', startDate });
const { data: habitAdherence } = useTrends({ metric: 'habit_adherence', period });
const { data: incomeTrend } = useTrends({ metric: 'income', period: 'month', startDate });

Key Interactions

• Period change → all charts and cards re-fetch
• Delta calculations: % change vs previous period
• Chart hover → tooltips
• Cross-highlight: hovering domain in one chart highlights it in others
• Goal click → navigate to goal detail

ADHD Features (from /today)

• "What should I do next?" button → calls suggestion engine → shows task + reason
• Energy-based task filtering (linked to morning assessment)
• Quick wins prominence when energy is low
• Break reminder timer (Pomodoro, client-side localStorage)
• Urgency color coding: overdue=red, today=amber, upcoming=neutral, quick-win=green

---

Implementation Phase

Phase 6 (Analytics & Polish) — AnalyticsModule, /analytics page, suggestion engine, ADHD features, animations.