Feature: Guided Multimodal Onboarding and Emotion Confidence Calibration

Summary

Add a guided onboarding and calibration workflow that helps users choose the right emotion input mode, understand confidence levels, and establish personal mood baselines before relying on recommendations.

Problem / Opportunity

Moodify supports text, speech, facial emotion detection, quick moods, and recommendation history. The product is powerful, but new users are dropped directly into multiple input modes without a structured way to learn which mode fits their situation or how reliable a given emotion result is. The architecture references confidence as a model concept, and landing copy mentions confidence and onboarding, but the active product workflow does not expose calibration or confidence-aware guidance.

Emotion detection can be subjective and context-dependent. A calibration flow would improve user trust, reduce misclassification frustration, and give the recommendation layer better personal context without overlapping mood journal, weekly recap, real-time blending, recommendation feedback, privacy export, sync, or provider abstraction work.

Proposed Feature

Create an optional onboarding/calibration flow for web and mobile:

• Introduce first-run onboarding that explains text, speech, face, and quick mood modes through actual interactive steps rather than static marketing copy.
• Let users complete a short baseline calibration by submitting one or more self-labeled mood examples.
• Store lightweight calibration metadata, such as preferred input mode, self-labeled baseline moods, skipped steps, and calibration timestamp.
• Display model confidence or confidence bands on analysis results when available from the inference service.
• Provide low-confidence recovery actions, such as retry with another modality, manually correct the mood, or continue with quick mood.
• Add a profile/settings area where users can rerun or reset calibration.

Scope

• Backend profile fields or a dedicated calibration record for onboarding state and baseline examples.
• API endpoints for saving, reading, resetting, and updating calibration state.
• Web onboarding/calibration screens integrated into the authenticated app flow.
• Mobile onboarding/calibration screens with parity for core steps.
• Result UI changes for confidence display and low-confidence recovery actions.
• Inference response contract update if confidence is not already returned consistently across modalities.
• Tests for onboarding state, calibration persistence, skipped flows, and low-confidence UI paths.

Acceptance Criteria

• New authenticated users can enter an optional guided onboarding flow before or from the Home screen.
• Users can select or confirm a preferred input mode during onboarding.
• Users can submit at least one self-labeled calibration example or explicitly skip calibration.
• Calibration state is persisted and can be retrieved by both web and mobile clients.
• Users can rerun or reset calibration from profile/settings.
• Analysis results display confidence or a confidence band when the inference response includes it.
• Low-confidence results provide clear recovery actions: retry another modality, manually correct mood, or continue anyway.
• Manual correction can be saved as calibration signal without corrupting mood history semantics.
• Tests cover first-run onboarding, skip behavior, reset behavior, confidence rendering, and low-confidence recovery actions.

Non-Goals

• Retraining production ML models from user calibration data in this first iteration.
• Diagnosing or treating mental health conditions.
• Forcing onboarding before anonymous users can try quick mood or text analysis.
• Replacing existing mood history or recommendation personalization logic.

Dependencies / Risks

• Confidence values must be comparable enough across text, speech, and facial models to avoid misleading users.
• Calibration examples are sensitive emotional data and should respect privacy and future consent controls.
• Manual corrections should improve UX without presenting the model as clinically accurate.

Open Questions

• Should confidence be shown as exact percentages, bands such as low/medium/high, or only as recovery prompts?
• Should calibration be available to anonymous users locally and merged after login?
• How many baseline examples are useful before the flow becomes too much friction?