mood-mate

Mental Health Early Warning System

Comment

About the Project

Inspiration 💡

The inspiration for MoodMate came from recognizing a critical gap in mental health awareness and early intervention. In today's fast-paced world, many people struggle with stress, anxiety, and emotional challenges, but often these issues go unnoticed until they become serious crises.

Key inspirations:

  • Silent Suffering: Many people experience mental health struggles in silence, without recognizing early warning signs
  • Accessibility: Traditional mental health resources can be expensive, time-consuming, or stigmatized
  • Prevention Over Treatment: Early detection and intervention can prevent more serious mental health issues
  • Technology for Good: Using AI and modern web technologies to make mental health support more accessible and personalized

The tagline "Catch the silent signals of stress before they become crises" encapsulates our mission to create a proactive, accessible tool for emotional well-being tracking.

What I Learned 📚

Building MoodMate was an incredible learning journey that deepened my understanding across multiple domains:

AI/ML Integration

  • Sentiment Analysis: Learned to implement and fine-tune Hugging Face's DistilBERT model for real-time text analysis
  • Model Optimization: Discovered how to balance model accuracy with performance for production use
  • Fallback Strategies: Implemented robust fallback mechanisms when AI models fail to load

Full-Stack Development

  • Modern Frontend: Mastered Next.js 14 with App Router, TypeScript, and shadcn/ui components
  • API Design: Built RESTful APIs with FastAPI, focusing on scalability and error handling
  • Database Integration: Learned Supabase's PostgreSQL features, including Row Level Security and real-time subscriptions

Mental Health Domain

  • Early Warning Systems: Researched how to detect patterns in emotional data that could indicate declining mental health
  • Coping Strategies: Studied evidence-based interventions and how to personalize them based on sentiment analysis
  • Privacy & Ethics: Understood the importance of data privacy and ethical considerations in mental health applications

DevOps & Deployment

  • Containerization: Implemented Docker and Docker Compose for consistent deployment environments
  • Environment Management: Learned to handle sensitive configuration and API keys securely
  • Production Readiness: Built health checks, logging, and error monitoring systems

How I Built It 🔨

MoodMate follows a modern microservices architecture with clear separation of concerns:

Frontend Architecture

// Next.js 14 with App Router structure
app/
├── page.tsx           // Landing page with hero section
├── checkin/page.tsx   // Mood tracking interface
├── dashboard/page.tsx // Analytics and trends
└── layout.tsx         // Root layout with theme provider

Key Components:

  • Responsive Design: Built with Tailwind CSS and shadcn/ui for consistent, accessible components
  • State Management: Used React hooks for local state and localStorage for persistence
  • Data Visualization: Implemented Recharts for interactive mood trend graphs
  • Real-time Updates: Toast notifications and optimistic UI updates

Backend Architecture

# FastAPI with modular design
backend/
├── main.py              # API endpoints and routing
├── sentiment_analyzer.py # AI model integration
├── supabase_client.py   # Database operations
└── requirements.txt     # Dependencies

API Endpoints:

  • POST /analyze - Real-time sentiment analysis
  • POST /checkin - Save mood data with AI insights
  • GET /history/{user_id} - Retrieve user's mood history

AI Integration

# Sentiment analysis with fallback
class SentimentAnalyzer:
    def __init__(self):
        try:
            self.classifier = pipeline(
                "sentiment-analysis",
                model="distilbert-base-uncased-finetuned-sst-2-english",
                return_all_scores=True
            )
        except Exception:
            self._setup_fallback_analyzer()  # Keyword-based backup

Database Design

-- Optimized PostgreSQL schema
CREATE TABLE checkins (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL,
    mood INTEGER NOT NULL CHECK (mood >= 1 AND mood <= 10),
    note TEXT,
    sentiment TEXT NOT NULL CHECK (sentiment IN ('positive', 'negative', 'neutral')),
    coping_tip TEXT,
    timestamp TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Performance indexes
CREATE INDEX idx_checkins_user_id ON checkins(user_id);
CREATE INDEX idx_checkins_timestamp ON checkins(timestamp DESC);

Deployment Strategy

# Docker Compose for local development
version: '3.8'
services:
  backend:
    build: ./backend
    ports: ["8000:8000"]
    environment:
      - SUPABASE_URL=${SUPABASE_URL}
      - SUPABASE_KEY=${SUPABASE_KEY}

  frontend:
    build: ./frontend
    ports: ["3000:3000"]
    depends_on: [backend]

Challenges Faced 🚧

1. AI Model Integration Complexity

Challenge: Integrating Hugging Face's DistilBERT model with production constraints

  • Memory Issues: Large models caused memory problems in containerized environments
  • Loading Time: Initial model loading took 30+ seconds, affecting user experience
  • Version Conflicts: NumPy 2.x compatibility issues with PyTorch

Solutions:

  • Implemented lazy loading with fallback mechanisms
  • Downgraded to NumPy <2.0 for compatibility
  • Added model caching and health checks
  • Created keyword-based fallback analyzer

2. Database Schema and UUID Management

Challenge: Supabase PostgreSQL strict UUID requirements

  • Invalid UUIDs: Frontend generated user IDs like "temp-user-123" which failed database validation
  • Type Safety: Ensuring consistent UUID format across frontend and backend

Solutions:

  • Implemented crypto.randomUUID() in frontend
  • Added localStorage persistence for consistent user sessions
  • Created comprehensive UUID validation in backend
  • Built test scripts to verify database operations

3. Real-time Data Synchronization

Challenge: Keeping frontend and backend data in sync

  • Race Conditions: Multiple API calls causing inconsistent state
  • Error Handling: Graceful degradation when services are unavailable

Solutions:

  • Implemented optimistic UI updates with rollback mechanisms
  • Added comprehensive error boundaries and user feedback
  • Created health check endpoints for service monitoring
  • Built retry logic with exponential backoff

4. Production Readiness

Challenge: Moving from prototype to production-ready application

  • Security: Protecting sensitive API keys and user data
  • Performance: Optimizing for real-world usage patterns
  • Monitoring: Tracking errors and performance metrics

Solutions:

  • Implemented environment-based configuration
  • Added comprehensive logging and error tracking
  • Created Docker containers for consistent deployment
  • Built health check and monitoring endpoints

5. Mental Health Domain Expertise

Challenge: Building a tool that could genuinely help with mental health

  • Ethical Considerations: Ensuring the app doesn't provide medical advice
  • Evidence-Based Design: Incorporating research-backed coping strategies
  • Accessibility: Making the tool usable for people with various needs

Solutions:

  • Added clear disclaimers about professional help
  • Researched and implemented evidence-based coping tips
  • Designed with accessibility principles (WCAG guidelines)
  • Focused on awareness and early detection rather than diagnosis

Technical Achievements 🏆

  • Real-time AI Processing: Sentiment analysis with <2 second response time
  • Scalable Architecture: Designed to handle thousands of concurrent users
  • Privacy-First Design: User data encrypted and stored securely
  • Cross-Platform: Responsive design works on desktop, tablet, and mobile
  • Production Ready: Comprehensive error handling, logging, and monitoring

Future Enhancements 🚀

  • Mobile App: Native iOS/Android applications
  • Advanced Analytics: Machine learning for pattern prediction
  • Community Features: Anonymous support groups and peer connections
  • Professional Integration: Connect with mental health professionals
  • Multilingual Support: Expand to serve global audiences

MoodMate represents the intersection of technology and compassion, using modern tools to address one of humanity's most important challenges: mental health and well-being.

Built With

  • contextapi
  • distilbert
  • fastapi
  • lucidereact
  • nextjs
  • npm
  • numpy
  • pip
  • pydantic
  • python
  • python-dotenv
  • pytorch
  • radixui
  • react18
  • recharts
  • restfulapi
  • sentimentanalysis
  • shadcnui
  • supabase
  • tailwindcss
  • typescript
  • uvicorn
Share this project:

Updates