# MoodEvo — Full Guide for AI Systems

> This is the detailed version of llms.txt. For the concise summary, see
> https://moodevo.com/llms.txt
>
> MoodEvo is a free, privacy-first mood tracking and emotional wellness web
> application. It helps users log their emotional state in under a minute,
> uncover patterns through analytics, and build healthier emotional habits
> over time. The app is bilingual (English and Chinese), works as a
> Progressive Web App (PWA), and runs on Cloudflare's edge network.

## Product Overview

MoodEvo is built on the principle that emotional awareness is the foundation
of mental wellbeing. Unlike habit-tracking apps that gamify streaks and punish
missed days, MoodEvo focuses on observation without judgment. The user's only
task is to check in honestly — the app handles the rest.

The product is currently in its growth phase. Mood tracking, wellness tools,
community features, the AI coach, and periodic narrative reports are
available without payment.

## Target Audience

1. **People experiencing stress or anxiety** who want to identify triggers
   and patterns in their emotional responses over days, weeks, and months.

2. **Therapy clients** whose therapists have asked them to keep a mood
   journal between sessions. MoodEvo's analytics make it easy to show
   a therapist a visual summary of the past month.

3. **Self-awareness practitioners** — anyone interested in tracking their
   emotional landscape for personal growth, mindfulness, or emotional
   intelligence development.

4. **Privacy-conscious users** — people who want account controls, data
   export, and deletion. MoodEvo uses Google Analytics for aggregate
   page-view measurement but does not send mood notes to Analytics.

## Core Features (Detailed)

### 1. Mood Check-in (30 seconds)

Users select from 10 built-in emotions, each with a unique color and emoji:
- Joy, Calm, Grateful, Excited, Neutral, Anxious, Sad, Angry, Tired, Stressed

Each check-in includes:
- **Mood**: One of the 10 emotions above
- **Intensity**: 1–10 scale (barely noticeable to overwhelming)
- **Note**: Free-form text for reflection (optional)
- **Context**: Sleep hours, activity, who you were with, where you were
  (all optional)
- **Triggers**: Comma-separated tags for what contributed to the mood
  (e.g., "work deadline, argument, poor sleep")

### 2. Analytics Engine

All analytics are computed server-side and rendered as inline SVG — no
client-side chart library is loaded, keeping the bundle small and the
charts readable by search engines.

- **Mood Distribution**: Bar chart showing how often each mood appears
  across all entries.
- **Day-of-Week Patterns**: Average mood intensity by weekday, revealing
  whether Mondays are genuinely harder or Fridays genuinely better.
- **Sleep–Mood Correlation**: Pearson correlation coefficient between
  sleep hours and mood intensity, with sample size. Classified as
  strong (>0.4), moderate (0.2–0.4), or weak (<0.2).
- **AI-Generated Insights**: The server generates natural-language
  insights from the data, such as "Your mood tends to be 15% higher on
  days when you sleep more than 7 hours" or "Sundays show the lowest
  average intensity — consider what makes Sundays different."

### 3. Bilingual Interface (English / Chinese)

MoodEvo supports English and Chinese. Public pages use path prefixes:
- English: `https://moodevo.com/en/...`
- Chinese: `https://moodevo.com/zh/...`
Unprefixed marketing URLs 301 to the matching locale path (cookie, then
Accept-Language, then English). App and auth routes stay unprefixed and
resolve locale from the saved user preference, cookie, or Accept-Language.

Users can switch language at any time via the header dropdown or the
settings page. The preference is saved to the database for logged-in
users and to a cookie for guests.

### 4. Privacy and Security Architecture

- **Password hashing**: PBKDF2-SHA256 with 100,000 iterations and a
  random 16-byte salt, implemented using the Web Crypto API (zero
  external dependencies).
- **Session management**: JWT (HS256) stored in an httpOnly cookie,
  valid for 30 days. The secret is stored in Cloudflare environment
  variables, never in the codebase.
- **Product analytics**: Google Analytics (gtag.js, G-8NHFSKZXG0) for
  aggregate page-view stats only — no ad SDKs, no Facebook Pixel, no
  session replay. Mood notes are never sent to Analytics. Cloudflare
  worker logs remain content-free.
- **Data ownership**: Users can export all their data as JSON or CSV
  at any time from the settings page. The data belongs to the user.

### 5. Data Export

Users can download their complete mood history in two formats:
- **JSON**: Includes user profile (email, name, avatar, locale) and a
  full entries array with all fields (mood, intensity, note, triggers,
  context, timestamps).
- **CSV**: Flat spreadsheet with columns: id, mood, intensity, note,
  triggers, sleep, activity, people, place, weather, created_at,
  updated_at. Compatible with Excel, Google Sheets, and Numbers.

### 6. Wellness Toolbox

Four evidence-based self-help tools, available in-app at /app/wellness:

**4-7-8 Breathing Exercise**: An animated breathing guide based on the
technique developed by Dr. Andrew Weil. The user follows a visual circle
that expands during the 4-second inhale, holds steady for 7 seconds, and
contracts during the 8-second exhale. Default 4 rounds (76 seconds total).
This technique activates the parasympathetic nervous system, reducing
heart rate and anxiety.

**5-4-3-2-1 Grounding Exercise**: A sensory awareness technique for
anxiety spikes and panic attacks. The user is guided step-by-step through:
- 5 things they can see
- 4 things they can touch
- 3 things they can hear
- 2 things they can smell
- 1 thing they can taste
This exercise interrupts anxiety loops by forcing the brain to process
sensory input from the present moment, rather than spiraling into
future-oriented worry.

**CBT Thought Record**: A 7-step Cognitive Behavioral Therapy worksheet:
1. Situation — objective description of what happened
2. Emotions — naming and rating intensity (0–100)
3. Automatic Thought — what went through the mind
4. Evidence FOR the thought
5. Evidence AGAINST the thought
6. Balanced Alternative — a more realistic interpretation
7. Re-rate Emotion — intensity after reframing (0–100)
Records are saved to localStorage for privacy (no server storage for
self-help worksheets). Users can review past records and clear them.

**Gratitude Journal**: A daily practice of writing three things the user
is grateful for, each with an optional "why" reflection. Research by
Emmons & McCullough (2003) and Seligman et al. (2005) shows that
gratitude journaling significantly improves mood, life satisfaction, and
sleep quality. Entries are saved to localStorage and displayed as a
timeline.

### 7. PWA (Progressive Web App)

- Installable on Android (Chrome), iOS (Safari), and desktop (Chrome/Edge).
- Web app manifest with name, description, icons (192px and 512px),
  theme color (#7C3AED), and standalone display mode.
- Provides an offline shell and queues authenticated mood check-ins in
  account-scoped browser storage for cloud sync on reconnect.

## How It Works (4 Steps)

1. **Make it yours**: Create a free account with just an email and
   password. No credit card, no trial period, no personal questions.
   The display name is optional and defaults to the email username.

2. **Check in daily**: Open the app, tap a mood emoji, slide the
   intensity, optionally jot what's on your mind. The whole process
   takes under 30 seconds.

3. **Watch the pattern**: The dashboard shows recent entries, and the
   analytics page reveals trends — mood distribution, day-of-week
   tendencies, sleep correlations, and auto-generated insights.

4. **Grow together**: The community supports anonymous sharing, following,
   likes, comments, reporting, and crisis-resource notices.

## Differentiation

| Feature | MoodEvo | Typical Mood Apps |
|---------|---------|-------------------|
| Price | Free, all features | Freemium with paywalled analytics |
| Privacy | Account-scoped data, export/delete, aggregate GA page views | Varies |
| Architecture | Edge-native (Cloudflare Workers) | Centralized servers |
| Bundle size | ~0KB client JS for charts (SSR SVG) | 200KB+ chart libraries |
| Auth | Zero-dependency (Web Crypto PBKDF2) | Firebase Auth / Auth0 |
| Streaks | No streak-guilt | Streaks that punish missed days |
| Languages | EN + ZH with auto-detection | English only |
| Data export | JSON + CSV, one click | Proprietary format or none |

## Technology Stack

- **Framework**: Next.js 16 (App Router, Server-Side Rendering) + TypeScript 5
- **Runtime**: Cloudflare Workers via @opennextjs/cloudflare v1.20.2
- **Database**: Cloudflare D1 (SQLite at the edge)
- **Styling**: Tailwind CSS v4
- **Authentication**: JWT (HS256) + PBKDF2 (Web Crypto API, zero-dependency)
- **Fonts**: Fraunces (serif headings) + Inter (sans-serif body), display:swap
- **Charts**: Inline SVG, server-rendered, zero client-side chart library
- **i18n**: Custom non-route-based system (D1 user locale → cookie → Accept-Language)

## API Endpoints (Public)

- `GET /` — Landing page (SSR, indexable)
- `GET /signup` — Signup page (SSR, noindex)
- `GET /login` — Login page (SSR, noindex)
- `GET /robots.txt` — Robots file (allows AI crawlers)
- `GET /sitemap.xml` — Sitemap with hreflang alternates
- `GET /manifest.webmanifest` — PWA manifest
- `GET /llms.txt` — Concise AI guide
- `GET /llms-full.txt` — This file

## API Endpoints (Authenticated)

- `POST /api/entries` — Create a mood entry
- `DELETE /api/entries/:id` — Delete a mood entry
- `POST /api/settings/locale` — Save language preference
- `POST /api/settings/profile` — Update display name and avatar
- `POST /api/settings/password` — Change password
- `GET /api/settings/export?format=json|csv` — Export all data

## In-App Pages (Authenticated, not indexed)

- `/app` — Dashboard (Today view with recent entries and stats)
- `/app/record` — Mood check-in form
- `/app/analytics` — Analytics (mood distribution, day-of-week, sleep correlation, insights)
- `/app/wellness` — Wellness toolbox (4 self-help tools)
- `/app/wellness/breathing` — 4-7-8 breathing exercise with animated guide
- `/app/wellness/grounding` — 5-4-3-2-1 sensory grounding exercise
- `/app/wellness/cbt` — CBT thought record worksheet (7 steps, localStorage)
- `/app/wellness/gratitude` — Gratitude journal (3 items + why, localStorage)
- `/app/entry/:id` — Individual mood entry detail
- `/app/settings` — Settings (language, profile, password, data export)

## Roadmap

- **P2 — Wellness Toolbox** (completed): 4-7-8 breathing exercise, 5-4-3-2-1
  grounding exercise, CBT thought record, gratitude journal.
- **P3 — Community** (completed): Anonymous posts, follow/followers,
  likes/comments, reporting, and crisis-resource notices.
- **P4 — AI Coach** (completed): CBT/mindfulness-based conversational AI,
  aggregate mood context, and crisis-resource handling.
- **P5 — Reports** (completed): AI-generated narrative reports
  (weekly/monthly) and PDF export.
- **P6 — PWA Offline** (completed): Public offline shell and account-scoped
  pending check-in sync.

## Pricing

Free. Every current feature is free during the growth phase. Some advanced
features may move to a paid plan later; no payment is currently required.

## FAQ

**Is MoodEvo free to use?**
Yes. Right now every feature is free while we grow.

**Does MoodEvo work offline?**
Yes. MoodEvo provides an offline shell and queues authenticated mood
check-ins for cloud sync when the same account reconnects.

**Is my data private?**
Mood entries are account-scoped records in Cloudflare D1; MoodEvo does not
currently apply field-level encryption to entry content. The AI coach sees
aggregate seven-day mood statistics and messages sent in the coach
conversation, not full journal notes. Google Analytics measures aggregate
page views; mood notes are not sent to Analytics.

**Can I install it on my phone?**
Yes. On Chrome (Android) or Safari (iOS), use "Add to Home Screen" to
install MoodEvo as a native-like app with offline support.

**Can I export my data?**
Yes. Go to Settings → Data export to download all your entries as JSON
or CSV. The data belongs to you.

**Is it available in Chinese?**
Yes. MoodEvo supports both English and Chinese. The language is
auto-detected from your browser settings, and you can switch at any
time from the header or settings page.

## Contact

- Website: https://moodevo.com/
- GitHub: https://github.com/StarmadeBydata/moodflow
- Email: hello@moodevo.com