Your AI-Powered Mental Health Companion
ChillBuddy is an innovative mental health support application that combines AI-driven conversations, gamification, and comprehensive resources to provide accessible mental health support. Built for the South African Intervarsity Hackathon 2025, ChillBuddy aims to make mental health care more approachable and engaging for young adults.
- 🤖 AI Chat Support: Intelligent conversational AI that provides empathetic mental health support
- 📊 Mood Tracking: Visual mood tracking with insights and patterns
- 🏆 Gamification: Achievement system with badges and progress tracking
- 📚 Resource Library: Curated mental health resources and crisis support
- 🎯 Goal Setting: Personal wellness goals with progress monitoring
- 🔒 Privacy-First: Secure, confidential conversations with data protection
- 📱 Responsive Design: Works seamlessly across desktop and mobile devices
├── assets/ # Project assets and media
├── demo/ # Demo videos and presentations
├── docs/ # Project documentation
├── src/
│ ├── backend/ # Python Flask backend
│ │ ├── app.py # Main application server
│ │ ├── conversation.py # AI conversation logic
│ │ ├── gamification.py # Achievement system
│ │ ├── resources.py # Mental health resources
│ │ └── models/ # Data models
│ └── frontend/ # HTML/CSS/JS frontend
│ ├── index.html # Main application interface
│ ├── css/ # Styling and themes
│ └── js/ # Client-side functionality
├── scripts/ # Utility and deployment scripts
└── vendor/ # Third-party dependencies
Backend:
- Python 3.8+
- Flask web framework
- OpenAI GPT API for conversational AI
- SQLite for data persistence
- JSON-based configuration
Frontend:
- Vanilla HTML5, CSS3, JavaScript
- Responsive CSS Grid and Flexbox
- Modern ES6+ JavaScript features
- CSS custom properties for theming
Development:
- Git version control
- Docker containerization support
- Cross-platform compatibility
-
Clone the repository
git clone https://github.com/yourusername/chillbuddy.git cd chillbuddy -
Set up the backend
cd src/backend pip install -r requirements.txt python app.py -
Launch the frontend
cd src/frontend python -m http.server 8000 -
Open your browser Navigate to
http://localhost:8000
For detailed setup instructions, see SETUP.md.
- Setup Guide - Complete installation and configuration
- Usage Guide - How to use ChillBuddy features
- Team Information - Meet the development team
- Acknowledgements - Credits and references
- Empathetic AI: Trained responses for mental health support
- Context Awareness: Maintains conversation history and user preferences
- Safety Filters: Built-in crisis detection and appropriate responses
- Personalization: Adapts to individual user communication styles
- Daily Mood Logging: Simple, intuitive mood entry system
- Visual Analytics: Charts and graphs showing mood patterns
- Insight Generation: AI-powered observations about mental health trends
- Goal Progress: Track wellness objectives and milestones
- Achievement Badges: Unlock rewards for consistent engagement
- Progress Levels: Advance through wellness journey stages
- Sharing Features: Celebrate achievements with community
- Motivation Tracking: Maintain engagement through positive reinforcement
- Curated Content: Professional mental health resources
- Crisis Support: Emergency contacts and immediate help options
- Educational Materials: Articles, videos, and self-help guides
- Local Resources: South African mental health services and contacts
ChillBuddy prioritizes user privacy and data security:
- Local Data Storage: Sensitive information stored locally when possible
- Encrypted Communications: All API communications use HTTPS
- Minimal Data Collection: Only essential data is collected and processed
- User Control: Users can delete their data at any time
- Compliance: Follows best practices for mental health data handling
- Multi-language Support: Designed for South African linguistic diversity
- Cultural Sensitivity: Culturally appropriate mental health approaches
- Accessibility Features: Screen reader compatible, keyboard navigation
- Mobile-First Design: Optimized for smartphones and tablets
- Low-Bandwidth Friendly: Efficient loading for various internet speeds
- Python 3.8 or higher
- Modern web browser (Chrome, Firefox, Safari, Edge)
- Internet connection for AI features
- OpenAI API key (for full functionality)
-
Clone and navigate to the project
git clone https://github.com/yourusername/chillbuddy.git cd chillbuddy -
Install backend dependencies
cd src/backend pip install -r requirements.txt -
Configure environment variables
cp config.py.example config.py # Edit config.py with your API keys -
Start the application
# Terminal 1: Start backend python app.py # Terminal 2: Start frontend server cd ../frontend python -m http.server 8000
-
Access the application Open your browser to
http://localhost:8000
docker build -t chillbuddy .
docker run -p 8000:8000 chillbuddyRun the test suite to ensure everything is working correctly:
cd src/backend
python run_tests.py- ✅ Core AI conversation system
- ✅ Mood tracking functionality
- ✅ Gamification and achievements
- ✅ Resource library
- ✅ Responsive UI design
- ✅ Crisis support integration
- 🔄 Advanced analytics (in progress)
- 🔄 Mobile app version (planned)
We welcome contributions to ChillBuddy! Please read our contributing guidelines and feel free to submit issues and pull requests.
This project is licensed under the MIT License - see the LICENSE file for details.
- South African Intervarsity Hackathon 2025 organizers
- Open source community for tools and libraries
- My AI coding assistant, Trae
Built with ❤️ for mental health awareness and support
ChillBuddy - Making mental health support accessible, engaging, and effective for everyone.