A production-ready mental health chatbot web application that provides empathetic AI-powered conversations, mindfulness exercises, and cognitive behavioral therapy (CBT) techniques for stress relief and emotional well-being.

• Real AI Conversations: Powered by OpenRouter API with Claude 3 Haiku
• Mindfulness Exercises: Guided breathing, grounding, and meditation techniques
• CBT Techniques: Thought challenging and cognitive restructuring exercises
• Session Management: Full conversation history with export capabilities
• Message Rating: Users can rate AI responses for feedback
• Error Handling: Comprehensive error handling with retry mechanisms
• Loading States: Smooth typing indicators and loading animations

• Clean, Calming Design: Therapeutic color palette and smooth animations
• Fully Responsive: Optimized for mobile, tablet, and desktop
• Accessibility: Screen reader support and keyboard navigation
• Real-time Interactions: Instant message delivery and smooth scrolling
• Export Conversations: Download chat history as text or JSON

• Production Ready: Real API integration, no mock data
• Environment Configuration: Secure API key management
• Error Recovery: Automatic retry mechanisms and fallback responses
• State Management: Persistent conversation state during session
• TypeScript: Full type safety throughout the application

• Node.js 18+ and npm
• OpenRouter API key (get from openrouter.ai)

1. Clone and install dependencies:

git clone <your-repo-url>
cd mindful-chat-app
npm install

2. Set up environment variables:

cp .env.example .env

3. Add your OpenRouter API key to .env:

VITE_OPENROUTER_API_KEY=sk-or-v1-your-api-key-here

4. Start the development server:

npm run dev

5. Open your browser to http://localhost:5173

1. Sign up at openrouter.ai
2. Navigate to the API Keys section in your dashboard
3. Create a new API key
4. Copy the key (starts with sk-or-v1-)

Create a .env file in your project root:

# Required: Your OpenRouter API key
VITE_OPENROUTER_API_KEY=sk-or-v1-your-actual-api-key-here

# Optional: Custom API endpoint (default shown)
VITE_OPENROUTER_API_URL=https://openrouter.ai/api/v1/chat/completions

# Optional: App configuration
VITE_APP_NAME=MindfulChat
VITE_APP_DESCRIPTION=Your AI Mental Health Companion

The app uses anthropic/claude-3-haiku by default. You can modify this in src/utils/openRouterAPI.ts:

• anthropic/claude-3-haiku (fast, cost-effective) - Default
• anthropic/claude-3-sonnet (balanced performance)
• openai/gpt-3.5-turbo (widely compatible)
• openai/gpt-4 (most capable, higher cost)

src/
├── components/           # React components
│   ├── ChatMessage.tsx   # Individual message display
│   ├── ChatInput.tsx     # Message input with voice support
│   ├── ChatHeader.tsx    # App header with controls
│   ├── TypingIndicator.tsx # Loading animation
│   ├── ErrorMessage.tsx  # Error display with retry
│   ├── MessageRating.tsx # Thumbs up/down rating
│   ├── ExportButton.tsx  # Conversation export
│   └── WelcomeMessage.tsx # Initial welcome screen
├── hooks/
│   └── useChat.ts        # Chat state management
├── utils/
│   └── openRouterAPI.ts  # API integration
├── data/
│   └── exercises.ts      # Mindfulness/CBT content
├── types/
│   └── chat.ts          # TypeScript definitions
└── App.tsx              # Main application component

The app includes a complete OpenRouter API integration:

// src/utils/openRouterAPI.ts
export async function sendChatMessage(messages: OpenRouterMessage[]): Promise<string> {
  const apiKey = import.meta.env.VITE_OPENROUTER_API_KEY;
  
  const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      'HTTP-Referer': window.location.origin,
      'X-Title': 'MindfulChat Mental Health Companion'
    },
    body: JSON.stringify({
      model: 'anthropic/claude-3-haiku',
      messages: [
        { role: 'system', content: SYSTEM_PROMPT },
        ...messages
      ],
      max_tokens: 400,
      temperature: 0.7
    })
  });
  
  // Full error handling and response processing...
}

Comprehensive error handling for:

• Invalid API keys
• Network connectivity issues
• Rate limiting
• Server errors
• Malformed responses

• Empathetic AI Responses: Trained specifically for mental health support
• Crisis Detection: Encourages professional help when appropriate
• Evidence-Based Techniques: CBT and mindfulness exercises
• Safe Environment: Non-judgmental, supportive interactions

• Therapeutic Design: Calming colors (teal, blue, soft grays)
• Smooth Animations: Framer Motion for delightful interactions
• Mobile Optimized: Touch-friendly interface for all devices
• Accessibility: WCAG compliant with keyboard navigation

• Session Persistence: Conversations maintained during session
• Export Options: Download as text or structured JSON
• Privacy Focused: No server-side data storage
• Message Rating: User feedback system for AI responses

1. Install Vercel CLI:

npm i -g vercel

2. Deploy:

vercel

3. Add environment variables in Vercel dashboard:
   • Go to your project settings
   • Add VITE_OPENROUTER_API_KEY with your API key

1. Build the project:

npm run build

2. Deploy the dist folder to Netlify

3. Add environment variables in Netlify dashboard

Make sure to add these environment variables in your deployment platform:

VITE_OPENROUTER_API_KEY=your-production-api-key

• Environment variables prevent key exposure
• Client-side validation of key format
• Secure headers for API requests

• No server-side conversation storage
• Local session management only
• Clear privacy disclaimers
• GDPR-friendly design

• Professional boundaries clearly defined
• Crisis intervention guidance
• Encourages professional help when needed
• Evidence-based therapeutic techniques

npm run dev      # Start development server
npm run build    # Build for production
npm run preview  # Preview production build
npm run lint     # Run ESLint

1. New Mindfulness Exercises: Edit src/data/exercises.ts
2. UI Components: Add to src/components/
3. API Modifications: Update src/utils/openRouterAPI.ts
4. Type Definitions: Extend src/types/chat.ts

// In src/utils/openRouterAPI.ts
body: JSON.stringify({
  model: 'openai/gpt-4', // Change this line
  // ... rest of configuration
})

The app uses Tailwind CSS with a custom color palette:

• Primary: Teal (teal-500, teal-600)
• Secondary: Blue (blue-500, blue-600)
• Accent: Purple (purple-500, purple-600)
• Neutral: Gray shades for text and backgrounds

• Lazy Loading: Components loaded as needed
• Efficient Rendering: React.memo and useCallback optimization
• Smooth Animations: Hardware-accelerated CSS transforms
• Responsive Images: Optimized for all screen sizes

• Lightweight: ~200KB gzipped
• Tree Shaking: Unused code eliminated
• Modern Build: ES2020+ for supported browsers

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

• Additional mindfulness exercises
• Voice input/output capabilities
• Multi-language support
• Advanced CBT techniques
• Accessibility improvements

MIT License - see LICENSE file for details.

• Open a GitHub issue for bugs or feature requests
• Check the troubleshooting section below

• Crisis Text Line: Text HOME to 741741
• National Suicide Prevention Lifeline: 988
• SAMHSA Helpline: 1-800-662-4357

API Key Not Working:

• Ensure key starts with sk-or-v1-
• Check for extra spaces or characters
• Verify key is active in OpenRouter dashboard

Build Errors:

• Clear node_modules: rm -rf node_modules && npm install
• Check Node.js version (18+ required)
• Verify all environment variables are set

Deployment Issues:

• Ensure environment variables are set in deployment platform
• Check build logs for specific errors
• Verify API key works in production environment

1. Check this README for common solutions
2. Search existing GitHub issues
3. Create a new issue with:
   • Error message
   • Steps to reproduce
   • Environment details (OS, Node version, etc.)

MindfulChat is not a replacement for professional mental health treatment. This application is designed to provide supportive conversations and evidence-based coping techniques, but it should not be used as a substitute for therapy, counseling, or medical treatment.

If you're experiencing a mental health crisis, please contact:

• Emergency services (911)
• National Suicide Prevention Lifeline (988)
• Crisis Text Line (Text HOME to 741741)
• Your local mental health crisis center

Always consult with qualified mental health professionals for serious mental health concerns.