Wellness & Productivity Services

Services for sleep tracking, mood journaling, habit tracking, goal management, and focused work sessions.

All wellness services follow a consistent pattern: SharedPreferences-backed persistence, lazy initialization via init(), sorted-descending storage, and analytics methods that operate on the in-memory list. Each service owns a single storage key and is independent of the others.

Common Pattern init() → addEntry() / deleteEntry() / updateEntry() → analytics methods. All mutations call _save() automatically. Services are safe to call before init() — they self-initialize on first data access.

SleepTrackerService

lib/core/services/sleep_tracker_service.dart

Manages sleep log entries with bedtime/wake time tracking, quality ratings, sleep factor analysis, and trend analytics. Supports sleep debt calculation and schedule consistency scoring.

Data Model

Field	Type	Description
`bedtime`	`DateTime`	When the user went to bed
`wakeTime`	`DateTime`	When the user woke up
`quality`	`SleepQuality`	Rating: terrible (1) → excellent (5)
`factors`	`List<SleepFactor>`	Contributing factors (caffeine, exercise, stress, etc.)
`awakenings`	`int`	Number of times woken during the night
`notes`	`String?`	Optional free-text notes

CRUD Methods

Method	Signature	Description
`init()`	`Future<void>`	Load entries from SharedPreferences (idempotent)
`addEntry(entry)`	`Future<void>`	Insert at front, auto-save
`deleteEntry(id)`	`Future<void>`	Remove by ID, auto-save
`updateEntry(entry)`	`Future<void>`	Replace by ID, auto-save
`entriesForDate(date)`	`List<SleepEntry>`	Filter entries by wake date
`entriesForLastDays(days)`	`List<SleepEntry>`	Entries within the last N days

Analytics Methods

Method	Returns	Description
`durationTrend(days)`	`Map<DateTime, double>`	Daily average sleep duration for chart data
`qualityTrend(days)`	`Map<DateTime, double>`	Daily average quality for chart data
`overallAvgDuration()`	`double?`	Lifetime average sleep hours
`overallAvgQuality()`	`double?`	Lifetime average quality (1–5)
`avgBedtimeHour(days)`	`double?`	Average bedtime (0–24), handles midnight normalization
`avgWakeTimeHour(days)`	`double?`	Average wake time (0–24)
`factorFrequency()`	`Map<SleepFactor, int>`	Factor occurrence counts, sorted descending
`qualityByFactor()`	`Map<SleepFactor, double>`	Average quality per factor (correlations)
`sleepDebt(days)`	`double`	Cumulative hours below target (default 8h)
`currentStreak()`	`int`	Consecutive days with sleep logs
`bestStreak()`	`int`	Longest-ever consecutive logging streak
`consistencyScore(days)`	`double`	Schedule consistency (0–100) based on bedtime/wake variance

Usage Example

final service = SleepTrackerService();
await service.init();

// Log last night's sleep
await service.addEntry(SleepEntry(
  id: 'uuid-1',
  bedtime: DateTime(2026, 3, 2, 23, 15),
  wakeTime: DateTime(2026, 3, 3, 7, 0),
  quality: SleepQuality.good,
  factors: [SleepFactor.exercise, SleepFactor.meditation],
));

// Check sleep debt this week
final debt = service.sleepDebt(7);  // hours below 8h target

// Which factors correlate with better sleep?
final correlations = service.qualityByFactor();
    

MoodJournalService

lib/core/services/mood_journal_service.dart

Tracks mood entries with a 5-level rating system, 14 activity tags, and notes. Provides trend analysis, activity-mood correlations, and streak tracking.

Data Model

Field	Type	Description
`mood`	`MoodLevel`	Rating: terrible (1) → great (5)
`activities`	`List<MoodActivity>`	What the user was doing (exercise, work, social, etc.)
`notes`	`String?`	Optional journal text
`timestamp`	`DateTime`	When the entry was recorded

Methods

Method	Returns	Description
`init()`	`Future<void>`	Load from SharedPreferences
`addEntry(entry)`	`Future<void>`	Add mood entry, auto-save
`deleteEntry(id)`	`Future<void>`	Remove by ID
`entriesForDate(date)`	`List<MoodEntry>`	Filter by date
`averageMoodForDate(date)`	`double?`	Mean mood level for a day
`moodTrend(days)`	`Map<DateTime, double>`	Daily average mood for charting
`activityFrequency()`	`Map<MoodActivity, int>`	How often each activity appears
`moodByActivity()`	`Map<MoodActivity, double>`	Average mood per activity (correlations)
`currentStreak()`	`int`	Consecutive days with entries

Correlation Insight Use moodByActivity() to discover which activities are associated with higher mood scores. This powers the Insights tab in the Mood Journal screen.

HabitTrackerService

lib/core/services/habit_tracker_service.dart

Manages daily habits with check-off tracking, streak counting, and completion statistics. Habits persist across sessions.

Data Model

Field	Type	Description
`name`	`String`	Habit name (e.g., "Meditate")
`icon`	`String`	Emoji icon for display
`completedDates`	`Set<DateTime>`	Dates the habit was completed
`createdAt`	`DateTime`	When the habit was created

Methods

Method	Returns	Description
`addHabit(habit)`	`void`	Add a new habit to track
`removeHabit(id)`	`void`	Remove a habit
`toggleCompletion(id, date)`	`void`	Toggle check-off for a date
`isCompletedOn(id, date)`	`bool`	Check if completed on a date
`currentStreak(id)`	`int`	Current consecutive-day streak
`completionRate(id, days)`	`double`	Completion percentage over N days
`todayProgress()`	`double`	Fraction of habits done today (0.0–1.0)

GoalTrackerService

lib/core/services/goal_tracker_service.dart

Manages goals with milestones, progress percentages, deadlines, and categories. Supports urgency sorting and summary statistics.

Data Model

Field	Type	Description
`title`	`String`	Goal name
`description`	`String?`	Detailed description
`category`	`GoalCategory`	Health, career, finance, education, personal, creative, social
`progress`	`int`	Completion percentage (0–100)
`deadline`	`DateTime?`	Optional target date
`milestones`	`List<Milestone>`	Sub-tasks with individual completion tracking
`status`	`GoalStatus`	active, completed, archived

Methods

Method	Returns	Description
`addGoal(goal)`	`void`	Add a new goal
`updateGoal(goal)`	`void`	Replace an existing goal
`deleteGoal(id)`	`void`	Remove permanently
`completeGoal(id)`	`void`	Mark as completed (100%)
`archiveGoal(id)`	`void`	Move to archived
`toggleMilestone(goalId, milestoneId)`	`void`	Toggle milestone completion
`updateProgress(goalId, progress)`	`void`	Set progress percentage
`getSummary()`	`GoalSummary`	Aggregate stats (active, completed, average progress)
`getByUrgency()`	`List<Goal>`	Active goals sorted by deadline proximity

Computed Properties

Property	Type	Description
`activeGoals`	`List<Goal>`	Goals with status = active
`completedGoals`	`List<Goal>`	Goals with status = completed
`overdueGoals`	`List<Goal>`	Active goals past their deadline

PomodoroService

lib/core/services/pomodoro_service.dart

Manages Pomodoro technique work sessions with configurable durations, automatic phase transitions (work → short break → long break), and daily statistics.

Settings

Setting	Default	Description
`workMinutes`	25	Focus session duration
`shortBreakMinutes`	5	Break between work sessions
`longBreakMinutes`	15	Break after every N work sessions
`longBreakInterval`	4	Work sessions before a long break

Methods

Method	Returns	Description
`nextPhase()`	`PomodoroPhase`	Determine next phase based on session count
`phaseDuration(phase)`	`int`	Minutes for the given phase
`startSession(phase)`	`PomodoroSession`	Begin a new session
`completeCurrentSession()`	`void`	Mark current session as completed
`todayStats()`	`PomodoroStats`	Today's completed sessions, focus minutes, streak
`reset()`	`void`	Clear all sessions and reset phase counter

Phase Cycle

// Default cycle with longBreakInterval = 4:
work → short break → work → short break → work → short break → work → long break → work → ...
    

Timer Not Included PomodoroService manages phase logic and statistics only. The countdown timer is handled by the UI layer (PomodoroScreen) using Timer.periodic.

DailyReviewService

lib/core/services/daily_review_service.dart

End-of-day reflection service with completion summaries, mood/energy tracking, highlights/lowlights, star ratings, and 7-day trend analysis.

Methods

Method	Returns	Description
`init()`	`Future<void>`	Load review history from SharedPreferences
`addReview(review)`	`Future<void>`	Save a daily review
`reviewForDate(date)`	`DailyReview?`	Get review for a specific date
`recentReviews(days)`	`List<DailyReview>`	Last N days of reviews
`currentStreak()`	`int`	Consecutive days with reviews
`averageRating(days)`	`double?`	Mean star rating over N days