Your safe space for daily reflection, guided journaling, and compassionate AI support.
Buddyku is a full-stack mental health application that provides a supportive environment for users to track their emotions, journal their thoughts, and receive AI-powered emotional support through an empathetic chatbot companion named Ruby.
- Empathetic AI Support: Ruby provides warm, supportive, and encouraging responses
- Crisis Detection: Advanced suicide risk detection with appropriate crisis intervention
- Safe Space: Non-judgmental environment for emotional expression
- Crisis Resources: Malaysian mental health hotlines and support contacts
- Daily Journaling: Track emotions, moods, and daily experiences
- Memory Jar System: Organize memories by emotions (gratitude, joy, love, etc.)
- Media Attachments: Support for images, videos, and audio recordings
- Emotion Tracking: 10 core emotions including belonging, calm, comfort, gratitude, hope, joy, love, sadness, strength
- AI-Powered Mood Detection: Analyze facial expressions and text sentiment
- Suicide Risk Assessment: Advanced text analysis for mental health risk detection
- Emotional Insights: Comprehensive emotional state tracking and analysis
- Phone Integration: Twilio-powered calling system for crisis support
- Video Calling: Face-to-face communication capabilities
- Emergency Kit: Quick access to breathing exercises and crisis resources
- Framework: FastAPI with Gunicorn for production
- AI Integration: AWS Bedrock for AI chat and analysis
- Storage: AWS S3 for media attachments
- Communication: Twilio for phone services
- Database: Emotion and journal entry management
- Framework: Next.js 15 with React 19
- Styling: Tailwind CSS with custom components
- Mobile-First: Responsive design optimized for mobile devices
- Real-time: Live chat and emotion tracking
- Containerization: Docker with multi-service architecture
- Reverse Proxy: Nginx for load balancing and routing
- Production Ready: Gunicorn with optimized worker configuration
- Health Monitoring: Comprehensive health checks and monitoring
- Docker and Docker Compose
- Node.js 18+ (for local development)
- Python 3.11+ (for local development)
-
Clone the repository
git clone <repository-url> cd Buddyku
-
Environment Setup
# Backend environment variables cp backend/.env.example backend/.env # Edit backend/.env with your AWS and Twilio credentials
-
Run with Docker Compose
# Build and start all services docker-compose up --build # Access the application # Frontend: http://localhost:3000 # Backend API: http://localhost:8000 # API Docs: http://localhost:8000/docs
-
Backend Development
cd backend pip install -r requirements.txt uvicorn main:app --reload -
Frontend Development
cd frontend npm install npm run dev
- Welcome screen with Buddyku branding
- Quick access to main features
- AI chat interface with Ruby
- Real-time conversation with empathetic responses
- Crisis detection and intervention
- Calendar view of journal entries
- Daily mood and emotion tracking
- Media attachment support
- Emergency breathing exercises
- Emotion jar system for memory organization
- Visual representation of emotional memories
- Random memory popup for reflection
- User settings and preferences
- Personal information management
- Face-to-face communication
- Real-time video streaming capabilities
POST /api/chat- AI chat with RubyPOST /api/detect-suicide- Suicide risk detectionPOST /api/mood-detection- Mood analysis from imagesPOST /uploadEmotionsS3- Upload journal entriesPOST /fetch-all-emotions- Retrieve user emotions
POST /phone/call- Make phone callsGET /phone/call/{call_sid}/status- Check call statusGET /phone/calls- List recent calls
GET /health- Backend health checkGET /phone/health- Phone service health
- FastAPI - Modern Python web framework
- Gunicorn - Production WSGI server
- AWS Bedrock - AI/ML services
- AWS S3 - File storage
- Twilio - Communication services
- Boto3 - AWS SDK
- Next.js 15 - React framework
- React 19 - UI library
- Tailwind CSS - Styling
- TypeScript - Type safety
- Lucide React - Icons
- Docker - Containerization
- Nginx - Reverse proxy
- Docker Compose - Orchestration
# AWS Configuration
AWS_ACCESS_KEY_ID=your_aws_key
AWS_SECRET_ACCESS_KEY=your_aws_secret
S3_BUCKET_NAME=your_s3_bucket
S3_REGION=ap-southeast-1
# Twilio Configuration
TWILIO_ACCOUNT_SID=your_twilio_sid
TWILIO_AUTH_TOKEN=your_twilio_token
TWILIO_FROM_NUMBER=your_twilio_number
# Bedrock Configuration
AWS_REGION=ap-southeast-1- Launch EC2 Instance (Recommended: t3.xlarge for production)
- Install Docker and Docker Compose
- Configure Security Groups (ports 80, 443, 22)
- Deploy Application:
# Copy application files scp -r . ubuntu@your-ec2-ip:~/buddyku/ # SSH and start services ssh ubuntu@your-ec2-ip cd ~/buddyku docker-compose up -d
- HTTPS: Use ngrok or ALB for HTTPS support
- Domain: Configure custom domain with SSL
- Monitoring: Set up CloudWatch or similar monitoring
- Backup: Regular S3 backups for user data
# Health check
curl http://localhost:8000/health
# Chat with Ruby
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{"message": "Hello Ruby", "message_history": []}'cd frontend
npm run dev
# Visit http://localhost:3000- Backend Health:
GET /health - Phone Service:
GET /phone/health - Docker Health: Built-in health checks for all services
- Resource Monitoring: Memory and CPU limits configured
- Fork the repository
- Create a feature branch
- Make your changes
- Test thoroughly
- Submit a pull request
Malaysian Mental Health Resources:
- Malaysian Mental Health Association (MMHA): +603-2780-6803
- Befrienders Kuala Lumpur: +603-7627-2929
- Talian Kasih (National Hotline): 15999
For technical support or questions about Buddyku, please open an issue in the repository.
Buddyku - Your compassionate companion for mental wellness 🌟