Initial commit: InnerVoice MVP

.gitignore

@@ -0,0 +1,29 @@
+# Environments
+.env
+.env.*
+!.env.example
+!.env.local.example
+
+# Node
+frontend/node_modules/
+frontend/.next/
+frontend/out/
+
+# Python
+backend/venv/
+backend/__pycache__/
+backend/*.pyc
+backend/.pytest_cache/
+
+# Databases
+*.db
+*.sqlite
+*.sqlite3
+
+# Models / ML
+*.pt
+*.bin
+*.h5
+
+# OS
+.DS_Store

README.md

@@ -0,0 +1,64 @@
+# InnerVoice — AI Emotional Wellness Tracker
+
+InnerVoice is a full-stack web application that allows users to record daily 60-second voice check-ins. The AI analyzes their voice to detect emotional signatures using acoustic features, tracking mental wellness trends over time.
+
+## Tech Stack
+- **Frontend**: Next.js 14, TailwindCSS, Recharts, Framer Motion
+- **Backend**: FastAPI, SQLAlchemy (SQLite/PostgreSQL)
+- **AI/ML**: `wav2vec2` (Emotion Classification), `librosa` (Acoustic Features), `OpenAI Whisper` (Transcription), `GPT-3.5` (Insights/Chat)
+
+## Demo Mode
+The UI is fully connected and defaults to **Demo Mode**, meaning it uses 30 days of pre-generated realistic mock data. You can explore the Dashboard, Timeline, and Chat without running the backend or providing an API key. 
+To disable Demo Mode, click the "Demo Mode ON" button in the sidebar or edit `.env.local`.
+
+---
+
+## 🚀 Quick Start (Production/Live Mode)
+
+If you want to run the real AI pipeline locally:
+
+### 1. Backend Setup (FastAPI + AI Services)
+The backend requires Python 3.10+ and downloads ~1.5GB of ML models on first run.
+```bash
+cd backend
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# Start the server (runs on http://localhost:8000)
+uvicorn main:app --reload
+```
+
+*Note: For the AI Companion and Insights to work, rename `backend/.env.example` to `backend/.env` and add your `OPENAI_API_KEY`.*
+
+### 2. Frontend Setup (Next.js)
+```bash
+cd frontend
+npm install
+
+# Start the dev server (runs on http://localhost:3000)
+npm run dev
+```
+
+Visit `http://localhost:3000` to start recording.
+
+### 3. Database Seeding (Optional)
+If you want to test the live backend but don't want to record 30 days of real audio first, you can seed the SQLite database with 30 days of realistic mock entries:
+```bash
+cd backend
+source venv/bin/activate
+python seed_data.py
+```
+This generates a user ID. Add that ID to `frontend/.env.local` as `NEXT_PUBLIC_DEMO_USER_ID`.
+
+---
+
+## Technical Features Implemented
+- **Web Audio API**: Client-side recording with real-time waveform visualization.
+- **Acoustic Extraction**: `librosa` extracts pitch, energy (RMS), tempo, pause duration, and zero-crossing rate (filler words).
+- **Emotion Inference**: HuggingFace `wav2vec2-lg-xlsr-en-speech-emotion-recognition` model lazy-loaded on the server.
+- **Trend Detection**: Week-over-week deviation analysis triggers alerts (e.g., "Mood declined 24%").
+- **State Injection Chat**: Custom GPT context window is injected with the last 30 days of voice metrics before the user asks a question, enabling personalized insights without fine-tuning.
+
+## Privacy Note
+Audio files are converted in-memory and deleted immediately after the feature-extraction pipeline completes. We only store acoustic metrics (floats), the transcription, and the detected emotion.

backend/.env.example

@@ -0,0 +1,5 @@
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+OPENROUTER_MODEL=meta-llama/llama-3-8b-instruct
+DATABASE_URL=sqlite:///./innervoice.db
+SECRET_KEY=change_me_to_a_random_secret_key_32chars
+CORS_ORIGINS=http://localhost:3000

backend/main.py

@@ -0,0 +1,72 @@
+"""
+FastAPI application entry point for InnerVoice backend.
+"""
+import os
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from models.database import init_db
+from routes.analyze import router as analyze_router
+from routes.entries import router as entries_router
+from routes.trends import router as trends_router
+from routes.alerts import router as alerts_router
+from routes.chat import router as chat_router
+
+app = FastAPI(
+    title="InnerVoice API",
+    description="AI-powered emotional wellness tracker backend",
+    version="1.0.0",
+)
+
+# CORS
+origins = os.getenv("CORS_ORIGINS", "http://localhost:3000").split(",")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Init DB on startup
+@app.on_event("startup")
+def startup():
+    init_db()
+    print("[InnerVoice] Database initialized.")
+
+# Register routers
+app.include_router(analyze_router, prefix="/api")
+app.include_router(entries_router, prefix="/api")
+app.include_router(trends_router, prefix="/api")
+app.include_router(alerts_router, prefix="/api")
+app.include_router(chat_router, prefix="/api")
+
+# User creation helper endpoint
+from fastapi import Depends
+from sqlalchemy.orm import Session
+from models.database import get_db, User
+from pydantic import BaseModel
+import uuid
+
+class UserCreate(BaseModel):
+    email: str
+    name: str
+
+@app.post("/api/users")
+def create_or_get_user(body: UserCreate, db: Session = Depends(get_db)):
+    user = db.query(User).filter(User.email == body.email).first()
+    if user:
+        return {"id": user.id, "email": user.email, "name": user.name, "existed": True}
+    user = User(id=str(uuid.uuid4()), email=body.email, name=body.name)
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+    return {"id": user.id, "email": user.email, "name": user.name, "existed": False}
+
+
+@app.get("/api/health")
+def health():
+    return {"status": "ok", "service": "InnerVoice API"}

backend/models/database.py

@@ -0,0 +1,108 @@
+import uuid
+from datetime import datetime
+from typing import Optional, List
+from sqlalchemy import (
+    create_engine, Column, String, Float, Integer,
+    Boolean, Text, ForeignKey, DateTime, JSON
+)
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker, relationship
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./innervoice.db")
+
+engine = create_engine(
+    DATABASE_URL,
+    connect_args={"check_same_thread": False} if "sqlite" in DATABASE_URL else {}
+)
+
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+Base = declarative_base()
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    email = Column(String, unique=True, nullable=False, index=True)
+    name = Column(String, nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    baseline_pitch = Column(Float, nullable=True)
+    baseline_energy = Column(Float, nullable=True)
+    baseline_speech_rate = Column(Float, nullable=True)
+
+    voice_entries = relationship("VoiceEntry", back_populates="user", cascade="all, delete-orphan")
+    mood_alerts = relationship("MoodAlert", back_populates="user", cascade="all, delete-orphan")
+    chat_messages = relationship("ChatMessage", back_populates="user", cascade="all, delete-orphan")
+
+
+class VoiceEntry(Base):
+    __tablename__ = "voice_entries"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    user_id = Column(String, ForeignKey("users.id"), nullable=False, index=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    audio_url = Column(String, nullable=True)
+    duration_seconds = Column(Float, nullable=True)
+    transcription = Column(Text, nullable=True)
+    primary_emotion = Column(String, nullable=True)
+    emotion_confidence = Column(Float, nullable=True)
+    energy_score = Column(Integer, nullable=True)
+    calmness_score = Column(Integer, nullable=True)
+    mood_score = Column(Integer, nullable=True)
+    clarity_score = Column(Integer, nullable=True)
+    pitch_mean = Column(Float, nullable=True)
+    pitch_std = Column(Float, nullable=True)
+    energy_raw = Column(Float, nullable=True)
+    speech_rate = Column(Float, nullable=True)
+    pause_count = Column(Integer, nullable=True)
+    avg_pause_duration = Column(Float, nullable=True)
+    filler_rate = Column(Float, nullable=True)
+    mfcc_features = Column(JSON, nullable=True)
+
+    user = relationship("User", back_populates="voice_entries")
+    chat_messages = relationship("ChatMessage", back_populates="voice_entry")
+
+
+class MoodAlert(Base):
+    __tablename__ = "mood_alerts"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    user_id = Column(String, ForeignKey("users.id"), nullable=False, index=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    alert_type = Column(String, nullable=False)
+    severity = Column(String, nullable=False)
+    message = Column(Text, nullable=False)
+    is_read = Column(Boolean, default=False)
+    suggested_action = Column(Text, nullable=True)
+
+    user = relationship("User", back_populates="mood_alerts")
+
+
+class ChatMessage(Base):
+    __tablename__ = "chat_messages"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    user_id = Column(String, ForeignKey("users.id"), nullable=False, index=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    role = Column(String, nullable=False)  # user / assistant
+    content = Column(Text, nullable=False)
+    voice_entry_id = Column(String, ForeignKey("voice_entries.id"), nullable=True)
+
+    user = relationship("User", back_populates="chat_messages")
+    voice_entry = relationship("VoiceEntry", back_populates="chat_messages")
+
+
+def init_db():
+    Base.metadata.create_all(bind=engine)

backend/requirements.txt

@@ -0,0 +1,17 @@
+fastapi==0.111.0
+uvicorn[standard]==0.30.1
+sqlalchemy==2.0.30
+python-multipart==0.0.9
+python-dotenv==1.0.1
+pydub==0.25.1
+librosa==0.10.2
+numpy==1.26.4
+scipy==1.13.0
+openai==1.30.1
+httpx==0.27.0
+aiofiles==23.2.1
+# ML models — comment out if you want faster install without AI analysis
+transformers==4.41.2
+torch==2.3.0
+torchaudio==2.3.0
+openai-whisper==20231117

backend/routes/alerts.py

@@ -0,0 +1,41 @@
+"""
+GET  /api/alerts         — fetch unread alerts for a user
+PUT  /api/alerts/{id}/read — mark alert as read
+"""
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+from models.database import get_db, MoodAlert
+
+router = APIRouter()
+
+
+@router.get("/alerts")
+def get_alerts(user_id: str, db: Session = Depends(get_db)):
+    alerts = (
+        db.query(MoodAlert)
+        .filter(MoodAlert.user_id == user_id, MoodAlert.is_read == False)
+        .order_by(MoodAlert.created_at.desc())
+        .all()
+    )
+    return [
+        {
+            "id": a.id,
+            "created_at": a.created_at.isoformat(),
+            "alert_type": a.alert_type,
+            "severity": a.severity,
+            "message": a.message,
+            "suggested_action": a.suggested_action,
+            "is_read": a.is_read,
+        }
+        for a in alerts
+    ]
+
+
+@router.put("/alerts/{alert_id}/read")
+def mark_alert_read(alert_id: str, db: Session = Depends(get_db)):
+    alert = db.query(MoodAlert).filter(MoodAlert.id == alert_id).first()
+    if not alert:
+        raise HTTPException(status_code=404, detail="Alert not found")
+    alert.is_read = True
+    db.commit()
+    return {"success": True}

backend/routes/analyze.py

@@ -0,0 +1,159 @@
+"""
+POST /api/analyze — Full voice analysis pipeline
+"""
+import os
+import tempfile
+from fastapi import APIRouter, UploadFile, File, Form, Depends, HTTPException
+from sqlalchemy.orm import Session
+from models.database import get_db, VoiceEntry, MoodAlert, User
+from services.audio_processor import convert_to_wav, extract_features
+from services.emotion_analyzer import classify_emotion
+from services.text_emotion import classify_text_emotion
+from services.emotion_fusion import fuse_emotions
+from services.transcriber import transcribe
+from services.mood_calculator import calculate_mood_scores
+from services.trend_detector import check_trends
+from services.gpt_service import generate_insight
+import uuid
+
+router = APIRouter()
+
+
+@router.post("/analyze")
+async def analyze_audio(
+    audio: UploadFile = File(...),
+    user_id: str = Form(...),
+    db: Session = Depends(get_db),
+):
+    # 1. Save uploaded audio to temp file
+    suffix = ".webm" if audio.content_type == "audio/webm" else ".wav"
+    tmp_fd, tmp_path = tempfile.mkstemp(suffix=suffix)
+    wav_path = None
+    try:
+        content = await audio.read()
+        with os.fdopen(tmp_fd, "wb") as f:
+            f.write(content)
+
+        # 2. Convert to WAV 16kHz mono
+        wav_path = convert_to_wav(tmp_path)
+
+        # 3. Run emotion classification (acoustic)
+        audio_emotion_result = classify_emotion(wav_path)
+
+        # 4. Extract acoustic features
+        features = extract_features(wav_path)
+
+        # 5. Transcribe (speech to text)
+        transcription = transcribe(wav_path)
+
+        # 5b. Run emotion classification (text)
+        text_emotion_result = classify_text_emotion(transcription)
+
+        # 5c. Fuse acoustic and text emotion predictions
+        emotion_result = fuse_emotions(audio_emotion_result, text_emotion_result)
+        emotion = emotion_result["emotion"]
+        confidence = emotion_result["confidence"]
+
+        # 6. Calculate mood scores
+        mood_scores = calculate_mood_scores(
+            emotion=emotion,
+            confidence=confidence,
+            pitch_mean=features["pitch_mean"],
+            pitch_std=features["pitch_std"],
+            energy=features["energy_raw"],
+            tempo=features["speech_rate"],
+            avg_pause=features["avg_pause_duration"],
+            filler_rate=features["filler_rate"],
+        )
+
+        # 7. Generate AI insight
+        insight = generate_insight(
+            emotion=emotion,
+            confidence=confidence,
+            mood_scores=mood_scores,
+            transcription=transcription,
+            features=features,
+        )
+
+        # 8. Save voice entry to DB
+        entry = VoiceEntry(
+            id=str(uuid.uuid4()),
+            user_id=user_id,
+            transcription=transcription,
+            primary_emotion=emotion,
+            emotion_confidence=confidence,
+            energy_score=mood_scores["energy"],
+            calmness_score=mood_scores["calmness"],
+            mood_score=mood_scores["mood"],
+            clarity_score=mood_scores["clarity"],
+            pitch_mean=features["pitch_mean"],
+            pitch_std=features["pitch_std"],
+            energy_raw=features["energy_raw"],
+            speech_rate=features["speech_rate"],
+            pause_count=features["pause_count"],
+            avg_pause_duration=features["avg_pause_duration"],
+            filler_rate=features["filler_rate"],
+            mfcc_features=features["mfcc_features"],
+            duration_seconds=features["duration_seconds"],
+        )
+        db.add(entry)
+        db.commit()
+        db.refresh(entry)
+
+        # 9. Check for trend alerts
+        all_entries = (
+            db.query(VoiceEntry)
+            .filter(VoiceEntry.user_id == user_id)
+            .order_by(VoiceEntry.created_at)
+            .all()
+        )
+        new_alerts = check_trends(all_entries)
+        saved_alerts = []
+        for alert_data in new_alerts:
+            # Avoid duplicate alerts of same type in last 7 days
+            from datetime import datetime, timedelta
+            cutoff = datetime.utcnow() - timedelta(days=7)
+            existing = (
+                db.query(MoodAlert)
+                .filter(
+                    MoodAlert.user_id == user_id,
+                    MoodAlert.alert_type == alert_data["type"],
+                    MoodAlert.created_at >= cutoff,
+                )
+                .first()
+            )
+            if not existing:
+                alert = MoodAlert(
+                    user_id=user_id,
+                    alert_type=alert_data["type"],
+                    severity=alert_data["severity"],
+                    message=alert_data["message"],
+                    suggested_action=alert_data.get("suggested_action"),
+                )
+                db.add(alert)
+                db.commit()
+                saved_alerts.append({
+                    "id": alert.id,
+                    "type": alert.alert_type,
+                    "severity": alert.severity,
+                    "message": alert.message,
+                    "suggested_action": alert.suggested_action,
+                })
+
+        return {
+            "entry_id": entry.id,
+            "emotion": emotion,
+            "confidence": confidence,
+            "mood_scores": mood_scores,
+            "transcription": transcription,
+            "features": features,
+            "insight": insight,
+            "new_alerts": saved_alerts,
+        }
+
+    finally:
+        # Always delete temp files (audio is never stored permanently)
+        if os.path.exists(tmp_path):
+            os.remove(tmp_path)
+        if wav_path and os.path.exists(wav_path):
+            os.remove(wav_path)

backend/routes/chat.py

@@ -0,0 +1,93 @@
+"""
+POST /api/chat — AI companion chat with full user context
+"""
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+from models.database import get_db, ChatMessage, VoiceEntry
+from services.gpt_service import chat_response
+import uuid
+
+router = APIRouter()
+
+
+class ChatRequest(BaseModel):
+    user_id: str
+    message: str
+    voice_entry_id: str | None = None
+
+
+@router.post("/chat")
+def chat(req: ChatRequest, db: Session = Depends(get_db)):
+    # Fetch recent voice entries for context
+    recent_entries = (
+        db.query(VoiceEntry)
+        .filter(VoiceEntry.user_id == req.user_id)
+        .order_by(VoiceEntry.created_at.desc())
+        .limit(30)
+        .all()
+    )
+    recent_entries = list(reversed(recent_entries))
+
+    # Fetch conversation history
+    history = (
+        db.query(ChatMessage)
+        .filter(ChatMessage.user_id == req.user_id)
+        .order_by(ChatMessage.created_at.asc())
+        .limit(40)
+        .all()
+    )
+    history_dicts = [{"role": m.role, "content": m.content} for m in history]
+
+    # Get AI response
+    response_text = chat_response(
+        user_message=req.message,
+        recent_entries=recent_entries,
+        conversation_history=history_dicts,
+    )
+
+    # Save user message
+    user_msg = ChatMessage(
+        id=str(uuid.uuid4()),
+        user_id=req.user_id,
+        role="user",
+        content=req.message,
+        voice_entry_id=req.voice_entry_id,
+    )
+    db.add(user_msg)
+
+    # Save assistant response
+    ai_msg = ChatMessage(
+        id=str(uuid.uuid4()),
+        user_id=req.user_id,
+        role="assistant",
+        content=response_text,
+        voice_entry_id=req.voice_entry_id,
+    )
+    db.add(ai_msg)
+    db.commit()
+
+    return {
+        "response": response_text,
+        "message_id": ai_msg.id,
+    }
+
+
+@router.get("/chat/history")
+def get_chat_history(user_id: str, db: Session = Depends(get_db)):
+    messages = (
+        db.query(ChatMessage)
+        .filter(ChatMessage.user_id == user_id)
+        .order_by(ChatMessage.created_at.asc())
+        .limit(100)
+        .all()
+    )
+    return [
+        {
+            "id": m.id,
+            "role": m.role,
+            "content": m.content,
+            "created_at": m.created_at.isoformat(),
+        }
+        for m in messages
+    ]

backend/routes/entries.py

@@ -0,0 +1,43 @@
+"""
+GET /api/entries — fetch voice entries for a user
+"""
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.orm import Session
+from models.database import get_db, VoiceEntry
+from datetime import datetime, timedelta
+
+router = APIRouter()
+
+
+@router.get("/entries")
+def get_entries(
+    user_id: str,
+    days: int = Query(default=30, ge=1, le=365),
+    db: Session = Depends(get_db),
+):
+    cutoff = datetime.utcnow() - timedelta(days=days)
+    entries = (
+        db.query(VoiceEntry)
+        .filter(VoiceEntry.user_id == user_id, VoiceEntry.created_at >= cutoff)
+        .order_by(VoiceEntry.created_at)
+        .all()
+    )
+    return [
+        {
+            "id": e.id,
+            "created_at": e.created_at.isoformat(),
+            "primary_emotion": e.primary_emotion,
+            "emotion_confidence": e.emotion_confidence,
+            "energy_score": e.energy_score,
+            "calmness_score": e.calmness_score,
+            "mood_score": e.mood_score,
+            "clarity_score": e.clarity_score,
+            "transcription": e.transcription,
+            "duration_seconds": e.duration_seconds,
+            "pitch_mean": e.pitch_mean,
+            "speech_rate": e.speech_rate,
+            "pause_count": e.pause_count,
+            "filler_rate": e.filler_rate,
+        }
+        for e in entries
+    ]

backend/routes/trends.py

@@ -0,0 +1,96 @@
+"""
+GET /api/trends — week-over-week comparisons and pattern insights
+"""
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.orm import Session
+from models.database import get_db, VoiceEntry
+from datetime import datetime, timedelta
+from statistics import mean
+from collections import Counter
+
+router = APIRouter()
+
+
+@router.get("/trends")
+def get_trends(user_id: str, db: Session = Depends(get_db)):
+    entries = (
+        db.query(VoiceEntry)
+        .filter(VoiceEntry.user_id == user_id)
+        .order_by(VoiceEntry.created_at)
+        .all()
+    )
+
+    if not entries:
+        return {"entries_count": 0, "trends": {}, "patterns": [], "insights": []}
+
+    now = datetime.utcnow()
+
+    # ── Week over week ────────────────────────────────────────────────────────
+    this_week_cutoff = now - timedelta(days=7)
+    last_week_cutoff = now - timedelta(days=14)
+    this_week = [e for e in entries if e.created_at >= this_week_cutoff]
+    last_week = [e for e in entries if last_week_cutoff <= e.created_at < this_week_cutoff]
+
+    def avg_score(es, field):
+        vals = [getattr(e, field) for e in es if getattr(e, field) is not None]
+        return round(mean(vals), 1) if vals else None
+
+    this_week_avg = {
+        "mood": avg_score(this_week, "mood_score"),
+        "energy": avg_score(this_week, "energy_score"),
+        "calmness": avg_score(this_week, "calmness_score"),
+        "clarity": avg_score(this_week, "clarity_score"),
+    }
+    last_week_avg = {
+        "mood": avg_score(last_week, "mood_score"),
+        "energy": avg_score(last_week, "energy_score"),
+        "calmness": avg_score(last_week, "calmness_score"),
+        "clarity": avg_score(last_week, "clarity_score"),
+    }
+
+    # ── Streak ────────────────────────────────────────────────────────────────
+    streak = 0
+    check_date = now.date()
+    entry_dates = {e.created_at.date() for e in entries}
+    while check_date in entry_dates:
+        streak += 1
+        check_date -= timedelta(days=1)
+
+    # ── Most common emotion this month ────────────────────────────────────────
+    month_cutoff = now - timedelta(days=30)
+    month_entries = [e for e in entries if e.created_at >= month_cutoff]
+    emotion_counts = Counter(
+        e.primary_emotion for e in month_entries if e.primary_emotion
+    )
+    most_common_emotion = emotion_counts.most_common(1)[0][0] if emotion_counts else None
+
+    # ── Pattern insights ──────────────────────────────────────────────────────
+    insights = []
+    if len(entries) >= 7:
+        # Day-of-week patterns
+        from collections import defaultdict
+        day_moods = defaultdict(list)
+        for e in entries[-60:]:
+            if e.mood_score is not None:
+                day_name = e.created_at.strftime("%A")
+                day_moods[day_name].append(e.mood_score)
+        if day_moods:
+            best_day = max(day_moods, key=lambda d: mean(day_moods[d]))
+            worst_day = min(day_moods, key=lambda d: mean(day_moods[d]))
+            insights.append(f"Your best days tend to be {best_day}s")
+            if worst_day != best_day:
+                insights.append(f"Your mood tends to dip on {worst_day}s")
+
+        # Improvement streak
+        recent_5 = [e.mood_score for e in entries[-5:] if e.mood_score]
+        if len(recent_5) >= 3 and all(recent_5[i] <= recent_5[i+1] for i in range(len(recent_5)-1)):
+            insights.append(f"You've been improving steadily for {len(recent_5)} days 🌱")
+
+    return {
+        "entries_count": len(entries),
+        "streak": streak,
+        "most_common_emotion": most_common_emotion,
+        "this_week": this_week_avg,
+        "last_week": last_week_avg,
+        "insights": insights,
+    }

backend/seed_data.py

@@ -0,0 +1,230 @@
+"""
+Seed the database with 30 days of realistic mock data for demo mode.
+Run: python seed_data.py
+"""
+import sys
+import os
+import uuid
+import random
+from datetime import datetime, timedelta
+from dotenv import load_dotenv
+
+load_dotenv()
+sys.path.insert(0, os.path.dirname(__file__))
+
+from models.database import init_db, SessionLocal, User, VoiceEntry, MoodAlert, ChatMessage
+
+DEMO_USER_EMAIL = "demo@innervoice.app"
+DEMO_USER_NAME = "Alex (Demo)"
+
+EMOTIONS = ["happy", "neutral", "sad", "anxious", "fearful", "angry"]
+EMOTION_WEIGHTS = [0.30, 0.28, 0.18, 0.12, 0.07, 0.05]
+
+TRANSCRIPTIONS = {
+    "happy": [
+        "Today was actually really good. I feel like things are finally clicking into place and I'm excited about what's ahead.",
+        "I had a great time with friends this evening. Laughed a lot. Really needed that connection.",
+        "Finished a project I've been working on for weeks. Feels so satisfying to see it done.",
+        "Went for a long walk this morning and the sunshine just lifted everything. Feeling grateful.",
+    ],
+    "neutral": [
+        "It's been a regular day. Nothing spectacular, nothing bad. Just steady.",
+        "Work was fine. Meetings ran long but got through it. Feeling okay overall.",
+        "Pretty normal Tuesday. Had lunch outside which was nice. Mostly just going through the motions.",
+        "No major feelings today. I'm present, just... existing. That's okay too.",
+    ],
+    "sad": [
+        "I don't really know how to explain it. Just feel a heaviness today that I can't shake.",
+        "Missing some people today. Feeling a bit disconnected from everything.",
+        "Things feel harder than they should. I'm trying but motivation is low.",
+        "Cried a little this evening and I'm not even sure why. Just needed to let it out.",
+    ],
+    "anxious": [
+        "My mind keeps racing about things I can't control. Hard to focus on the present.",
+        "Feeling that familiar chest tightness again. Too many things on my plate.",
+        "The week ahead feels overwhelming. I'm trying to take it one thing at a time.",
+        "Lots of uncertainty right now and my nervous system is definitely feeling it.",
+    ],
+    "fearful": [
+        "Something doesn't feel right but I can't name it. Just uneasy.",
+        "Woke up with a sense of dread this morning. Trying to ground myself.",
+        "Scared about some changes happening in my life. Trying to trust the process.",
+    ],
+    "angry": [
+        "Really frustrated today. Feel like I'm not being heard or seen.",
+        "Had a tense situation at work. Hard not to carry that home.",
+        "Some things happened today that felt unfair and I'm still processing the anger.",
+    ],
+}
+
+
+def generate_entry(user_id: str, days_ago: int) -> VoiceEntry:
+    # Generate a realistic mood arc (dip in middle, recovery)
+    progress = days_ago / 30.0  # 0 = most recent, 1 = oldest
+    base_mood_shift = int(20 * (0.5 - abs(progress - 0.6)))  # dip 18 days ago
+
+    emotion = random.choices(EMOTIONS, weights=EMOTION_WEIGHTS)[0]
+    confidence = round(random.uniform(0.60, 0.95), 3)
+
+    from services.mood_calculator import calculate_mood_scores
+    pitch_mean = random.uniform(100, 200)
+    pitch_std = random.uniform(10, 60)
+    energy = random.uniform(0.005, 0.04)
+    tempo = random.uniform(60, 120)
+    avg_pause = random.uniform(0.1, 0.8)
+    filler_rate = random.uniform(0.01, 0.08)
+
+    scores = calculate_mood_scores(
+        emotion=emotion,
+        confidence=confidence,
+        pitch_mean=pitch_mean,
+        pitch_std=pitch_std,
+        energy=energy,
+        tempo=tempo,
+        avg_pause=avg_pause,
+        filler_rate=filler_rate,
+    )
+
+    # Apply arc shift
+    for key in scores:
+        scores[key] = max(0, min(100, scores[key] + base_mood_shift + random.randint(-5, 5)))
+
+    transcription_options = TRANSCRIPTIONS.get(emotion, TRANSCRIPTIONS["neutral"])
+    transcription = random.choice(transcription_options)
+
+    created_at = datetime.utcnow() - timedelta(days=days_ago, hours=random.randint(6, 22))
+
+    return VoiceEntry(
+        id=str(uuid.uuid4()),
+        user_id=user_id,
+        created_at=created_at,
+        audio_url=None,
+        duration_seconds=round(random.uniform(30, 65), 1),
+        transcription=transcription,
+        primary_emotion=emotion,
+        emotion_confidence=confidence,
+        energy_score=scores["energy"],
+        calmness_score=scores["calmness"],
+        mood_score=scores["mood"],
+        clarity_score=scores["clarity"],
+        pitch_mean=round(pitch_mean, 2),
+        pitch_std=round(pitch_std, 2),
+        energy_raw=round(energy, 6),
+        speech_rate=round(tempo, 2),
+        pause_count=random.randint(2, 15),
+        avg_pause_duration=round(avg_pause, 3),
+        filler_rate=round(filler_rate, 4),
+        mfcc_features=[round(random.uniform(-50, 50), 2) for _ in range(13)],
+    )
+
+
+def seed():
+    init_db()
+    db = SessionLocal()
+    try:
+        # Create or get demo user
+        user = db.query(User).filter(User.email == DEMO_USER_EMAIL).first()
+        if not user:
+            user = User(
+                id=str(uuid.uuid4()),
+                email=DEMO_USER_EMAIL,
+                name=DEMO_USER_NAME,
+            )
+            db.add(user)
+            db.commit()
+            db.refresh(user)
+            print(f"[Seed] Created demo user: {user.id}")
+        else:
+            print(f"[Seed] Demo user exists: {user.id}")
+            # Clear old entries
+            db.query(VoiceEntry).filter(VoiceEntry.user_id == user.id).delete()
+            db.query(MoodAlert).filter(MoodAlert.user_id == user.id).delete()
+            db.query(ChatMessage).filter(ChatMessage.user_id == user.id).delete()
+            db.commit()
+
+        # Generate 30 days of entries (skip ~20% of days for realism)
+        entries = []
+        for days_ago in range(30, 0, -1):
+            if random.random() < 0.80:  # 80% check-in rate
+                entry = generate_entry(user.id, days_ago)
+                db.add(entry)
+                entries.append(entry)
+
+        db.commit()
+        print(f"[Seed] Created {len(entries)} voice entries.")
+
+        # Create sample alerts
+        alerts = [
+            MoodAlert(
+                id=str(uuid.uuid4()),
+                user_id=user.id,
+                created_at=datetime.utcnow() - timedelta(days=2),
+                alert_type="mood_decline",
+                severity="warning",
+                message="Your mood has declined 24% this week compared to last week.",
+                suggested_action="Try scheduling something enjoyable today, even something small.",
+                is_read=False,
+            ),
+            MoodAlert(
+                id=str(uuid.uuid4()),
+                user_id=user.id,
+                created_at=datetime.utcnow() - timedelta(days=1),
+                alert_type="low_energy",
+                severity="concern",
+                message="Your energy has been consistently low for the past 5 days.",
+                suggested_action="Even a 10-minute walk can shift your energy. Try it today.",
+                is_read=False,
+            ),
+        ]
+        for alert in alerts:
+            db.add(alert)
+
+        # Create sample chat messages
+        chats = [
+            ChatMessage(
+                id=str(uuid.uuid4()),
+                user_id=user.id,
+                created_at=datetime.utcnow() - timedelta(hours=3),
+                role="user",
+                content="I'm fine, just tired.",
+            ),
+            ChatMessage(
+                id=str(uuid.uuid4()),
+                user_id=user.id,
+                created_at=datetime.utcnow() - timedelta(hours=3, seconds=-5),
+                role="assistant",
+                content="I hear you — and 'tired' can mean so many things. Your voice this week has been a little lower in energy than usual. Is there something specific weighing on you, or is it more of a general fatigue?",
+            ),
+            ChatMessage(
+                id=str(uuid.uuid4()),
+                user_id=user.id,
+                created_at=datetime.utcnow() - timedelta(hours=2),
+                role="user",
+                content="Why have I been feeling off lately?",
+            ),
+            ChatMessage(
+                id=str(uuid.uuid4()),
+                user_id=user.id,
+                created_at=datetime.utcnow() - timedelta(hours=2, seconds=-5),
+                role="assistant",
+                content="Looking at your last two weeks, your mood started dipping around 18 days ago and your energy has been below your baseline since then. That sometimes happens during seasonal changes or when routines get disrupted. Does anything stand out from around that time?",
+            ),
+        ]
+        for chat in chats:
+            db.add(chat)
+
+        db.commit()
+        print(f"[Seed] Created {len(alerts)} alerts and {len(chats)} chat messages.")
+        print(f"[Seed] Demo user ID: {user.id}")
+        print(f"[Seed] Seeding complete ✓")
+
+        return user.id
+
+    finally:
+        db.close()
+
+
+if __name__ == "__main__":
+    user_id = seed()
+    print(f"\nDemo user ID: {user_id}")
+    print("Use this ID in Demo Mode or set NEXT_PUBLIC_DEMO_USER_ID in frontend/.env.local")

backend/services/audio_processor.py

@@ -0,0 +1,80 @@
+"""
+Audio processing: convert to WAV 16kHz mono and extract librosa features.
+Temp files are deleted immediately after feature extraction.
+"""
+import os
+import tempfile
+import numpy as np
+from typing import Optional
+
+
+def convert_to_wav(input_path: str) -> str:
+    """Convert any audio format to WAV 16kHz mono. Returns path to WAV file."""
+    try:
+        from pydub import AudioSegment
+        audio = AudioSegment.from_file(input_path)
+        audio = audio.set_frame_rate(16000).set_channels(1)
+        wav_fd, wav_path = tempfile.mkstemp(suffix=".wav")
+        os.close(wav_fd)
+        audio.export(wav_path, format="wav")
+        return wav_path
+    except Exception as e:
+        raise RuntimeError(f"Audio conversion failed: {e}")
+
+
+def extract_features(wav_path: str) -> dict:
+    """
+    Extract acoustic features from a 16kHz mono WAV file.
+    Returns a dict with pitch, energy, speech_rate, pauses, MFCCs, filler_rate.
+    """
+    import librosa
+
+    y, sr = librosa.load(wav_path, sr=16000, mono=True)
+    duration = librosa.get_duration(y=y, sr=sr)
+
+    # ── Pitch ────────────────────────────────────────────────────────────────
+    f0, voiced_flag, _ = librosa.pyin(
+        y, fmin=librosa.note_to_hz("C2"), fmax=librosa.note_to_hz("C7"), sr=sr
+    )
+    f0_clean = f0[voiced_flag == 1] if voiced_flag is not None else np.array([])
+    pitch_mean = float(np.mean(f0_clean)) if len(f0_clean) > 0 else 0.0
+    pitch_std = float(np.std(f0_clean)) if len(f0_clean) > 0 else 0.0
+
+    # ── Energy / RMS ─────────────────────────────────────────────────────────
+    rms = librosa.feature.rms(y=y)[0]
+    energy_raw = float(np.sqrt(np.mean(rms ** 2)))
+
+    # ── Tempo (speech rate proxy) ─────────────────────────────────────────────
+    tempo_arr, _ = librosa.beat.beat_track(y=y, sr=sr)
+    tempo = float(tempo_arr) if np.isscalar(tempo_arr) else float(tempo_arr[0])
+
+    # ── Pauses (silence detection) ────────────────────────────────────────────
+    intervals = librosa.effects.split(y, top_db=30)
+    pauses = []
+    for i in range(1, len(intervals)):
+        gap = (intervals[i][0] - intervals[i - 1][1]) / sr
+        if gap > 0.2:
+            pauses.append(gap)
+    pause_count = len(pauses)
+    avg_pause_duration = float(np.mean(pauses)) if pauses else 0.0
+
+    # ── MFCCs ────────────────────────────────────────────────────────────────
+    mfccs = librosa.feature.mfcc(y=y, sr=sr, n_mfcc=13)
+    mfcc_means = [round(float(np.mean(mfccs[i])), 4) for i in range(13)]
+
+    # ── Filler Rate (estimate via zero crossing rate) ─────────────────────────
+    # High ZCR in quiet segments indicates filler sounds (um, uh, er)
+    zcr = librosa.feature.zero_crossing_rate(y)[0]
+    filler_rate = float(np.mean(zcr)) * 2  # scale to ~0–1 range
+
+    return {
+        "pitch_mean": round(pitch_mean, 2),
+        "pitch_std": round(pitch_std, 2),
+        "energy_raw": round(energy_raw, 6),
+        "speech_rate": round(tempo, 2),
+        "pause_count": pause_count,
+        "avg_pause_duration": round(avg_pause_duration, 3),
+        "filler_rate": round(filler_rate, 4),
+        "mfcc_features": mfcc_means,
+        "duration_seconds": round(duration, 2),
+    }

backend/services/emotion_analyzer.py

@@ -0,0 +1,75 @@
+"""
+Emotion analysis using wav2vec2.
+Model: ehcalabres/wav2vec2-lg-xlsr-en-speech-emotion-recognition
+
+Lazy-loaded on first call to avoid slow startup.
+Falls back to a heuristic if the model is unavailable.
+"""
+import numpy as np
+from typing import Optional
+
+_pipeline = None
+
+
+def _load_model():
+    global _pipeline
+    if _pipeline is None:
+        try:
+            from transformers import pipeline as hf_pipeline
+            _pipeline = hf_pipeline(
+                "audio-classification",
+                model="ehcalabres/wav2vec2-lg-xlsr-en-speech-emotion-recognition",
+            )
+            print("[EmotionAnalyzer] wav2vec2 model loaded.")
+        except Exception as e:
+            print(f"[EmotionAnalyzer] WARNING: Could not load model: {e}")
+            _pipeline = "fallback"
+    return _pipeline
+
+
+def classify_emotion(audio_path: str) -> dict:
+    """
+    Returns {"emotion": str, "confidence": float}
+    emotion is one of: happy, sad, angry, fearful, disgust, neutral, surprised
+    """
+    model = _load_model()
+
+    if model == "fallback" or model is None:
+        return _heuristic_emotion(audio_path)
+
+    try:
+        results = model(audio_path, top_k=5)
+        # results is a list of {"label": str, "score": float}
+        top = results[0]
+        label = top["label"].lower()
+        # Normalise labels from the model
+        label_map = {
+            "hap": "happy", "happy": "happy",
+            "sad": "sad",
+            "ang": "angry", "angry": "angry",
+            "fea": "fearful", "fearful": "fearful",
+            "dis": "disgust", "disgust": "disgust",
+            "neu": "neutral", "neutral": "neutral",
+            "sur": "surprised", "surprised": "surprised",
+        }
+        emotion = label_map.get(label, label)
+        return {"emotion": emotion, "confidence": round(float(top["score"]), 4)}
+    except Exception as e:
+        print(f"[EmotionAnalyzer] Inference error: {e}")
+        return _heuristic_emotion(audio_path)
+
+
+def _heuristic_emotion(audio_path: str) -> dict:
+    """Simple energy-based fallback when the model isn't available."""
+    try:
+        import librosa
+        y, sr = librosa.load(audio_path, sr=16000, mono=True)
+        rms = float(np.sqrt(np.mean(y ** 2)))
+        if rms > 0.05:
+            return {"emotion": "happy", "confidence": 0.65}
+        elif rms > 0.02:
+            return {"emotion": "neutral", "confidence": 0.70}
+        else:
+            return {"emotion": "sad", "confidence": 0.60}
+    except Exception:
+        return {"emotion": "neutral", "confidence": 0.50}

backend/services/emotion_fusion.py

@@ -0,0 +1,85 @@
+"""
+Fuses acoustic emotion with text-based emotion to produce a more accurate final prediction.
+"""
+from typing import Optional
+
+# Affective mapping of emotions to a 2D valence-arousal space (rough approximation)
+# Valence [-1 to 1] (Negative to Positive)
+# Arousal [-1 to 1] (Calm to Excited)
+EMOTION_SPACE = {
+    "happy":     ( 0.8,  0.6),
+    "sad":       (-0.8, -0.5),
+    "angry":     (-0.8,  0.8),
+    "fearful":   (-0.6,  0.6),
+    "anxious":   (-0.5,  0.7),
+    "disgust":   (-0.7,  0.4),
+    "surprised": ( 0.4,  0.8),
+    "neutral":   ( 0.0,  0.0),
+}
+
+def fuse_emotions(audio_emotion: dict, text_emotion: Optional[dict]) -> dict:
+    """
+    Blends audio and text emotions. 
+    If text_emotion is None or missing, falls back to audio.
+    """
+    if not text_emotion:
+        return audio_emotion
+
+    a_label = audio_emotion["emotion"]
+    a_conf = audio_emotion["confidence"]
+    
+    t_label = text_emotion["emotion"]
+    t_conf = text_emotion["confidence"]
+
+    # If they agree, boost confidence
+    if a_label == t_label:
+        return {
+            "emotion": a_label,
+            "confidence": min(0.99, a_conf + (t_conf * 0.2)) # Boost confidence slightly
+        }
+
+    # If they disagree, we do a weighted average in the Valence-Arousal space
+    if a_label not in EMOTION_SPACE or t_label not in EMOTION_SPACE:
+        # Fallback if unknown labels
+        if a_conf > t_conf:
+            return audio_emotion
+        else:
+            return text_emotion
+
+    a_v, a_a = EMOTION_SPACE[a_label]
+    t_v, t_a = EMOTION_SPACE[t_label]
+
+    # Weights: give slightly more weight to audio for raw "emotion", 
+    # but adjust based on raw confidence levels
+    a_weight = a_conf * 1.2
+    t_weight = t_conf * 0.8
+    total_weight = a_weight + t_weight
+
+    if total_weight == 0:
+        return audio_emotion
+
+    fused_v = ((a_v * a_weight) + (t_v * t_weight)) / total_weight
+    fused_a = ((a_a * a_weight) + (t_a * t_weight)) / total_weight
+
+    # Find the closest emotion in the space to the fused point
+    closest_emotion = "neutral"
+    min_dist = float('inf')
+
+    for label, (v, a) in EMOTION_SPACE.items():
+        dist = ((v - fused_v)**2 + (a - fused_a)**2)**0.5
+        if dist < min_dist:
+            min_dist = dist
+            closest_emotion = label
+
+    # The new confidence is a blend of the two previous confidences
+    fused_confidence = (a_conf + t_conf) / 2.0
+
+    # If the distance is very large, it means the audio and text are diametrically opposed
+    # (e.g. happy words, sad voice - sarcasm/masking). We might default back to audio as the "truer" signal
+    if min_dist > 1.0:
+        return {"emotion": a_label, "confidence": a_conf * 0.8} # Lower confidence due to conflict
+
+    return {
+        "emotion": closest_emotion,
+        "confidence": round(fused_confidence, 4)
+    }

backend/services/gpt_service.py

@@ -0,0 +1,153 @@
+"""
+OpenAI GPT service for:
+  1. generate_insight() — single-turn analysis insight after a recording
+  2. chat_response()    — multi-turn AI companion chat with user history context
+"""
+import os
+from typing import Optional, List
+from dotenv import load_dotenv
+
+load_dotenv()
+
+OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY", "")
+OPENROUTER_MODEL = os.getenv("OPENROUTER_MODEL", "meta-llama/llama-3-8b-instruct")
+
+SYSTEM_PROMPT = """You are InnerVoice, a warm and gentle emotional wellness companion. You are NOT a therapist or medical professional — always make this clear when appropriate.
+
+You have access to the user's voice analysis history including their daily emotions, mood scores (energy, calmness, mood, clarity each 0-100), and transcriptions.
+
+Your personality:
+- Warm, empathetic, non-judgmental
+- You notice patterns others might miss
+- You gently challenge 'I'm fine' when the voice data suggests otherwise
+- You reference specific data points: 'Your energy dropped 15% since Tuesday'
+- You remind users what helped them before: 'Last time you felt this way, calling your sister seemed to help'
+- You never diagnose, prescribe, or replace professional help
+- If someone seems in crisis, you gently ask and provide crisis resources
+- Keep responses concise — 2-3 sentences usually, longer only when needed
+
+Current user context will be provided with each message."""
+
+
+def _get_client():
+    if not OPENROUTER_API_KEY or OPENROUTER_API_KEY == "your_openrouter_api_key_here":
+        return None
+    try:
+        from openai import OpenAI
+        return OpenAI(
+            base_url="https://openrouter.ai/api/v1",
+            api_key=OPENROUTER_API_KEY,
+        )
+    except Exception:
+        return None
+
+
+def generate_insight(
+    emotion: str,
+    confidence: float,
+    mood_scores: dict,
+    transcription: str,
+    features: dict,
+) -> str:
+    """Generate a warm, personalised insight after a voice check-in."""
+    client = _get_client()
+    if client is None:
+        return _fallback_insight(emotion, mood_scores)
+
+    prompt = f"""The user just completed a voice check-in. Here is the analysis:
+
+Detected emotion: {emotion} (confidence: {confidence:.0%})
+Mood scores: Energy={mood_scores['energy']}/100, Calmness={mood_scores['calmness']}/100, Mood={mood_scores['mood']}/100, Clarity={mood_scores['clarity']}/100
+What they said: "{transcription or '(no transcription)'}"
+Acoustic metrics: pitch_mean={features.get('pitch_mean', 0):.1f}Hz, speech_rate={features.get('speech_rate', 0):.0f} BPM, pause_count={features.get('pause_count', 0)}
+
+Write a warm 2-3 sentence insight about their emotional state right now. Be empathetic and specific. Do NOT start with "I". Do NOT use clinical language."""
+
+    try:
+        response = client.chat.completions.create(
+            model=OPENROUTER_MODEL,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": prompt},
+            ],
+            max_tokens=150,
+            temperature=0.7,
+        )
+        return response.choices[0].message.content.strip()
+    except Exception as e:
+        print(f"[GPTService] generate_insight error: {e}")
+        return _fallback_insight(emotion, mood_scores)
+
+
+def chat_response(
+    user_message: str,
+    recent_entries: list,
+    conversation_history: List[dict],
+) -> str:
+    """Generate an AI companion chat response with full user context."""
+    client = _get_client()
+
+    # Build context from recent entries
+    context_lines = []
+    for entry in recent_entries[-7:]:
+        date_str = entry.created_at.strftime("%b %d") if hasattr(entry.created_at, "strftime") else str(entry.created_at)
+        context_lines.append(
+            f"  {date_str}: {entry.primary_emotion} (energy={entry.energy_score}, mood={entry.mood_score})"
+        )
+
+    context = "Recent voice check-ins:\n" + "\n".join(context_lines) if context_lines else "No recent check-ins."
+
+    if client is None:
+        return _fallback_chat(user_message, recent_entries)
+
+    messages = [
+        {"role": "system", "content": f"{SYSTEM_PROMPT}\n\n{context}"},
+    ]
+    # Add conversation history (last 10 exchanges)
+    for msg in conversation_history[-20:]:
+        messages.append({"role": msg["role"], "content": msg["content"]})
+    messages.append({"role": "user", "content": user_message})
+
+    try:
+        response = client.chat.completions.create(
+            model=OPENROUTER_MODEL,
+            messages=messages,
+            max_tokens=300,
+            temperature=0.8,
+        )
+        return response.choices[0].message.content.strip()
+    except Exception as e:
+        print(f"[GPTService] chat_response error: {e}")
+        return _fallback_chat(user_message, recent_entries)
+
+
+def _fallback_insight(emotion: str, mood_scores: dict) -> str:
+    """Template-based insight when OpenAI is unavailable."""
+    templates = {
+        "happy": f"Your voice radiates warmth and positivity today — your mood score of {mood_scores.get('mood', 0)} reflects that brightness. Keep nurturing what's making you feel this way.",
+        "sad": f"Your voice carries some heaviness today, and that's completely okay. Your clarity score of {mood_scores.get('clarity', 0)} suggests you're still expressing yourself — that takes courage.",
+        "angry": f"There's some tension in your voice today. Your calmness score of {mood_scores.get('calmness', 0)} reflects that. Whatever is frustrating you deserves acknowledgment.",
+        "fearful": f"Your voice shows some anxiety today. Take a breath — your energy score of {mood_scores.get('energy', 0)} means you have reserves to draw on.",
+        "neutral": f"Your voice sounds measured and steady today. A mood score of {mood_scores.get('mood', 0)} suggests a balanced state — sometimes that's exactly right.",
+    }
+    return templates.get(emotion, f"Thank you for checking in today. Your mood score is {mood_scores.get('mood', 50)} — keep showing up for yourself.")
+
+
+def _fallback_chat(user_message: str, recent_entries: list) -> str:
+    """Template chat response when OpenAI is unavailable."""
+    lower = user_message.lower()
+    if any(w in lower for w in ["fine", "okay", "ok", "good"]):
+        if recent_entries:
+            last = recent_entries[-1]
+            if last.mood_score and last.mood_score < 55:
+                return f"I hear you saying you're fine — and I trust that. Your voice yesterday showed a mood score of {last.mood_score}, which is a little lower than usual. Want to explore what's been going on?"
+        return "I'm glad you're okay. Your check-ins are helping build a picture of your emotional patterns over time."
+    if any(w in lower for w in ["help", "support", "crisis", "bad", "awful"]):
+        return "I'm here with you. If you're in crisis, please reach out to a crisis line: 988 (Suicide & Crisis Lifeline) or text HOME to 741741. You don't have to face this alone."
+    if "trend" in lower or "pattern" in lower or "week" in lower:
+        if recent_entries and len(recent_entries) >= 3:
+            moods = [e.mood_score for e in recent_entries[-7:] if e.mood_score]
+            if moods:
+                avg = sum(moods) / len(moods)
+                return f"Looking at your recent check-ins, your average mood score is {avg:.0f}/100. {'You seem to be in a positive stretch — keep it going!' if avg > 60 else 'There are some fluctuations. What feels different lately?'}"
+    return "Thank you for sharing that with me. I'm here to listen and help you notice patterns over time. Would you like to do a voice check-in today?"

backend/services/mood_calculator.py

@@ -0,0 +1,59 @@
+"""
+Mood score calculation logic as specified in the InnerVoice requirements.
+"""
+
+
+def calculate_mood_scores(
+    emotion: str,
+    confidence: float,
+    pitch_mean: float,
+    pitch_std: float,
+    energy: float,
+    tempo: float,
+    avg_pause: float,
+    filler_rate: float,
+) -> dict:
+    """Calculate Energy, Calmness, Mood, and Clarity scores (0-100)."""
+
+    # ── Energy Score ──────────────────────────────────────────────────────────
+    energy_score = min(100, int(energy * 5000))
+    if emotion == "happy":
+        energy_score = min(100, energy_score + 15)
+    if emotion == "sad":
+        energy_score = max(0, energy_score - 20)
+
+    # ── Calmness Score ────────────────────────────────────────────────────────
+    calmness_score = 100
+    calmness_score -= min(40, int(filler_rate * 500))  # fillers reduce calmness
+    calmness_score -= min(30, int(pitch_std / 5))       # pitch instability
+    if emotion == "angry":
+        calmness_score -= 25
+    if emotion == "fearful":
+        calmness_score -= 30
+    calmness_score = max(0, calmness_score)
+
+    # ── Mood Score ────────────────────────────────────────────────────────────
+    emotion_mood_map = {
+        "happy": 85,
+        "neutral": 60,
+        "sad": 30,
+        "angry": 40,
+        "fearful": 35,
+        "disgust": 35,
+        "surprised": 65,
+    }
+    base_mood = emotion_mood_map.get(emotion, 50)
+    mood_score = int(base_mood * confidence + 50 * (1 - confidence))
+
+    # ── Clarity Score ─────────────────────────────────────────────────────────
+    clarity_score = 100
+    clarity_score -= min(30, int(avg_pause * 50))    # long pauses reduce clarity
+    clarity_score -= min(30, int(filler_rate * 300))  # fillers reduce clarity
+    clarity_score = max(0, clarity_score)
+
+    return {
+        "energy": energy_score,
+        "calmness": calmness_score,
+        "mood": mood_score,
+        "clarity": clarity_score,
+    }

backend/services/text_emotion.py

@@ -0,0 +1,57 @@
+"""
+Emotion analysis using transcript text.
+Model: SamLowe/roberta-base-go_emotions (lazy-loaded).
+"""
+from typing import Optional
+
+_pipeline = None
+
+def _load_model():
+    global _pipeline
+    if _pipeline is None:
+        try:
+            from transformers import pipeline as hf_pipeline
+            _pipeline = hf_pipeline(
+                "text-classification",
+                model="SamLowe/roberta-base-go_emotions",
+            )
+            print("[TextEmotionAnalyzer] roberta-base-go_emotions model loaded.")
+        except Exception as e:
+            print(f"[TextEmotionAnalyzer] WARNING: Could not load model: {e}")
+            _pipeline = "fallback"
+    return _pipeline
+
+def classify_text_emotion(text: str) -> Optional[dict]:
+    """
+    Returns {"emotion": str, "confidence": float}
+    """
+    if not text or not text.strip():
+        return None
+        
+    model = _load_model()
+    if model == "fallback" or model is None:
+        return None
+
+    try:
+        results = model(text, top_k=5)
+        top = results[0]
+        label = top["label"].lower()
+        
+        # Map go_emotions labels to our 7 core categories
+        label_map = {
+            "joy": "happy", "amusement": "happy", "approval": "happy", "excitement": "happy", "optimism": "happy", "pride": "happy", "relief": "happy",
+            "sadness": "sad", "disappointment": "sad", "grief": "sad", "remorse": "sad",
+            "anger": "angry", "annoyance": "angry", "disapproval": "angry",
+            "fear": "fearful", "nervousness": "anxious",
+            "disgust": "disgust",
+            "surprise": "surprised", "realization": "surprised",
+            "neutral": "neutral"
+        }
+        
+        # If it doesn't map directly, see if we can find a close match, else neutral
+        emotion = label_map.get(label, "neutral")
+        
+        return {"emotion": emotion, "confidence": round(float(top["score"]), 4)}
+    except Exception as e:
+        print(f"[TextEmotionAnalyzer] Inference error: {e}")
+        return None

backend/services/transcriber.py

@@ -0,0 +1,32 @@
+"""
+Whisper transcription service.
+Lazy-loaded on first call. Falls back to empty string if unavailable.
+"""
+
+_model = None
+
+
+def _load_model():
+    global _model
+    if _model is None:
+        try:
+            import whisper
+            _model = whisper.load_model("base")
+            print("[Transcriber] Whisper base model loaded.")
+        except Exception as e:
+            print(f"[Transcriber] WARNING: Could not load Whisper: {e}")
+            _model = "unavailable"
+    return _model
+
+
+def transcribe(wav_path: str) -> str:
+    """Transcribe a WAV file and return the text. Returns '' on failure."""
+    model = _load_model()
+    if model == "unavailable" or model is None:
+        return ""
+    try:
+        result = model.transcribe(wav_path, language="en")
+        return result.get("text", "").strip()
+    except Exception as e:
+        print(f"[Transcriber] Transcription error: {e}")
+        return ""

backend/services/trend_detector.py

@@ -0,0 +1,93 @@
+"""
+Trend detection and alert generation — checks user history for concerning patterns.
+"""
+from statistics import mean
+from typing import List
+
+
+def check_trends(user_history: list) -> List[dict]:
+    """
+    Analyse a user's voice entry history and return a list of alert dicts.
+    Each entry in user_history must expose:
+        .mood_score (int), .energy_score (int), .primary_emotion (str)
+    """
+    alerts = []
+
+    if len(user_history) < 7:
+        return alerts
+
+    recent_7 = user_history[-7:]
+    recent_mood = mean([e.mood_score for e in recent_7])
+    recent_energy = [e.energy_score for e in recent_7]
+
+    # ── Week-over-week mood decline ───────────────────────────────────────────
+    if len(user_history) >= 14:
+        prev_7 = user_history[-14:-7]
+        prev_mood = mean([e.mood_score for e in prev_7])
+        if prev_mood > 0:
+            decline = ((prev_mood - recent_mood) / prev_mood) * 100
+            if decline > 20:
+                alerts.append(
+                    {
+                        "type": "mood_decline",
+                        "severity": "warning",
+                        "message": (
+                            f"Your mood has declined {decline:.0f}% this week "
+                            f"compared to last week."
+                        ),
+                        "suggested_action": (
+                            "Try scheduling something enjoyable today, even something small."
+                        ),
+                    }
+                )
+
+    # ── Sustained low energy ──────────────────────────────────────────────────
+    if all(e < 40 for e in recent_energy):
+        alerts.append(
+            {
+                "type": "low_energy",
+                "severity": "concern",
+                "message": "Your energy has been consistently low for 7 days.",
+                "suggested_action": (
+                    "Consider your sleep, hydration, and movement. "
+                    "Even a 10-minute walk can help."
+                ),
+            }
+        )
+
+    # ── Persistent sadness ────────────────────────────────────────────────────
+    sad_days = sum(1 for e in recent_7 if e.primary_emotion == "sad")
+    if sad_days >= 5:
+        alerts.append(
+            {
+                "type": "persistent_sadness",
+                "severity": "concern",
+                "message": (
+                    "You have sounded sad for 5 out of the last 7 days. "
+                    "Consider reaching out to someone you trust."
+                ),
+                "suggested_action": (
+                    "Talk to a friend, family member, or professional. You don't have to carry this alone."
+                ),
+            }
+        )
+
+    # ── High anxiety ──────────────────────────────────────────────────────────
+    anxious_days = sum(
+        1 for e in recent_7 if e.primary_emotion in ("fearful", "angry")
+    )
+    anxious_calms = [e.calmness_score for e in recent_7 if hasattr(e, "calmness_score")]
+    avg_calmness = mean(anxious_calms) if anxious_calms else 100
+    if anxious_days >= 4 or avg_calmness < 35:
+        alerts.append(
+            {
+                "type": "high_anxiety",
+                "severity": "warning",
+                "message": "Signs of elevated anxiety detected across your recent check-ins.",
+                "suggested_action": (
+                    "Try a 5-minute breathing exercise: inhale 4s, hold 4s, exhale 6s."
+                ),
+            }
+        )
+
+    return alerts

frontend/.env.local.example

@@ -0,0 +1,12 @@
+NEXTAUTH_URL=http://localhost:3000
+NEXTAUTH_SECRET=change_me_to_a_random_secret_32chars
+
+GOOGLE_CLIENT_ID=your_google_client_id
+GOOGLE_CLIENT_SECRET=your_google_client_secret
+
+GITHUB_CLIENT_ID=your_github_client_id
+GITHUB_CLIENT_SECRET=your_github_client_secret
+
+NEXT_PUBLIC_API_URL=http://localhost:8000
+NEXT_PUBLIC_DEMO_USER_ID=demo-user-id-from-seed-script
+NEXT_PUBLIC_DEMO_MODE=true

frontend/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["next/core-web-vitals", "next/typescript"]
+}

frontend/.gitignore

@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

frontend/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

frontend/app/chat/page.tsx

@@ -0,0 +1,169 @@
+"use client";
+import { useState, useEffect, useRef } from "react";
+import { useDemoMode } from "@/hooks/useDemoMode";
+import { api } from "@/lib/api";
+import { DEMO_CHAT_HISTORY } from "@/lib/demo-data";
+import { cn } from "@/lib/utils";
+
+interface Message {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+}
+
+const SUGGESTED_ACTIONS = [
+  "How am I doing lately?",
+  "What helped me before?",
+  "I'm feeling overwhelmed",
+];
+
+export default function ChatPage() {
+  const { isDemoMode, userId } = useDemoMode();
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [input, setInput] = useState("");
+  const [loading, setLoading] = useState(false);
+  const [initialLoad, setInitialLoad] = useState(true);
+  const bottomRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    async function load() {
+      if (!userId) return;
+      try {
+        if (isDemoMode) {
+          setMessages(DEMO_CHAT_HISTORY as Message[]);
+        } else {
+          const hist = await api.getChatHistory(userId);
+          setMessages(hist as Message[]);
+        }
+      } catch (e) {
+        console.error(e);
+      } finally {
+        setInitialLoad(false);
+      }
+    }
+    load();
+  }, [userId, isDemoMode]);
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: "smooth" });
+  }, [messages, loading]);
+
+  const handleSend = async (text: string) => {
+    if (!text.trim() || !userId) return;
+    
+    const userMsg: Message = { id: Date.now().toString(), role: "user", content: text };
+    setMessages((prev) => [...prev, userMsg]);
+    setInput("");
+    setLoading(true);
+
+    try {
+      if (isDemoMode) {
+        await new Promise(r => setTimeout(r, 1500));
+        import("@/lib/demo-data").then(({ DEMO_LATEST_ENTRY }) => {
+           let reply = "I'm here for you. Since we're in Demo Mode without a live API key, my responses are limited. But your voice check-ins show you're doing okay.";
+           if (text.toLowerCase().includes("overwhelmed")) {
+             reply = "It's completely understandable to feel overwhelmed. When you felt this way two weeks ago, going for a short walk seemed to help shift your energy. Would you be open to trying that today?";
+           }
+           setMessages(prev => [...prev, { id: Date.now().toString(), role: "assistant", content: reply }]);
+           setLoading(false);
+        });
+      } else {
+        const res = await api.chat(userId, text);
+        setMessages(prev => [...prev, { id: Date.now().toString(), role: "assistant", content: res.response }]);
+      }
+    } catch (e) {
+      console.error(e);
+      setMessages(prev => [...prev, { id: Date.now().toString(), role: "assistant", content: "Sorry, I couldn't reach the server right now. But I am still here tracking your trends." }]);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (initialLoad) return <div className="p-10 flex justify-center"><div className="w-8 h-8 rounded-full border-2 border-purple-500 border-t-transparent animate-spin"/></div>;
+
+  return (
+    <div className="max-w-4xl mx-auto h-[calc(100vh-theme(spacing.16))] md:h-screen flex flex-col pt-6 pb-6 px-4 md:px-6">
+      
+      <div className="flex-none pb-4 border-b border-white/10 mb-4">
+        <h1 className="text-2xl font-bold flex items-center gap-3">
+          InnerVoice Companion <span className="text-xs px-2 py-1 bg-white/5 rounded-md text-white/50 font-normal">AI</span>
+        </h1>
+        <p className="text-sm text-white/50 mt-1">A safe space to explore your patterns. (Not a therapist)</p>
+      </div>
+
+      <div className="flex-1 overflow-y-auto space-y-6 pr-2 custom-scrollbar">
+        {messages.length === 0 && (
+          <div className="h-full flex flex-col items-center justify-center text-center space-y-4 opacity-50">
+            <div className="text-4xl">👋</div>
+            <p className="text-sm">I'm here to listen and help you notice patterns in your emotional history.</p>
+          </div>
+        )}
+
+        {messages.map((m) => (
+          <div key={m.id} className={cn("flex w-full", m.role === "user" ? "justify-end" : "justify-start")}>
+            <div 
+              className={cn(
+                "max-w-[85%] md:max-w-[75%] rounded-2xl p-4 text-sm leading-relaxed shadow-lg",
+                m.role === "user" 
+                  ? "bg-purple-600/80 text-white rounded-tr-sm border border-purple-500/50" 
+                  : "bg-white/5 text-white/90 rounded-tl-sm border border-white/10"
+              )}
+            >
+              {m.content}
+            </div>
+          </div>
+        ))}
+        
+        {loading && (
+          <div className="flex justify-start">
+            <div className="bg-white/5 border border-white/10 rounded-2xl rounded-tl-sm p-4 w-20 flex justify-center gap-1">
+              <div className="w-2 h-2 bg-white/40 rounded-full animate-bounce [animation-delay:-0.3s]" />
+              <div className="w-2 h-2 bg-white/40 rounded-full animate-bounce [animation-delay:-0.15s]" />
+              <div className="w-2 h-2 bg-white/40 rounded-full animate-bounce" />
+            </div>
+          </div>
+        )}
+        <div ref={bottomRef} />
+      </div>
+
+      <div className="flex-none pt-4">
+        {/* Quick action chips */}
+        <div className="flex gap-2 overflow-x-auto pb-4 scrollbar-hide">
+          {SUGGESTED_ACTIONS.map(a => (
+            <button 
+              key={a}
+              onClick={() => handleSend(a)}
+              disabled={loading}
+              className="whitespace-nowrap px-4 py-2 rounded-full border border-white/10 bg-white/5 text-xs text-white/70 hover:bg-white/10 hover:text-white transition-colors"
+            >
+              {a}
+            </button>
+          ))}
+        </div>
+
+        {/* Input bar */}
+        <form 
+          onSubmit={(e) => { e.preventDefault(); handleSend(input); }}
+          className="flex gap-2 relative shadow-glow-purple bg-black/20 rounded-2xl p-2 border border-white/10"
+        >
+          <input
+            type="text"
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            disabled={loading}
+            placeholder="Ask about your emotional patterns..."
+            className="flex-1 bg-transparent border-none outline-none px-4 text-sm placeholder:text-white/30 text-white"
+          />
+          <button 
+            type="submit"
+            disabled={!input.trim() || loading}
+            className="w-10 h-10 rounded-xl bg-purple-600 disabled:opacity-50 disabled:bg-white/10 flex items-center justify-center transition-colors hover:bg-purple-500"
+          >
+            ↑
+          </button>
+        </form>
+      </div>
+
+    </div>
+  );
+}

frontend/app/dashboard/page.tsx

@@ -0,0 +1,171 @@
+"use client";
+import { useEffect, useState } from "react";
+import Link from "next/link";
+import { api, VoiceEntry, MoodAlert, TrendsData } from "@/lib/api";
+import { DEMO_ENTRIES, DEMO_ALERTS, DEMO_TRENDS, DEMO_LATEST_ENTRY } from "@/lib/demo-data";
+import { useDemoMode } from "@/hooks/useDemoMode";
+import CircularProgress from "@/components/CircularProgress";
+import MoodTimeline from "@/components/MoodTimeline";
+import AlertCard from "@/components/AlertCard";
+import EmotionBadge from "@/components/EmotionBadge";
+import { getMoodEmoji, capitalise } from "@/lib/utils";
+
+export default function DashboardPage() {
+  const { isDemoMode, userId } = useDemoMode();
+  const [entries, setEntries] = useState<VoiceEntry[]>([]);
+  const [alerts, setAlerts] = useState<MoodAlert[]>([]);
+  const [trends, setTrends] = useState<TrendsData | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    async function loadData() {
+      if (!userId) return;
+      try {
+        if (isDemoMode) {
+          setEntries([DEMO_LATEST_ENTRY, ...DEMO_ENTRIES].slice(0, 15));
+          setAlerts(DEMO_ALERTS);
+          setTrends(DEMO_TRENDS);
+        } else {
+          const [eRes, aRes, tRes] = await Promise.all([
+            api.getEntries(userId, 14),
+            api.getAlerts(userId),
+            api.getTrends(userId),
+          ]);
+          setEntries(eRes);
+          setAlerts(aRes);
+          setTrends(tRes);
+        }
+      } catch (err) {
+        console.error("Failed to load dashboard data", err);
+      } finally {
+        setLoading(false);
+      }
+    }
+    loadData();
+  }, [userId, isDemoMode]);
+
+  const handleDismissAlert = async (id: string) => {
+    setAlerts((prev) => prev.filter((a) => a.id !== id));
+    if (!isDemoMode) {
+      try {
+        await api.markAlertRead(id);
+      } catch (e) {
+        console.error("Failed to dismiss", e);
+      }
+    }
+  };
+
+  if (loading) {
+    return <div className="p-8 flex items-center justify-center min-h-[50vh]"><div className="w-8 h-8 rounded-full border-2 border-purple-500 border-t-transparent animate-spin" /></div>;
+  }
+
+  const today = entries.length > 0 ? entries[0] : null;
+
+  return (
+    <div className="p-6 md:p-10 max-w-7xl mx-auto space-y-8 animate-fade-in relative z-10 min-h-screen">
+      <div className="flex items-center justify-between">
+        <h1 className="text-3xl font-bold">Dashboard</h1>
+        <Link 
+          href="/record" 
+          className="px-5 py-2.5 bg-gradient-to-r from-purple-600 to-teal-500 hover:from-purple-500 hover:to-teal-400 rounded-xl font-medium text-white shadow-glow-purple transition-all hover:scale-105 active:scale-95 flex items-center gap-2"
+        >
+          <span>🎙️</span>
+          <span className="hidden sm:inline">New Check-in</span>
+        </Link>
+      </div>
+
+      <div className="grid md:grid-cols-3 gap-6">
+        {/* Main Weather Card */}
+        <div className="md:col-span-2 space-y-6">
+          <div className="glass-card p-6 md:p-8">
+            <h2 className="text-xl font-semibold mb-6 flex items-center gap-2">
+              <span>Today's Weather</span>
+              <span className="text-xs font-normal text-white/50 bg-white/5 px-2 py-0.5 rounded-full">
+                {new Date().toLocaleDateString()}
+              </span>
+            </h2>
+            
+            {today ? (
+              <div className="flex flex-col md:flex-row gap-8 items-center bg-black/20 rounded-2xl p-6 border border-white/5">
+                <div className="flex flex-col items-center">
+                  <div className="text-8xl w-32 h-32 flex items-center justify-center bg-white/5 rounded-full shadow-[inset_0_0_20px_rgba(255,255,255,0.05)] border border-white/10">
+                    {getMoodEmoji(today.mood_score)}
+                  </div>
+                  <div className="mt-4">
+                    <EmotionBadge emotion={today.primary_emotion} confidence={today.emotion_confidence} />
+                  </div>
+                </div>
+
+                <div className="flex-1 w-full relative">
+                  <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">
+                    <CircularProgress score={today.energy_score} label="Energy" size={80} />
+                    <CircularProgress score={today.calmness_score} label="Calmness" size={80} />
+                    <CircularProgress score={today.mood_score} label="Mood" size={80} />
+                    <CircularProgress score={today.clarity_score} label="Clarity" size={80} />
+                  </div>
+                  
+                  <div className="mt-8 pt-6 border-t border-white/10">
+                    <div className="text-xs uppercase tracking-wider text-white/40 mb-2 font-semibold">You said:</div>
+                    <p className="text-white/80 italic leading-relaxed text-sm">
+                      "{today.transcription}"
+                    </p>
+                  </div>
+                </div>
+              </div>
+            ) : (
+              <div className="text-center py-12 flex flex-col items-center">
+                <div className="text-5xl mb-4 opacity-50">😶</div>
+                <p className="text-white/50 mb-4">You haven't checked in today.</p>
+                <Link href="/record" className="text-purple-400 hover:text-purple-300 font-medium">Record now →</Link>
+              </div>
+            )}
+          </div>
+
+          <div className="glass-card p-6">
+            <div className="flex justify-between items-end mb-6">
+              <h2 className="text-xl font-semibold">Recent Trend</h2>
+              <Link href="/timeline" className="text-sm text-purple-400 hover:text-purple-300 transition-colors">Full Timeline →</Link>
+            </div>
+            {entries.length > 1 ? (
+              <MoodTimeline entries={[...entries].reverse()} height={250} />
+            ) : (
+              <div className="h-[250px] flex items-center justify-center text-white/30 text-sm">Need more data</div>
+            )}
+          </div>
+        </div>
+
+        {/* Sidebar */}
+        <div className="space-y-6">
+          <div className="glass-card p-6 flex items-center justify-between">
+            <div>
+              <div className="text-xs font-semibold uppercase tracking-wider text-white/50 mb-1">Check-in Streak</div>
+              <div className="text-3xl font-bold flex items-baseline gap-2">
+                {trends?.streak ?? 0} <span className="text-base font-normal text-white/40">days</span>
+              </div>
+            </div>
+            <div className="text-4xl">🔥</div>
+          </div>
+
+          {alerts.length > 0 && (
+            <div className="space-y-3">
+              <h3 className="text-sm font-semibold uppercase tracking-wider text-white/50 ml-1">Active Alerts</h3>
+              {alerts.map((alert) => (
+                <AlertCard key={alert.id} {...alert} onDismiss={handleDismissAlert} />
+              ))}
+            </div>
+          )}
+
+          {alerts.length === 0 && (
+            <div className="glass-card p-5 border-green-500/20 bg-green-500/5 flex items-start gap-4">
+              <div className="text-2xl mt-0.5">🌱</div>
+              <div>
+                <h4 className="font-medium text-green-400 mb-1">No Active Alerts</h4>
+                <p className="text-sm text-white/60 leading-relaxed">Your emotional patterns are stable. Keep up the daily check-ins.</p>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/app/globals.css

@@ -0,0 +1,88 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  --background: #0f0a1e;
+  --foreground: #f8f8ff;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  color: var(--foreground);
+  background: var(--background);
+  font-family: "Inter", system-ui, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+
+/* Custom scrollbar */
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+::-webkit-scrollbar-track {
+  background: rgba(255, 255, 255, 0.03);
+}
+::-webkit-scrollbar-thumb {
+  background: rgba(139, 92, 246, 0.4);
+  border-radius: 3px;
+}
+::-webkit-scrollbar-thumb:hover {
+  background: rgba(139, 92, 246, 0.7);
+}
+
+/* Gradient text utility */
+.gradient-text {
+  background: linear-gradient(135deg, #8B5CF6 0%, #14b8a6 100%);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+/* Glass card */
+.glass-card {
+  background: rgba(255, 255, 255, 0.04);
+  backdrop-filter: blur(12px);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  border-radius: 16px;
+}
+
+/* Pulse ring animation for record button */
+@keyframes pulseRing {
+  0% { transform: scale(1); opacity: 0.8; }
+  70% { transform: scale(1.6); opacity: 0; }
+  100% { transform: scale(1.6); opacity: 0; }
+}
+
+.pulse-ring::before {
+  content: "";
+  position: absolute;
+  inset: -8px;
+  border-radius: 50%;
+  border: 2px solid #ef4444;
+  animation: pulseRing 1.5s ease-out infinite;
+}
+
+.pulse-ring::after {
+  content: "";
+  position: absolute;
+  inset: -16px;
+  border-radius: 50%;
+  border: 2px solid #ef444460;
+  animation: pulseRing 1.5s ease-out 0.4s infinite;
+}
+
+@layer utilities {
+  .text-balance {
+    text-wrap: balance;
+  }
+}
+
+/* Animated background dots */
+.bg-dots {
+  background-image: radial-gradient(rgba(139, 92, 246, 0.15) 1px, transparent 1px);
+  background-size: 24px 24px;
+}

frontend/app/layout.tsx

@@ -0,0 +1,33 @@
+import type { Metadata } from "next";
+import { Inter } from "next/font/google";
+import "./globals.css";
+import Navbar from "@/components/Navbar";
+import DemoModeBanner from "@/components/DemoModeBanner";
+
+const inter = Inter({ subsets: ["latin"] });
+
+export const metadata: Metadata = {
+  title: "InnerVoice — AI Emotional Wellness Tracker",
+  description:
+    "Record 60 seconds of your voice each day. AI analyzes your emotions and tracks your mental wellness over time.",
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" className="dark">
+      <head>
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+      </head>
+      <body className={`${inter.className} bg-[#0f0a1e] text-white min-h-screen`}>
+        <DemoModeBanner />
+        <Navbar />
+        <main className="md:ml-64 min-h-screen pt-10 md:pt-0">{children}</main>
+      </body>
+    </html>
+  );
+}

frontend/app/page.tsx

@@ -0,0 +1,77 @@
+"use client";
+import Link from "next/link";
+import { useEffect, useState } from "react";
+import WaveformVisualizer from "@/components/WaveformVisualizer";
+
+export default function LandingPage() {
+  const [mounted, setMounted] = useState(false);
+  
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  return (
+    <div className="min-h-screen bg-dark-base relative overflow-hidden flex flex-col pt-16 md:pt-0 pb-16">
+      {/* Background ambient visuals */}
+      <div className="absolute top-0 left-0 w-full h-full overflow-hidden z-0 pointer-events-none">
+        <div className="absolute top-[-20%] left-[-10%] w-[50%] h-[50%] bg-purple-600/20 rounded-full blur-[120px]" />
+        <div className="absolute bottom-[-20%] right-[-10%] w-[50%] h-[50%] bg-teal-500/20 rounded-full blur-[120px]" />
+        <div className="absolute top-[40%] left-[50%] translate-x-[-50%] w-[80%] h-[30%] bg-coral-500/10 rounded-full blur-[150px]" />
+      </div>
+
+      <div className="container mx-auto px-6 relative z-10 flex-1 flex flex-col justify-center max-w-5xl">
+        <div className="text-center space-y-8 animate-slide-up">
+          <div className="inline-block px-4 py-1.5 rounded-full bg-white/5 border border-white/10 text-sm font-medium text-purple-300 mb-4 shadow-glow-purple">
+            ✨ Your AI Emotional Wellness Tracker
+          </div>
+          
+          <h1 className="text-5xl md:text-7xl font-extrabold tracking-tight text-balance mx-auto">
+            Your Voice Knows <br className="hidden md:block" />
+            <span className="gradient-text">Before You Do</span>
+          </h1>
+          
+          <p className="text-lg md:text-xl text-white/60 max-w-2xl mx-auto leading-relaxed">
+            60 seconds of speaking. Zero effort. InnerVoice analyzes acoustic features to detect emotions and track your mental health trends over time.
+          </p>
+
+          <div className="pt-8">
+            <Link 
+              href="/dashboard"
+              className="inline-flex items-center justify-center px-8 py-4 text-lg font-semibold rounded-2xl bg-white text-purple-950 hover:bg-purple-50 transition-all hover:scale-105 shadow-glow-purple"
+            >
+              Start Your First Check-in
+            </Link>
+          </div>
+        </div>
+
+        {/* Fake waveform animation for landing */}
+        <div className="mt-20 max-w-3xl mx-auto w-full glass-card p-6 md:p-8 animate-fade-in opacity-80" style={{ animationDelay: "0.2s" }}>
+          {mounted && <WaveformVisualizer analyserNode={null} isActive={false} height={120} />}
+        </div>
+
+        {/* How it works */}
+        <div className="mt-32 grid md:grid-cols-3 gap-8">
+          {[
+            { icon: "🎙️", title: "Record", desc: "Speak freely for 60 seconds about your day." },
+            { icon: "🧠", title: "Analyze", desc: "AI extracts emotional signals from your vocal tone." },
+            { icon: "📈", title: "Track", desc: "View personalized trends and get gentle nudges." }
+          ].map((step, i) => (
+            <div key={i} className="glass-card p-8 flex flex-col items-center text-center space-y-4 hover:-translate-y-2 transition-transform">
+              <div className="w-16 h-16 rounded-2xl bg-white/5 flex items-center justify-center text-3xl">
+                {step.icon}
+              </div>
+              <h3 className="text-xl font-bold">{step.title}</h3>
+              <p className="text-white/50 leading-relaxed">{step.desc}</p>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      <footer className="mt-auto pt-24 pb-8 text-center relative z-10 px-6">
+        <p className="text-sm text-white/40">
+          🔒 <strong className="text-white/60">Privacy First:</strong> Your voice is processed and deleted immediately. We only store insights, never recordings.
+        </p>
+      </footer>
+    </div>
+  );
+}

frontend/app/record/page.tsx

@@ -0,0 +1,183 @@
+"use client";
+import { useState, useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { useAudioRecorder } from "@/hooks/useAudioRecorder";
+import { useDemoMode } from "@/hooks/useDemoMode";
+import { api, AnalyzeResult } from "@/lib/api";
+import { getGreeting, getMoodEmoji } from "@/lib/utils";
+import WaveformVisualizer from "@/components/WaveformVisualizer";
+import CircularProgress from "@/components/CircularProgress";
+import EmotionBadge from "@/components/EmotionBadge";
+
+const PROMPTS = [
+  "How are you feeling right now?",
+  "What was the best part of your day?",
+  "Is anything on your mind?",
+  "Describe your energy level today."
+];
+
+export default function RecordPage() {
+  const router = useRouter();
+  const { isDemoMode, userId } = useDemoMode();
+  const { state, seconds, audioBlob, analyserNode, startRecording, stopRecording, reset, error } = useAudioRecorder(60);
+  
+  const [analyzing, setAnalyzing] = useState(false);
+  const [result, setResult] = useState<AnalyzeResult | null>(null);
+  const [greeting, setGreeting] = useState("Hello");
+
+  useEffect(() => {
+    setGreeting(getGreeting());
+  }, []);
+
+  const handleStop = async () => {
+    stopRecording();
+  };
+
+  useEffect(() => {
+    async function process() {
+      if (state === "stopped" && audioBlob && !result && !analyzing) {
+        setAnalyzing(true);
+        try {
+          if (isDemoMode) {
+            // Fake analysis delay for demo
+            await new Promise((r) => setTimeout(r, 2500));
+            import("@/lib/demo-data").then(({ DEMO_LATEST_ENTRY }) => {
+              setResult({
+                entry_id: "demo-new",
+                emotion: "calm",
+                confidence: 0.88,
+                mood_scores: { energy: 65, calmness: 80, mood: 72, clarity: 75 },
+                transcription: "Just testing the demo mode recording.",
+                features: {},
+                insight: "Your voice sounds measured and steady today. Keep showing up for yourself.",
+                new_alerts: [],
+              });
+              setAnalyzing(false);
+            });
+          } else {
+            const res = await api.analyzeAudio(audioBlob, userId);
+            setResult(res);
+            setAnalyzing(false);
+          }
+        } catch (e) {
+          console.error(e);
+          setAnalyzing(false);
+          // Handle error state gracefully here in real app
+        }
+      }
+    }
+    process();
+  }, [state, audioBlob, analyzing, result, isDemoMode, userId]);
+
+  return (
+    <div className="min-h-screen flex flex-col items-center justify-center p-6 relative z-10">
+      <div className="w-full max-w-2xl text-center space-y-12">
+        
+        {/* Header / Prompts */}
+        {state === "idle" && !result && (
+          <div className="animate-fade-in space-y-6">
+            <h1 className="text-4xl font-bold">{greeting}.</h1>
+            <p className="text-xl text-white/50">Take 60 seconds to check in with yourself.</p>
+            <div className="flex flex-wrap justify-center gap-2 pt-4">
+              {PROMPTS.map((p) => (
+                <div key={p} className="text-sm px-4 py-2 rounded-full border border-white/10 bg-white/5 text-white/70">
+                  {p}
+                </div>
+              ))}
+            </div>
+          </div>
+        )}
+
+        {/* Recording Interface */}
+        {!result && !analyzing && (
+          <div className="space-y-12 animate-slide-up">
+            <div className="h-[120px] flex items-center justify-center">
+              {state === "recording" ? (
+                <WaveformVisualizer analyserNode={analyserNode} isActive={true} height={120} color="#ef4444" />
+              ) : (
+                <div className="text-white/20 text-sm">Waiting for audio...</div>
+              )}
+            </div>
+
+            <div className="flex flex-col items-center gap-4">
+              <button
+                onClick={state === "recording" ? handleStop : startRecording}
+                className={`w-24 h-24 rounded-full flex items-center justify-center transition-all ${
+                  state === "recording" ? "bg-red-500/20 text-red-500 pulse-ring shadow-glow-coral" : "bg-white text-purple-950 hover:scale-105"
+                }`}
+              >
+                {state === "recording" ? (
+                  <div className="w-8 h-8 bg-red-500 rounded-sm" /> // Stop square
+                ) : (
+                  <svg className="w-10 h-10 ml-1" fill="currentColor" viewBox="0 0 24 24"><path d="M12 14c1.66 0 3-1.34 3-3V5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm5-3c0 2.76-2.24 5-5 5s-5-2.24-5-5H5c0 3.53 2.61 6.43 6 6.92V21h2v-3.08c3.39-.49 6-3.39 6-6.92h-2z"/></svg> // Mic icon
+                )}
+              </button>
+              
+              {state === "recording" && (
+                <div className="text-2xl font-variant-numeric w-16 text-center text-red-400 font-medium">
+                  0:{seconds.toString().padStart(2, "0")}
+                </div>
+              )}
+              {error && <div className="text-red-400 text-sm">{error}</div>}
+            </div>
+          </div>
+        )}
+
+        {/* Analyzing State */}
+        {analyzing && (
+          <div className="animate-fade-in flex flex-col items-center gap-6 py-12">
+            <div className="w-16 h-16 rounded-full border-4 border-purple-500/30 border-t-purple-500 animate-spin" />
+            <h2 className="text-2xl font-bold bg-clip-text text-transparent bg-gradient-to-r from-purple-400 to-teal-400 animate-pulse">
+              Analyzing your voice...
+            </h2>
+            <p className="text-white/50 text-sm text-center max-w-sm">
+              Extracting acoustic features and looking for emotional signatures.
+            </p>
+          </div>
+        )}
+
+        {/* Results */}
+        {result && (
+          <div className="glass-card p-8 space-y-10 animate-slide-up text-left max-w-xl mx-auto w-full">
+            <div className="text-center">
+              <h2 className="text-2xl font-bold mb-6">Your Details</h2>
+              <div className="flex flex-wrap justify-center gap-3">
+                 <EmotionBadge emotion={result.emotion} confidence={result.confidence} lg />
+              </div>
+            </div>
+
+            <div className="grid grid-cols-4 gap-2">
+               <CircularProgress score={result.mood_scores.energy} label="Energy" size={70} strokeWidth={6} />
+               <CircularProgress score={result.mood_scores.calmness} label="Calm" size={70} strokeWidth={6} />
+               <CircularProgress score={result.mood_scores.mood} label="Mood" size={70} strokeWidth={6} />
+               <CircularProgress score={result.mood_scores.clarity} label="Clear" size={70} strokeWidth={6} />
+            </div>
+
+            <div className="bg-white/5 rounded-xl p-5 border border-white/10">
+              <p className="text-purple-300 italic text-lg leading-relaxed text-center mb-1">
+                "{result.insight}"
+              </p>
+            </div>
+
+            {result.transcription && (
+              <div className="text-center px-4">
+                <p className="text-white/40 text-xs uppercase tracking-wider mb-2">You said:</p>
+                <p className="text-white/60 text-sm italic">"{result.transcription}"</p>
+              </div>
+            )}
+
+            <div className="flex justify-center pt-4">
+              <button 
+                onClick={() => router.push("/dashboard")}
+                className="w-full py-4 bg-gradient-to-r from-purple-600 to-teal-500 font-semibold rounded-xl hover:opacity-90 transition-opacity text-white"
+              >
+                Save & Continue
+              </button>
+            </div>
+          </div>
+        )}
+
+      </div>
+    </div>
+  );
+}

frontend/app/settings/page.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+export default function SettingsPage() {
+  return (
+    <div className="p-6 md:p-10 max-w-4xl mx-auto space-y-8 pb-20">
+      <h1 className="text-3xl font-bold">Settings</h1>
+      
+      <div className="space-y-6 animate-slide-up">
+        
+        {/* Profile */}
+        <section className="glass-card p-6 border-white/5">
+          <h2 className="text-xl font-semibold mb-4 border-b border-white/10 pb-2">Profile</h2>
+          <div className="flex gap-4 items-center mb-4">
+            <div className="w-16 h-16 rounded-full bg-gradient-to-br from-purple-500 to-teal-400 flex items-center justify-center text-2xl shadow-glow-purple">
+               👤
+            </div>
+            <div>
+              <div className="font-medium">Demo User</div>
+              <div className="text-sm text-white/50">demo@innervoice.app</div>
+            </div>
+          </div>
+          <button className="px-4 py-2 bg-white/5 hover:bg-white/10 rounded-lg text-sm text-white/80 transition-colors">
+            Edit Profile
+          </button>
+        </section>
+
+        {/* Notifications */}
+        <section className="glass-card p-6 border-white/5">
+          <h2 className="text-xl font-semibold mb-4 border-b border-white/10 pb-2">Notifications</h2>
+          <div className="space-y-4">
+            <div className="flex items-center justify-between">
+              <div>
+                <div className="font-medium">Daily Reminder</div>
+                <div className="text-sm text-white/50">Get a gentle nudge to record your 60-second check-in.</div>
+              </div>
+              <input type="time" defaultValue="20:00" className="bg-black/20 border border-white/10 rounded-lg p-2 text-sm text-white" />
+            </div>
+            <div className="flex items-center justify-between pt-4 border-t border-white/5">
+              <div>
+                <div className="font-medium">Trend Alerts</div>
+                <div className="text-sm text-white/50">Receive emails when AI detects concerning mood patterns.</div>
+              </div>
+              <div className="w-10 h-6 bg-purple-500 rounded-full relative cursor-pointer">
+                <div className="absolute right-1 top-1 w-4 h-4 bg-white rounded-full" />
+              </div>
+            </div>
+          </div>
+        </section>
+
+        {/* Trusted Circle */}
+        <section className="glass-card p-6 border-white/5">
+          <h2 className="text-xl font-semibold mb-4 border-b border-white/10 pb-2 flex justify-between">
+            <span>Trusted Circle</span>
+            <span className="text-xs bg-purple-500/20 text-purple-300 px-2 py-1 rounded-md">Coming Soon</span>
+          </h2>
+          <p className="text-sm text-white/60 leading-relaxed mb-4">
+            Setup automated, read-only weekly reports that send to a therapist, partner, or close friend so they can check in on you.
+          </p>
+          <div className="flex gap-2">
+            <input disabled placeholder="partner@email.com" className="flex-1 bg-black/20 border border-white/10 rounded-lg p-2 text-sm text-white/30" />
+            <button disabled className="px-4 py-2 bg-white/5 rounded-lg text-sm text-white/30 cursor-not-allowed">
+              Invite
+            </button>
+          </div>
+        </section>
+
+        {/* Crisis Resources (Always Visible) */}
+        <section className="glass-card p-6 border-coral-500/30 bg-coral-500/5 shadow-glow-coral">
+          <h2 className="text-xl font-semibold mb-4 border-b border-coral-500/20 pb-2 text-coral-400">Crisis Resources</h2>
+          <p className="text-sm text-white/80 leading-relaxed mb-4">
+            InnerVoice is not a medical tool. If you are experiencing a crisis, please reach out for immediate support. You are not alone.
+          </p>
+          <div className="flex flex-col gap-2">
+            <div className="bg-black/20 p-3 rounded-lg border border-coral-500/20 flex justify-between items-center">
+              <div>
+                <div className="font-bold">Suicide & Crisis Lifeline (US)</div>
+                <div className="text-xs text-white/60">Available 24/7. Free and confidential.</div>
+              </div>
+              <a href="tel:988" className="bg-coral-500 hover:bg-coral-400 text-white font-bold py-2 px-4 rounded-lg transition-colors">
+                Call 988
+              </a>
+            </div>
+            <div className="bg-black/20 p-3 rounded-lg border border-coral-500/20 flex justify-between items-center">
+              <div>
+                <div className="font-bold">Crisis Text Line (US)</div>
+                <div className="text-xs text-white/60">Text HOME to connect with a Crisis Counselor.</div>
+              </div>
+              <a href="sms:741741" className="bg-white/10 hover:bg-white/20 text-white font-bold py-2 px-4 rounded-lg transition-colors border border-white/10">
+                Text 741741
+              </a>
+            </div>
+          </div>
+        </section>
+
+        {/* Privacy & Data */}
+        <section className="glass-card p-6 border-white/5">
+          <h2 className="text-xl font-semibold mb-4 border-b border-red-500/20 pb-2 text-red-400">Privacy & Data Control</h2>
+          <div className="space-y-4">
+            <p className="text-sm text-white/60">
+              Your voice recordings are processed in memory and deleted immediately after analysis. They are never stored permanently.
+            </p>
+            <div className="flex gap-4">
+              <button className="px-4 py-2 bg-white/5 hover:bg-white/10 rounded-lg text-sm text-white/80 transition-colors flex-1">
+                Export My Data
+              </button>
+              <button className="px-4 py-2 border border-red-500/30 text-red-400 hover:bg-red-500/10 rounded-lg text-sm transition-colors flex-1">
+                Delete Account
+              </button>
+            </div>
+          </div>
+        </section>
+
+      </div>
+    </div>
+  );
+}

frontend/app/timeline/page.tsx

@@ -0,0 +1,134 @@
+"use client";
+import { useEffect, useState } from "react";
+import { useDemoMode } from "@/hooks/useDemoMode";
+import { api, VoiceEntry, TrendsData } from "@/lib/api";
+import { DEMO_ENTRIES, DEMO_TRENDS } from "@/lib/demo-data";
+import MoodTimeline from "@/components/MoodTimeline";
+import CalendarHeatmap from "@/components/CalendarHeatmap";
+import EmotionBadge from "@/components/EmotionBadge";
+import { getMoodEmoji } from "@/lib/utils";
+
+export default function TimelinePage() {
+  const { isDemoMode, userId } = useDemoMode();
+  const [entries, setEntries] = useState<VoiceEntry[]>([]);
+  const [trends, setTrends] = useState<TrendsData | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [selectedEntry, setSelectedEntry] = useState<VoiceEntry | null>(null);
+  const [selectedDate, setSelectedDate] = useState<Date | null>(null);
+
+  useEffect(() => {
+    async function load() {
+      if (!userId) return;
+      try {
+        if (isDemoMode) {
+          setEntries([...DEMO_ENTRIES].reverse());
+          setTrends(DEMO_TRENDS);
+        } else {
+          const [eRes, tRes] = await Promise.all([
+            api.getEntries(userId, 30),
+            api.getTrends(userId),
+          ]);
+          setEntries(eRes);
+          setTrends(tRes);
+        }
+      } catch (e) {
+        console.error(e);
+      } finally {
+        setLoading(false);
+      }
+    }
+    load();
+  }, [userId, isDemoMode]);
+
+  const handleDayClick = (entry: VoiceEntry | null, date: Date) => {
+    setSelectedEntry(entry);
+    setSelectedDate(date);
+  };
+
+  if (loading) return <div className="p-10 flex justify-center"><div className="w-8 h-8 rounded-full border-2 border-purple-500 border-t-transparent animate-spin"/></div>;
+
+  return (
+    <div className="p-6 md:p-10 max-w-7xl mx-auto space-y-8 min-h-[90vh]">
+      <h1 className="text-3xl font-bold">Timeline Patterns</h1>
+
+      <div className="grid lg:grid-cols-3 gap-6">
+        
+        <div className="lg:col-span-2 space-y-6">
+          <div className="glass-card p-6">
+            <h2 className="text-lg font-semibold mb-6 flex items-center justify-between">
+              <span>30-Day Trajectory</span>
+              <span className="text-xs font-normal px-2 py-1 bg-white/5 rounded-md text-white/50">All Scores</span>
+            </h2>
+            <MoodTimeline entries={entries} showAllScores height={300} onPointClick={setSelectedEntry} />
+          </div>
+
+          <div className="glass-card p-6 overflow-x-auto">
+            <h2 className="text-lg font-semibold mb-6">Check-in Activity</h2>
+            <CalendarHeatmap entries={entries} onDayClick={handleDayClick} />
+          </div>
+        </div>
+
+        <div className="space-y-6">
+          {selectedEntry ? (
+            <div className="glass-card p-6 sticky top-6 animate-fade-in border-purple-500/30 shadow-glow-purple">
+              <div className="flex justify-between items-start mb-4">
+                <h3 className="font-semibold text-lg">
+                  {new Date(selectedEntry.created_at).toLocaleDateString("en-US", { weekday: 'short', month: 'short', day: 'numeric'})}
+                </h3>
+                <button onClick={() => setSelectedEntry(null)} className="text-white/40 hover:text-white">✕</button>
+              </div>
+              
+              <div className="flex items-center gap-4 mb-6">
+                <div className="text-4xl">{getMoodEmoji(selectedEntry.mood_score)}</div>
+                <EmotionBadge emotion={selectedEntry.primary_emotion} confidence={selectedEntry.emotion_confidence} />
+              </div>
+
+              <div className="space-y-3 mb-6 bg-white/5 p-4 rounded-xl">
+                <div className="flex justify-between text-sm">
+                  <span className="text-white/60">Mood</span>
+                  <span className="font-medium text-purple-300">{selectedEntry.mood_score}</span>
+                </div>
+                <div className="flex justify-between text-sm">
+                  <span className="text-white/60">Energy</span>
+                  <span className="font-medium text-teal-300">{selectedEntry.energy_score}</span>
+                </div>
+                <div className="flex justify-between text-sm">
+                  <span className="text-white/60">Calmness</span>
+                  <span className="font-medium text-blue-300">{selectedEntry.calmness_score}</span>
+                </div>
+              </div>
+
+              {selectedEntry.transcription && (
+                <div>
+                  <div className="text-xs uppercase text-white/40 mb-2 font-semibold">Transcription</div>
+                  <p className="text-sm text-white/80 italic">"{selectedEntry.transcription}"</p>
+                </div>
+              )}
+            </div>
+          ) : (
+            <div className="glass-card p-6 text-white/40 text-sm text-center italic border-dashed border-white/10 sticky top-6">
+              Click any point on the chart or calendar to view details for that day.
+            </div>
+          )}
+
+          <div className="glass-card p-6">
+            <h2 className="text-lg font-semibold mb-4">Pattern Insights</h2>
+            {trends?.insights && trends.insights.length > 0 ? (
+              <ul className="space-y-4">
+                {trends.insights.map((insight, i) => (
+                  <li key={i} className="flex gap-3 text-sm text-white/80 items-start">
+                    <span className="text-purple-400 mt-0.5">✦</span>
+                    <span>{insight}</span>
+                  </li>
+                ))}
+              </ul>
+            ) : (
+              <p className="text-sm text-white/50 italic">More data needed to generate pattern insights (min 7 days).</p>
+            )}
+          </div>
+        </div>
+
+      </div>
+    </div>
+  );
+}

frontend/components/AlertCard.tsx

@@ -0,0 +1,71 @@
+"use client";
+import { getSeverityColor, getSeverityIcon } from "@/lib/utils";
+
+interface AlertCardProps {
+  id: string;
+  alert_type: string;
+  severity: string;
+  message: string;
+  suggested_action?: string | null;
+  created_at: string;
+  onDismiss?: (id: string) => void;
+}
+
+export default function AlertCard({
+  id,
+  alert_type,
+  severity,
+  message,
+  suggested_action,
+  created_at,
+  onDismiss,
+}: AlertCardProps) {
+  const severityClass = getSeverityColor(severity);
+  const icon = getSeverityIcon(severity);
+
+  const typeLabels: Record<string, string> = {
+    mood_decline: "Mood Decline",
+    low_energy: "Low Energy",
+    high_anxiety: "Elevated Anxiety",
+    burnout_risk: "Burnout Risk",
+    crisis: "Needs Attention",
+    persistent_sadness: "Persistent Sadness",
+  };
+
+  return (
+    <div
+      className={`rounded-xl border p-4 ${severityClass} animate-fade-in transition-all`}
+    >
+      <div className="flex items-start justify-between gap-3">
+        <div className="flex items-start gap-3 flex-1">
+          <span className="text-xl mt-0.5 shrink-0">{icon}</span>
+          <div className="flex-1 min-w-0">
+            <div className="flex items-center gap-2 mb-1 flex-wrap">
+              <span className="text-xs font-semibold uppercase tracking-wide text-white/50">
+                {typeLabels[alert_type] ?? alert_type}
+              </span>
+              <span className="text-xs text-white/30">
+                {new Date(created_at).toLocaleDateString()}
+              </span>
+            </div>
+            <p className="text-sm text-white/90 leading-relaxed">{message}</p>
+            {suggested_action && (
+              <p className="mt-2 text-xs text-white/60 italic">
+                💡 {suggested_action}
+              </p>
+            )}
+          </div>
+        </div>
+        {onDismiss && (
+          <button
+            onClick={() => onDismiss(id)}
+            className="text-white/30 hover:text-white/70 transition-colors shrink-0"
+            title="Dismiss"
+          >
+            ✕
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

frontend/components/CalendarHeatmap.tsx

@@ -0,0 +1,101 @@
+"use client";
+import { VoiceEntry } from "@/lib/api";
+import { getScoreColor } from "@/lib/utils";
+
+interface CalendarHeatmapProps {
+  entries: VoiceEntry[];
+  onDayClick?: (entry: VoiceEntry | null, date: Date) => void;
+}
+
+function getDateKey(date: Date): string {
+  return date.toISOString().split("T")[0];
+}
+
+export default function CalendarHeatmap({ entries, onDayClick }: CalendarHeatmapProps) {
+  // Build a map of date → entry
+  const entryMap: Record<string, VoiceEntry> = {};
+  entries.forEach((e) => {
+    const key = e.created_at.split("T")[0];
+    entryMap[key] = e;
+  });
+
+  // Generate last 30 days grid
+  const days: Date[] = [];
+  for (let i = 29; i >= 0; i--) {
+    const d = new Date();
+    d.setDate(d.getDate() - i);
+    days.push(d);
+  }
+
+  // Group into weeks
+  const weeks: Date[][] = [];
+  let week: Date[] = [];
+  days.forEach((d, i) => {
+    week.push(d);
+    if (week.length === 7 || i === days.length - 1) {
+      weeks.push(week);
+      week = [];
+    }
+  });
+
+  return (
+    <div>
+      <div className="text-xs text-white/40 mb-3">Last 30 days</div>
+      <div className="flex gap-1.5">
+        {weeks.map((week, wi) => (
+          <div key={wi} className="flex flex-col gap-1.5">
+            {week.map((day) => {
+              const key = getDateKey(day);
+              const entry = entryMap[key];
+              const isToday = key === getDateKey(new Date());
+
+              let bg = "bg-white/5";
+              let title = day.toLocaleDateString();
+
+              if (entry) {
+                const color = getScoreColor(entry.mood_score);
+                const opacity = Math.max(0.2, entry.mood_score / 100);
+                title = `${day.toLocaleDateString()} — Mood: ${entry.mood_score} (${entry.primary_emotion})`;
+                return (
+                  <button
+                    key={key}
+                    title={title}
+                    onClick={() => onDayClick?.(entry, day)}
+                    className={`w-8 h-8 rounded-md transition-all hover:scale-110 hover:brightness-125 ${isToday ? "ring-2 ring-purple-400" : ""}`}
+                    style={{
+                      backgroundColor: color,
+                      opacity,
+                    }}
+                  />
+                );
+              }
+
+              return (
+                <button
+                  key={key}
+                  title={title}
+                  onClick={() => onDayClick?.(null, day)}
+                  className={`w-8 h-8 rounded-md ${bg} ${isToday ? "ring-2 ring-purple-400/50" : ""} cursor-default`}
+                />
+              );
+            })}
+          </div>
+        ))}
+      </div>
+      {/* Legend */}
+      <div className="flex items-center gap-3 mt-3">
+        <span className="text-xs text-white/30">Less</span>
+        <div className="flex gap-1">
+          {[15, 30, 50, 70, 90].map((v) => (
+            <div
+              key={v}
+              className="w-4 h-4 rounded-sm"
+              style={{ backgroundColor: getScoreColor(v), opacity: Math.max(0.2, v / 100) }}
+            />
+          ))}
+        </div>
+        <span className="text-xs text-white/30">More</span>
+      </div>
+    </div>
+  );
+}

frontend/components/CircularProgress.tsx

@@ -0,0 +1,66 @@
+"use client";
+import { getScoreColor } from "@/lib/utils";
+
+interface CircularProgressProps {
+  score: number;
+  label: string;
+  size?: number;
+  strokeWidth?: number;
+}
+
+export default function CircularProgress({
+  score,
+  label,
+  size = 96,
+  strokeWidth = 8,
+}: CircularProgressProps) {
+  const radius = (size - strokeWidth * 2) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const progress = (score / 100) * circumference;
+  const color = getScoreColor(score);
+  const cx = size / 2;
+  const cy = size / 2;
+
+  return (
+    <div className="flex flex-col items-center gap-2">
+      <div className="relative" style={{ width: size, height: size }}>
+        <svg
+          width={size}
+          height={size}
+          className="-rotate-90"
+          style={{ transform: "rotate(-90deg)" }}
+        >
+          {/* Background track */}
+          <circle
+            cx={cx}
+            cy={cy}
+            r={radius}
+            fill="none"
+            stroke="rgba(255,255,255,0.08)"
+            strokeWidth={strokeWidth}
+          />
+          {/* Progress arc */}
+          <circle
+            cx={cx}
+            cy={cy}
+            r={radius}
+            fill="none"
+            stroke={color}
+            strokeWidth={strokeWidth}
+            strokeDasharray={`${progress} ${circumference}`}
+            strokeLinecap="round"
+            style={{
+              filter: `drop-shadow(0 0 6px ${color}80)`,
+              transition: "stroke-dasharray 0.8s ease",
+            }}
+          />
+        </svg>
+        {/* Center score */}
+        <div className="absolute inset-0 flex flex-col items-center justify-center">
+          <span className="text-xl font-bold text-white leading-none">{score}</span>
+        </div>
+      </div>
+      <span className="text-xs font-medium text-white/60 tracking-wide uppercase">{label}</span>
+    </div>
+  );
+}

frontend/components/DemoModeBanner.tsx

@@ -0,0 +1,24 @@
+"use client";
+import { useDemoMode } from "@/hooks/useDemoMode";
+
+export default function DemoModeBanner() {
+  const { isDemoMode, toggleDemoMode } = useDemoMode();
+  if (!isDemoMode) return null;
+
+  return (
+    <div className="fixed top-0 left-0 right-0 z-50 bg-gradient-to-r from-teal-600/80 to-purple-600/80 backdrop-blur-md border-b border-white/10 py-2 px-4 flex items-center justify-between gap-4 md:left-64">
+      <div className="flex items-center gap-2 text-sm text-white/90">
+        <span>📊</span>
+        <span>
+          <strong>Demo Mode</strong> — Showing 30 days of sample data. No account needed.
+        </span>
+      </div>
+      <button
+        onClick={toggleDemoMode}
+        className="text-xs text-white/60 hover:text-white underline shrink-0"
+      >
+        Exit Demo
+      </button>
+    </div>
+  );
+}

frontend/components/EmotionBadge.tsx

@@ -0,0 +1,47 @@
+"use client";
+import { capitalise, getEmotionBg, getEmotionColor } from "@/lib/utils";
+
+interface EmotionBadgeProps {
+  emotion: string;
+  confidence?: number;
+  size?: "sm" | "md" | "lg";
+}
+
+const EMOTION_EMOJI: Record<string, string> = {
+  happy: "😊",
+  sad: "😢",
+  angry: "😠",
+  fearful: "😨",
+  neutral: "😐",
+  anxious: "😰",
+  disgust: "😒",
+  surprised: "😲",
+};
+
+export default function EmotionBadge({
+  emotion,
+  confidence,
+  size = "md",
+}: EmotionBadgeProps) {
+  const emoji = EMOTION_EMOJI[emotion] ?? "🎭";
+  const bgClass = getEmotionBg(emotion);
+  const textClass = getEmotionColor(emotion);
+
+  const sizeClasses = {
+    sm: "text-xs px-2 py-1 gap-1",
+    md: "text-sm px-3 py-1.5 gap-1.5",
+    lg: "text-base px-4 py-2 gap-2",
+  };
+
+  return (
+    <span
+      className={`inline-flex items-center rounded-full border font-medium ${bgClass} ${textClass} ${sizeClasses[size]}`}
+    >
+      <span>{emoji}</span>
+      <span>{capitalise(emotion)}</span>
+      {confidence !== undefined && (
+        <span className="opacity-60">· {Math.round(confidence * 100)}%</span>
+      )}
+    </span>
+  );
+}

frontend/components/MoodTimeline.tsx

@@ -0,0 +1,103 @@
+"use client";
+import {
+  AreaChart, Area, XAxis, YAxis, CartesianGrid, Tooltip,
+  ResponsiveContainer, ReferenceLine
+} from "recharts";
+import { VoiceEntry } from "@/lib/api";
+import { formatDate, getMoodEmoji } from "@/lib/utils";
+
+interface MoodTimelineProps {
+  entries: VoiceEntry[];
+  onPointClick?: (entry: VoiceEntry) => void;
+  showAllScores?: boolean;
+  height?: number;
+}
+
+function CustomTooltip({ active, payload, label }: any) {
+  if (!active || !payload?.length) return null;
+  const d = payload[0]?.payload;
+  return (
+    <div className="bg-[#1a0f2e]/95 border border-white/10 rounded-xl p-3 shadow-xl text-sm">
+      <div className="text-white/50 mb-2">{label}</div>
+      <div className="flex items-center gap-2 mb-1">
+        <span className="text-lg">{getMoodEmoji(d.mood_score)}</span>
+        <span className="text-white font-medium">Mood: {d.mood_score}</span>
+      </div>
+      {d.energy_score && <div className="text-white/60">Energy: {d.energy_score}</div>}
+      {d.calmness_score && <div className="text-white/60">Calmness: {d.calmness_score}</div>}
+      {d.clarity_score && <div className="text-white/60">Clarity: {d.clarity_score}</div>}
+      <div className="mt-2 text-xs text-purple-300 capitalize">{d.primary_emotion}</div>
+    </div>
+  );
+}
+
+export default function MoodTimeline({
+  entries,
+  onPointClick,
+  showAllScores = false,
+  height = 220,
+}: MoodTimelineProps) {
+  const data = entries.map((e) => ({
+    ...e,
+    date: formatDate(e.created_at),
+  }));
+
+  return (
+    <ResponsiveContainer width="100%" height={height}>
+      <AreaChart data={data} margin={{ top: 10, right: 10, left: -20, bottom: 0 }}
+        onClick={(e: any) => {
+          if (e?.activePayload?.[0] && onPointClick) {
+            onPointClick(e.activePayload[0].payload);
+          }
+        }}
+      >
+        <defs>
+          <linearGradient id="moodGradient" x1="0" y1="0" x2="0" y2="1">
+            <stop offset="5%" stopColor="#8B5CF6" stopOpacity={0.4} />
+            <stop offset="95%" stopColor="#8B5CF6" stopOpacity={0.0} />
+          </linearGradient>
+          <linearGradient id="energyGradient" x1="0" y1="0" x2="0" y2="1">
+            <stop offset="5%" stopColor="#14b8a6" stopOpacity={0.3} />
+            <stop offset="95%" stopColor="#14b8a6" stopOpacity={0.0} />
+          </linearGradient>
+          <linearGradient id="calmnessGradient" x1="0" y1="0" x2="0" y2="1">
+            <stop offset="5%" stopColor="#3b82f6" stopOpacity={0.3} />
+            <stop offset="95%" stopColor="#3b82f6" stopOpacity={0.0} />
+          </linearGradient>
+        </defs>
+        <CartesianGrid strokeDasharray="3 3" stroke="rgba(255,255,255,0.05)" />
+        <XAxis
+          dataKey="date"
+          tick={{ fill: "rgba(255,255,255,0.4)", fontSize: 11 }}
+          tickLine={false}
+          axisLine={false}
+          interval="preserveStartEnd"
+        />
+        <YAxis
+          domain={[0, 100]}
+          tick={{ fill: "rgba(255,255,255,0.4)", fontSize: 11 }}
+          tickLine={false}
+          axisLine={false}
+        />
+        <Tooltip content={<CustomTooltip />} />
+        <ReferenceLine y={50} stroke="rgba(255,255,255,0.1)" strokeDasharray="4 4" />
+        <Area
+          type="monotone"
+          dataKey="mood_score"
+          stroke="#8B5CF6"
+          strokeWidth={2.5}
+          fill="url(#moodGradient)"
+          dot={{ fill: "#8B5CF6", r: 3, strokeWidth: 0 }}
+          activeDot={{ r: 6, fill: "#8B5CF6", strokeWidth: 0 }}
+          name="Mood"
+        />
+        {showAllScores && (
+          <>
+            <Area type="monotone" dataKey="energy_score" stroke="#14b8a6" strokeWidth={1.5} fill="url(#energyGradient)" dot={false} name="Energy" />
+            <Area type="monotone" dataKey="calmness_score" stroke="#3b82f6" strokeWidth={1.5} fill="url(#calmnessGradient)" dot={false} name="Calmness" />
+          </>
+        )}
+      </AreaChart>
+    </ResponsiveContainer>
+  );
+}

frontend/components/Navbar.tsx

@@ -0,0 +1,100 @@
+"use client";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { useDemoMode } from "@/hooks/useDemoMode";
+
+const navItems = [
+  { href: "/dashboard", label: "Dashboard", icon: "🏠" },
+  { href: "/record", label: "Check-in", icon: "🎙️" },
+  { href: "/timeline", label: "Timeline", icon: "📈" },
+  { href: "/chat", label: "Companion", icon: "💬" },
+  { href: "/settings", label: "Settings", icon: "⚙️" },
+];
+
+export default function Navbar() {
+  const pathname = usePathname();
+  const { isDemoMode, toggleDemoMode } = useDemoMode();
+
+  return (
+    <>
+      {/* Desktop sidebar */}
+      <nav className="hidden md:flex fixed left-0 top-0 h-full w-64 flex-col bg-[#130d24]/90 backdrop-blur-xl border-r border-white/5 z-40">
+        {/* Logo */}
+        <div className="p-6 border-b border-white/5">
+          <Link href="/" className="flex items-center gap-3 group">
+            <div className="w-9 h-9 rounded-xl bg-gradient-to-br from-purple-600 to-teal-500 flex items-center justify-center text-lg shadow-glow-purple">
+              🎵
+            </div>
+            <div>
+              <div className="font-bold text-white text-lg leading-none">InnerVoice</div>
+              <div className="text-xs text-white/40 mt-0.5">Wellness Tracker</div>
+            </div>
+          </Link>
+        </div>
+
+        {/* Nav links */}
+        <div className="flex-1 p-4 space-y-1">
+          {navItems.map(({ href, label, icon }) => {
+            const active = pathname === href || pathname.startsWith(href + "/");
+            return (
+              <Link
+                key={href}
+                href={href}
+                className={`flex items-center gap-3 px-4 py-3 rounded-xl transition-all ${
+                  active
+                    ? "bg-purple-600/20 text-purple-300 border border-purple-600/30"
+                    : "text-white/50 hover:text-white/80 hover:bg-white/5"
+                }`}
+              >
+                <span className="text-lg">{icon}</span>
+                <span className="font-medium">{label}</span>
+                {active && (
+                  <div className="ml-auto w-1.5 h-1.5 rounded-full bg-purple-400" />
+                )}
+              </Link>
+            );
+          })}
+        </div>
+
+        {/* Demo mode toggle */}
+        <div className="p-4 border-t border-white/5">
+          <button
+            onClick={toggleDemoMode}
+            className={`w-full flex items-center gap-3 px-4 py-3 rounded-xl transition-all text-sm ${
+              isDemoMode
+                ? "bg-teal-500/20 text-teal-300 border border-teal-500/30"
+                : "text-white/40 hover:text-white/60 hover:bg-white/5"
+            }`}
+          >
+            <span>{isDemoMode ? "📊" : "🔒"}</span>
+            <span className="font-medium">{isDemoMode ? "Demo Mode ON" : "Demo Mode OFF"}</span>
+          </button>
+          <p className="text-[10px] text-white/20 text-center mt-2 px-2">
+            InnerVoice is not a medical tool. If in crisis, call 988.
+          </p>
+        </div>
+      </nav>
+
+      {/* Mobile bottom bar */}
+      <nav className="md:hidden fixed bottom-0 left-0 right-0 z-40 bg-[#130d24]/95 backdrop-blur-xl border-t border-white/5">
+        <div className="flex justify-around px-2 py-2">
+          {navItems.map(({ href, label, icon }) => {
+            const active = pathname === href;
+            return (
+              <Link
+                key={href}
+                href={href}
+                className={`flex flex-col items-center gap-1 px-3 py-2 rounded-xl transition-all ${
+                  active ? "text-purple-400" : "text-white/40"
+                }`}
+              >
+                <span className="text-xl">{icon}</span>
+                <span className="text-[10px] font-medium">{label}</span>
+              </Link>
+            );
+          })}
+        </div>
+      </nav>
+    </>
+  );
+}

frontend/components/WaveformVisualizer.tsx

@@ -0,0 +1,87 @@
+"use client";
+import { useEffect, useRef } from "react";
+
+interface WaveformVisualizerProps {
+  analyserNode: AnalyserNode | null;
+  isActive: boolean;
+  height?: number;
+  color?: string;
+}
+
+export default function WaveformVisualizer({
+  analyserNode,
+  isActive,
+  height = 80,
+  color = "#8B5CF6",
+}: WaveformVisualizerProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const animFrameRef = useRef<number>(0);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+
+    const draw = () => {
+      animFrameRef.current = requestAnimationFrame(draw);
+      const W = canvas.width;
+      const H = canvas.height;
+      ctx.clearRect(0, 0, W, H);
+
+      if (!analyserNode || !isActive) {
+        // Idle animation — gentle sine wave
+        ctx.beginPath();
+        const t = Date.now() / 800;
+        for (let x = 0; x < W; x++) {
+          const y = H / 2 + Math.sin(x * 0.03 + t) * 8 * Math.sin(x * 0.008 + t * 0.5);
+          x === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y);
+        }
+        ctx.strokeStyle = color + "60";
+        ctx.lineWidth = 2;
+        ctx.stroke();
+        return;
+      }
+
+      const bufLen = analyserNode.frequencyBinCount;
+      const dataArray = new Uint8Array(bufLen);
+      analyserNode.getByteTimeDomainData(dataArray);
+
+      // Draw gradient waveform
+      const gradient = ctx.createLinearGradient(0, 0, W, 0);
+      gradient.addColorStop(0, "#8B5CF6");
+      gradient.addColorStop(0.5, "#14b8a6");
+      gradient.addColorStop(1, "#8B5CF6");
+
+      ctx.beginPath();
+      const sliceW = W / bufLen;
+      let x = 0;
+      for (let i = 0; i < bufLen; i++) {
+        const v = dataArray[i] / 128.0;
+        const y = (v * H) / 2;
+        i === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y);
+        x += sliceW;
+      }
+      ctx.lineTo(W, H / 2);
+      ctx.strokeStyle = gradient;
+      ctx.lineWidth = 2.5;
+      ctx.shadowBlur = 12;
+      ctx.shadowColor = color;
+      ctx.stroke();
+      ctx.shadowBlur = 0;
+    };
+
+    draw();
+    return () => cancelAnimationFrame(animFrameRef.current);
+  }, [analyserNode, isActive, color]);
+
+  return (
+    <canvas
+      ref={canvasRef}
+      width={600}
+      height={height}
+      className="w-full rounded-xl"
+      style={{ height }}
+    />
+  );
+}

frontend/hooks/useAudioRecorder.ts

@@ -0,0 +1,120 @@
+"use client";
+import { useState, useRef, useCallback, useEffect } from "react";
+
+export type RecorderState = "idle" | "requesting" | "recording" | "stopped" | "error";
+
+export interface UseAudioRecorderReturn {
+  state: RecorderState;
+  seconds: number;
+  audioBlob: Blob | null;
+  analyserNode: AnalyserNode | null;
+  startRecording: () => Promise<void>;
+  stopRecording: () => void;
+  reset: () => void;
+  error: string | null;
+}
+
+export function useAudioRecorder(maxSeconds = 60): UseAudioRecorderReturn {
+  const [state, setState] = useState<RecorderState>("idle");
+  const [seconds, setSeconds] = useState(0);
+  const [audioBlob, setAudioBlob] = useState<Blob | null>(null);
+  const [analyserNode, setAnalyserNode] = useState<AnalyserNode | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const mediaRecorderRef = useRef<MediaRecorder | null>(null);
+  const chunksRef = useRef<Blob[]>([]);
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const audioContextRef = useRef<AudioContext | null>(null);
+  const streamRef = useRef<MediaStream | null>(null);
+
+  const cleanup = useCallback(() => {
+    if (timerRef.current) clearInterval(timerRef.current);
+    if (audioContextRef.current && audioContextRef.current.state !== "closed") {
+      audioContextRef.current.close();
+      audioContextRef.current = null;
+    }
+    if (streamRef.current) {
+      streamRef.current.getTracks().forEach((t) => t.stop());
+      streamRef.current = null;
+    }
+    setAnalyserNode(null);
+  }, []);
+
+  const startRecording = useCallback(async () => {
+    setState("requesting");
+    setError(null);
+    chunksRef.current = [];
+    setAudioBlob(null);
+
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      streamRef.current = stream;
+
+      // Set up Web Audio API for visualisation
+      const audioContext = new AudioContext();
+      audioContextRef.current = audioContext;
+      const source = audioContext.createMediaStreamSource(stream);
+      const analyser = audioContext.createAnalyser();
+      analyser.fftSize = 256;
+      source.connect(analyser);
+      setAnalyserNode(analyser);
+
+      const mediaRecorder = new MediaRecorder(stream, {
+        mimeType: MediaRecorder.isTypeSupported("audio/webm;codecs=opus")
+          ? "audio/webm;codecs=opus"
+          : "audio/webm",
+      });
+      mediaRecorderRef.current = mediaRecorder;
+
+      mediaRecorder.ondataavailable = (e) => {
+        if (e.data.size > 0) chunksRef.current.push(e.data);
+      };
+
+      mediaRecorder.onstop = () => {
+        const blob = new Blob(chunksRef.current, { type: "audio/webm" });
+        setAudioBlob(blob);
+        cleanup();
+      };
+
+      mediaRecorder.start(250);
+      setState("recording");
+      setSeconds(0);
+
+      timerRef.current = setInterval(() => {
+        setSeconds((prev) => {
+          if (prev + 1 >= maxSeconds) {
+            mediaRecorderRef.current?.stop();
+            if (timerRef.current) clearInterval(timerRef.current);
+            setState("stopped");
+            return maxSeconds;
+          }
+          return prev + 1;
+        });
+      }, 1000);
+    } catch (err) {
+      setError("Microphone access denied. Please allow microphone access and try again.");
+      setState("error");
+    }
+  }, [cleanup, maxSeconds]);
+
+  const stopRecording = useCallback(() => {
+    if (mediaRecorderRef.current && state === "recording") {
+      mediaRecorderRef.current.stop();
+      if (timerRef.current) clearInterval(timerRef.current);
+      setState("stopped");
+    }
+  }, [state]);
+
+  const reset = useCallback(() => {
+    cleanup();
+    setState("idle");
+    setSeconds(0);
+    setAudioBlob(null);
+    setError(null);
+    chunksRef.current = [];
+  }, [cleanup]);
+
+  useEffect(() => () => cleanup(), [cleanup]);
+
+  return { state, seconds, audioBlob, analyserNode, startRecording, stopRecording, reset, error };
+}

frontend/hooks/useDemoMode.ts

@@ -0,0 +1,33 @@
+"use client";
+import { useState, useEffect } from "react";
+
+const DEMO_KEY = "innervoice_demo_mode";
+
+export function useDemoMode() {
+  const [isDemoMode, setIsDemoMode] = useState(true);
+
+  useEffect(() => {
+    const stored = localStorage.getItem(DEMO_KEY);
+    if (stored !== null) {
+      setIsDemoMode(stored === "true");
+    } else {
+      // Default to demo mode on first visit
+      const envDefault = process.env.NEXT_PUBLIC_DEMO_MODE === "true";
+      setIsDemoMode(envDefault);
+    }
+  }, []);
+
+  const toggleDemoMode = () => {
+    setIsDemoMode((prev) => {
+      const next = !prev;
+      localStorage.setItem(DEMO_KEY, String(next));
+      return next;
+    });
+  };
+
+  const userId = isDemoMode
+    ? "demo-user-local"
+    : (typeof window !== "undefined" && localStorage.getItem("innervoice_user_id")) || "";
+
+  return { isDemoMode, toggleDemoMode, userId };
+}

frontend/lib/api.ts

@@ -0,0 +1,111 @@
+// API client for InnerVoice backend
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL || "http://localhost:8000";
+
+export async function apiGet<T>(path: string): Promise<T> {
+  const res = await fetch(`${API_URL}${path}`);
+  if (!res.ok) throw new Error(`API Error ${res.status}: ${await res.text()}`);
+  return res.json();
+}
+
+export async function apiPost<T>(path: string, body: unknown): Promise<T> {
+  const res = await fetch(`${API_URL}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`API Error ${res.status}: ${await res.text()}`);
+  return res.json();
+}
+
+export async function apiPut<T>(path: string): Promise<T> {
+  const res = await fetch(`${API_URL}${path}`, { method: "PUT" });
+  if (!res.ok) throw new Error(`API Error ${res.status}: ${await res.text()}`);
+  return res.json();
+}
+
+// ── Typed API functions ───────────────────────────────────────────────────────
+
+export interface VoiceEntry {
+  id: string;
+  created_at: string;
+  primary_emotion: string;
+  emotion_confidence: number;
+  energy_score: number;
+  calmness_score: number;
+  mood_score: number;
+  clarity_score: number;
+  transcription: string;
+  duration_seconds: number;
+  pitch_mean: number;
+  speech_rate: number;
+  pause_count: number;
+  filler_rate: number;
+}
+
+export interface MoodAlert {
+  id: string;
+  created_at: string;
+  alert_type: string;
+  severity: string;
+  message: string;
+  suggested_action: string | null;
+  is_read: boolean;
+}
+
+export interface TrendsData {
+  entries_count: number;
+  streak: number;
+  most_common_emotion: string | null;
+  this_week: Record<string, number | null>;
+  last_week: Record<string, number | null>;
+  insights: string[];
+}
+
+export interface AnalyzeResult {
+  entry_id: string;
+  emotion: string;
+  confidence: number;
+  mood_scores: { energy: number; calmness: number; mood: number; clarity: number };
+  transcription: string;
+  features: Record<string, unknown>;
+  insight: string;
+  new_alerts: MoodAlert[];
+}
+
+export const api = {
+  getEntries: (userId: string, days = 30) =>
+    apiGet<VoiceEntry[]>(`/api/entries?user_id=${userId}&days=${days}`),
+
+  getTrends: (userId: string) =>
+    apiGet<TrendsData>(`/api/trends?user_id=${userId}`),
+
+  getAlerts: (userId: string) =>
+    apiGet<MoodAlert[]>(`/api/alerts?user_id=${userId}`),
+
+  markAlertRead: (alertId: string) =>
+    apiPut<{ success: boolean }>(`/api/alerts/${alertId}/read`),
+
+  chat: (userId: string, message: string) =>
+    apiPost<{ response: string }>("/api/chat", { user_id: userId, message }),
+
+  getChatHistory: (userId: string) =>
+    apiGet<Array<{ id: string; role: string; content: string; created_at: string }>>(
+      `/api/chat/history?user_id=${userId}`
+    ),
+
+  createUser: (email: string, name: string) =>
+    apiPost<{ id: string; email: string; name: string }>("/api/users", { email, name }),
+
+  analyzeAudio: async (audioBlob: Blob, userId: string): Promise<AnalyzeResult> => {
+    const formData = new FormData();
+    formData.append("audio", audioBlob, "recording.webm");
+    formData.append("user_id", userId);
+    const res = await fetch(`${API_URL}/api/analyze`, {
+      method: "POST",
+      body: formData,
+    });
+    if (!res.ok) throw new Error(`Analyze error ${res.status}`);
+    return res.json();
+  },
+};

frontend/lib/demo-data.ts

@@ -0,0 +1,125 @@
+// 30-day pre-generated mock data for Demo Mode
+import { VoiceEntry, MoodAlert, TrendsData } from "./api";
+
+const DEMO_USER_ID = "demo-user-local";
+
+function daysAgo(n: number): string {
+  const d = new Date();
+  d.setDate(d.getDate() - n);
+  d.setHours(20, 15, 0, 0);
+  return d.toISOString();
+}
+
+const emotions = ["happy", "neutral", "sad", "happy", "fearful", "neutral", "happy", "sad", "neutral", "anxious", "happy", "neutral", "sad", "angry", "neutral", "happy", "neutral", "sad", "sad", "fearful", "neutral", "neutral", "happy", "neutral", "happy", "happy", "neutral", "happy", "sad", "happy"];
+
+const transcriptions: Record<string, string[]> = {
+  happy: ["Today was genuinely great. I feel energised and hopeful about what's ahead.", "Spent time with people I love. Laughing feels like medicine.", "Something shifted today — I feel lighter than I have in weeks."],
+  neutral: ["Just a regular day. Nothing dramatic, but steady feels okay.", "Work was fine. Meetings ran long. Surviving.", "Feeling present. Not high, not low. Just here."],
+  sad: ["There's a heaviness I can't quite shake. Just going through the motions.", "Missing someone today. Feeling the distance.", "Hard to explain. Just off."],
+  anxious: ["Mind racing. Too many open tabs. Need to slow down.", "That chest-tight feeling again. Trying to breathe through it."],
+  fearful: ["Something feels uncertain and I can't name it.", "Woke up with dread. Working through it slowly."],
+  angry: ["Really frustrated with a situation. Trying not to carry it home."],
+};
+
+function pickTranscription(emotion: string): string {
+  const list = transcriptions[emotion] ?? transcriptions.neutral;
+  return list[Math.floor(Math.random() * list.length)];
+}
+
+function moodArc(i: number): number {
+  // Simulate a dip ~2 weeks ago with recovery
+  const x = (i - 15) / 15;
+  return Math.round(50 + 25 * Math.cos(x * Math.PI * 0.8));
+}
+
+export const DEMO_ENTRIES: VoiceEntry[] = Array.from({ length: 30 }, (_, i) => {
+  const daysAgoN = 30 - i;
+  const skip = [5, 11, 18, 25].includes(daysAgoN);
+  if (skip) return null as unknown as VoiceEntry;
+
+  const emotion = emotions[i % emotions.length];
+  const base = moodArc(i);
+  const jitter = () => Math.floor(Math.random() * 10 - 5);
+
+  const mood_score = Math.max(10, Math.min(95, base + jitter()));
+  const energy_score = Math.max(10, Math.min(95, base - 5 + jitter()));
+  const calmness_score = Math.max(10, Math.min(95, base + 5 + jitter()));
+  const clarity_score = Math.max(10, Math.min(95, base - 3 + jitter()));
+
+  return {
+    id: `demo-entry-${i}`,
+    created_at: daysAgo(daysAgoN),
+    primary_emotion: emotion,
+    emotion_confidence: parseFloat((0.65 + Math.random() * 0.3).toFixed(3)),
+    energy_score,
+    calmness_score,
+    mood_score,
+    clarity_score,
+    transcription: pickTranscription(emotion),
+    duration_seconds: parseFloat((35 + Math.random() * 25).toFixed(1)),
+    pitch_mean: parseFloat((130 + Math.random() * 60).toFixed(2)),
+    speech_rate: parseFloat((80 + Math.random() * 40).toFixed(2)),
+    pause_count: Math.floor(2 + Math.random() * 10),
+    filler_rate: parseFloat((0.01 + Math.random() * 0.06).toFixed(4)),
+  };
+}).filter(Boolean);
+
+export const DEMO_LATEST_ENTRY: VoiceEntry = {
+  id: "demo-today",
+  created_at: new Date().toISOString(),
+  primary_emotion: "happy",
+  emotion_confidence: 0.82,
+  energy_score: 74,
+  calmness_score: 68,
+  mood_score: 76,
+  clarity_score: 71,
+  transcription: "Honestly, today felt like a turning point. I feel more settled than I have in a while and I'm trying to hold onto that feeling.",
+  duration_seconds: 48.2,
+  pitch_mean: 162.4,
+  speech_rate: 98.5,
+  pause_count: 4,
+  filler_rate: 0.023,
+};
+
+export const DEMO_ALERTS: MoodAlert[] = [
+  {
+    id: "demo-alert-1",
+    created_at: daysAgo(2),
+    alert_type: "mood_decline",
+    severity: "warning",
+    message: "Your mood declined 24% this week compared to last week.",
+    suggested_action: "Try scheduling something enjoyable today, even something small.",
+    is_read: false,
+  },
+  {
+    id: "demo-alert-2",
+    created_at: daysAgo(1),
+    alert_type: "low_energy",
+    severity: "concern",
+    message: "Your energy has been consistently low for 5 days.",
+    suggested_action: "Even a 10-minute walk can shift your energy. Try it today.",
+    is_read: false,
+  },
+];
+
+export const DEMO_TRENDS: TrendsData = {
+  entries_count: 26,
+  streak: 5,
+  most_common_emotion: "neutral",
+  this_week: { mood: 68, energy: 62, calmness: 71, clarity: 66 },
+  last_week: { mood: 54, energy: 49, calmness: 58, clarity: 61 },
+  insights: [
+    "Your best days tend to be Wednesdays 🌟",
+    "Your mood tends to dip on Sundays",
+    "You've been improving steadily for 5 days 🌱",
+  ],
+};
+
+export const DEMO_CHAT_HISTORY = [
+  { id: "dm1", role: "user", content: "I'm fine, just a bit tired.", created_at: daysAgo(0) },
+  { id: "dm2", role: "assistant", content: "I hear you — and 'tired' can mean so many different things. Your voice this week has been a little lower in energy than usual. Is there something specific weighing on you, or is it more of a general fatigue?", created_at: daysAgo(0) },
+  { id: "dm3", role: "user", content: "Why have I been feeling off lately?", created_at: daysAgo(0) },
+  { id: "dm4", role: "assistant", content: "Looking at your last two weeks, your mood started dipping around 14 days ago and your energy has been below your baseline since then. That sometimes happens when routines are disrupted or there's background stress building up. Does anything stand out from around that time?", created_at: daysAgo(0) },
+];
+
+export { DEMO_USER_ID };