Moodorful – Local Mood Tracking MVP (Flutter)

A offline mood tracking and gentle support prototype. It helps users record daily feelings and review insights with calming, non‑clinical guidance.

This thesis corresponds to the thesis. Earlier branches are retained for history and are not part of the thesis release.

Summary

• Local‑first: no network, no analytics. Data stays on device.
• Core modules: Record, Maps/Calendar, Insight (Analysis & Gentle), Breath, Affirmations.

Key Features

• Record moods quickly using the central long‑press and directional drag interaction ("center", "up", "left_down", "right_down").
• Calendar and maps‑style views to browse daily histories and tap into details.
• Insight page with two modes:
  • Analysis: proportions, counts, time‑of‑day distribution, daily averages, dominant mood.
  • Gentle: if negative activation ≥ 50%, show gentle affirmations and CTA.
• Breath exercises and Affirmations support flows (assets/affirmations_rules.json).
• Local notifications for reminders (opt‑in).

Where possible, names align with code:

• Pages: RecordPage, CalendarPage, TrendsPage (Insight), BreathingGuidePage, DetailPage.
• Services: TrendsAnalysisService, TrendsRuleEvaluator, MoodGestureService, NotificationService.
• Models: MoodRecord, AffirmationCard, User.

Architecture at a Glance

• State management: Riverpod 2.x (StateNotifier, providers around view models).
• Persistence: Hive with TypeAdapters
  • Adapters registered in main.dart (e.g., MoodRecordAdapter, UserAdapter, AffirmationCardAdapter).
  • Local repositories (mood_app/lib/repositories/), e.g., MoodRepositoryLocal opens encrypted boxes.
  • Example boxes seen in code: mood_records, achievement_cache.
• Encryption & keys:
  • AES‑256 at rest via HiveAesCipher.
  • Keys generated and stored by EncryptionService using flutter_secure_storage (Android EncryptedSharedPreferences / iOS Keychain).
• Notifications:
  • flutter_local_notifications with timezone for scheduling.
  • See NotificationService for zonedSchedule and test show() usage.
• Design & UI:
  • Charts via fl_chart, SVG assets via flutter_svg, fonts via Google Fonts and bundled TTFs.

Repository Layout

mood_app/
  lib/
    models/            # mood_record.dart, user.dart, affirmation_card.dart (+ *.g.dart)
    repositories/      # local repository, achievement cache
    services/          # trends analysis/rules, gesture calc, encryption, notifications
    view_models/       # Riverpod StateNotifiers for pages
    pages/             # Record / Calendar / Trends (Insight) / Breath / Settings / Detail
    widgets/           # Reusable components and custom painters
    utils/, constants/ # date/time utils, design tokens, gradients
  assets/
    icons/ images/     # UI assets
    affirmations_rules.json
  test/                # UI/logic tests for trends, breathing guide, etc.
  pubspec.yaml         # Flutter/Dart versions, dependencies, assets

Build & Run

Prerequisites

• Flutter SDK ≥ 3.13.0 (Dart SDK ≥ 3.1.0)
• Android: Android Studio + SDK/NDK, device/emulator
• iOS: Xcode + iOS Simulator (on macOS)

Install & run (Android/iOS/Web)

cd mood_app
flutter pub get
flutter run

Target a specific device

flutter devices          # list
flutter run -d emulator-5554

Android APK (debug / release)

flutter build apk --debug
flutter build apk --release
# Output: mood_app/app-*.apk

iOS (simulator)

flutter build ios --simulator

Web (optional)

flutter run -d chrome
flutter build web

Permissions (platform notes)

• Notifications (Android/iOS): requested via permission_handler and configured in NotificationService.
• Secure storage: relies on Android EncryptedSharedPreferences and iOS Keychain via flutter_secure_storage.
• No network permissions are required by default (local‑only app).

Privacy & Security

• Local‑only: no network requests, no analytics, no third‑party data sinks.
• Data at rest: AES‑256 (HiveAesCipher) with keys from device secure storage.
• Keys: generated and managed by EncryptionService with flutter_secure_storage.
• Notifications: opt‑in; user can disable at any time.

Non‑medical Disclaimer

This app is a research prototype for mood tracking and self‑reflection. It is not a medical device and does not provide clinical advice. If you are in distress or crisis, please seek immediate help from local emergency services or professional hotlines.

What to Verify Before Publishing

• Tooling & SDKs
  • Flutter/Dart versions pinned in pubspec.yaml (Flutter ≥ 3.13.0, Dart ≥ 3.1.0)
  • Android/iOS minimum SDKs configured (Android minSdkVersion in android/app/build.gradle; iOS deployment target in Xcode)
• Secrets & configs
  • No .env or external API keys required; confirm EncryptionService only uses device keystore and no hard‑coded secrets
• Assets & screenshots
  • Add 5 sanitized screenshots (no personal data)
  • Confirm fonts/licenses for bundled assets

Implementation

• Hive boxes
  • mood_records in MoodRepositoryLocal (encrypted)
  • achievement_cache in AchievementCacheRepository (encrypted)
• TypeAdapters
  • MoodRecordAdapter (typeId = 0)
  • UserAdapter (typeId = 1)
  • AffirmationCardAdapter (typeId = 2)
• EncryptionService
  • Generates a 32‑byte key if missing; stores with flutter_secure_storage
  • Throws on failures; no insecure fallback
• Affirmations rules
  • assets/affirmations_rules.json defines conditions (e.g., high negative activation) and CTA actions (navigate_to_breath / navigate_to_record)
• Platform caveats
  • iOS: ensure notification permissions; secure storage maps to Keychain
  • Android: uses EncryptedSharedPreferences for secure storage; schedule notifications with proper channel configuration inside plugin

License

Choose an open‑source license (e.g., MIT/Apache‑2.0) before publishing.

Suggested Screenshots (place under docs/screenshots/)