🌟 Solace

Your Gentle Companion for Mental Wellness

A warm, supportive digital mental health platform designed with love for students. Here, your mental health matters, your feelings are valid, and you're never alone on this journey.

Features • Installation • Documentation • Deployment • Contributing

📋 Table of Contents

About
Features
Tech Stack
Getting Started
Project Structure
API Documentation
Usage Guide
Deployment
Security & Privacy
Contributing
License
Support

🎯 About Solace

Solace is a comprehensive digital mental health platform specifically designed for students. In a world where 60% of students feel overwhelmed by anxiety and 80% hesitate to seek help due to stigma, Solace provides a safe, judgment-free space for mental wellness support.

Our Mission

To provide accessible, empathetic, and effective mental health support to students worldwide, breaking down barriers and reducing stigma associated with seeking help.

Key Statistics

📊 60% of students feel overwhelmed by anxiety
💙 40% experience feelings of sadness
🚫 80% hesitate to seek help due to stigma
✅ 95% of users report feeling better after using Solace

✨ Features

🤖 AI Companion Chat

24/7 Availability: Like having a caring friend available around the clock
Instant Support: Get immediate responses to mental health concerns
Coping Strategies: Receive personalized guidance and techniques
Gentle Guidance: Empathetic AI-powered conversations powered by OpenAI GPT-3.5

📅 Safe Space Booking

Professional Counselors: Connect with licensed mental health professionals
Complete Privacy: Your conversations are protected and confidential
Easy Scheduling: Simple appointment booking system
Secure Sessions: End-to-end privacy protection

👥 Gentle Community

Peer Support Groups: Find your tribe in moderated support communities
Judgment-Free Environment: Share, listen, and grow together
Moderated Discussions: Safe spaces with community guidelines
Shared Experiences: Connect with others on similar journeys

📝 Journal & Mood Tracking

Digital Journal: Private space for thoughts and reflections
Mood Tracking: Visualize your emotional journey over time
Progress Insights: Track your mental wellness progress
Personal Growth: Identify patterns and celebrate improvements

🧘 Healing Resources

Curated Content: Carefully selected wellness materials
Breathing Exercises: Guided relaxation techniques
Meditation Guides: Mindfulness and meditation resources
Multilingual Support: Content in your preferred language

🆘 Crisis Support

24/7 Helplines: Instant access to crisis support services
Emergency Resources: Quick access to emergency contacts
Safety Protocols: Immediate support when you need it most
India-Specific: Includes Indian mental health helplines (AASRA, iCALL, YourDOST)

📊 Admin Dashboard

Institutional Analytics: Insights for educational institutions
Student Wellness Metrics: Aggregate data (privacy-preserving)
Resource Management: Manage content and resources
User Support Tools: Administrative tools for platform management

🎨 User Experience

Modern UI/UX: Beautiful, intuitive interface design
Dark/Light Mode: Theme toggle for comfortable viewing
Responsive Design: Works seamlessly on desktop and mobile
Accessibility: Built with accessibility best practices

🛠 Tech Stack

Frontend

HTML5 - Semantic markup and structure
CSS3 - Modern styling with animations and responsive design
Vanilla JavaScript - Interactive functionality and DOM manipulation
Firebase SDK (v10.7.1) - Authentication and database services

Backend

Node.js (≥18.0.0) - Runtime environment
Express.js (v4.18.2) - Web application framework
Axios (v1.6.0) - HTTP client for API requests
CORS (v2.8.5) - Cross-origin resource sharing
dotenv (v16.3.1) - Environment variable management

Services & APIs

Firebase Authentication - User authentication and authorization
Cloud Firestore - NoSQL database for user data
OpenAI GPT-3.5 - AI-powered chat companion
Render/Railway/Vercel - Deployment platforms

Development Tools

Nodemon (v3.0.1) - Development server auto-reload
http-server (v14.1.1) - Local static file serving

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (version 18.0.0 or higher)
npm (comes with Node.js) or yarn
Git (for version control)
Firebase Account (for authentication and database)
OpenAI API Key (for AI chat functionality)

Installation

Clone the repository

git clone https://github.com/yourusername/solace-main.git
cd solace-main

Install dependencies

# Install root dependencies
npm install

# Install backend dependencies
cd backend
npm install
cd ..

Set up Firebase
- Create a Firebase project at Firebase Console
- Enable Authentication (Email/Password and Google Sign-In)
- Create a Firestore database
- Copy your Firebase configuration
- Update scripts/firebase-config.js with your credentials

Configure environment variables

Create a .env file in the root directory:

# Server Configuration
PORT=3000
CORS_ORIGIN=*

# OpenAI Configuration
OPENAI_API_KEY=your-openai-api-key-here

# Firebase Configuration (optional, can be in firebase-config.js)
# FIREBASE_API_KEY=your-firebase-api-key
# FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
# FIREBASE_PROJECT_ID=your-project-id

Start the development server

# Development mode (with auto-reload)
npm run dev

# Production mode
npm start

# Or serve static files only
npm run serve

Access the application
- Open your browser and navigate to http://localhost:3000
- The landing page should load successfully

Configuration

Firebase Setup

Create Firebase Project
- Go to Firebase Console
- Click "Add project"
- Follow the setup wizard
Enable Authentication
- Navigate to Authentication → Sign-in method
- Enable Email/Password
- Enable Google Sign-In (optional but recommended)
Create Firestore Database
- Go to Firestore Database
- Click "Create database"
- Start in test mode (or configure security rules)
- Choose your preferred location
Get Configuration
- Go to Project Settings → General
- Scroll to "Your apps" section
- Click the web icon (</>)
- Copy the configuration object
Update Configuration
- Open scripts/firebase-config.js
- Replace the firebaseConfig object with your values

OpenAI API Setup

Create OpenAI Account
- Sign up at OpenAI Platform
- Add billing information (pay-as-you-go)
Generate API Key
- Go to API Keys section
- Click "Create new secret key"
- Copy the key immediately (it won't be shown again)
Set Environment Variable
- Add OPENAI_API_KEY to your .env file
- Or set it in your deployment platform's environment variables

📁 Project Structure

solace-main/
│
├── 📄 index.html                 # Landing page
├── 📄 dashboard.html             # Main user dashboard
├── 📄 auth.html                  # Authentication page (login/signup)
├── 📄 ai-chat.html              # AI chat interface
├── 📄 appointments.html          # Counselor booking page
├── 📄 journal.html               # Journaling interface
├── 📄 mood-tracker.html          # Mood tracking dashboard
├── 📄 community.html             # Community support page
├── 📄 resources.html             # Wellness resources
├── 📄 admin-dashboard.html       # Admin analytics dashboard
├── 📄 onboarding.html            # User onboarding flow
├── 📄 profile.html               # User profile page
├── 📄 contact.html               # Contact page
├── 📄 help.html                  # Help and support
├── 📄 privacy.html               # Privacy policy
├── 📄 terms.html                 # Terms of service
│
├── 📂 scripts/                   # JavaScript files
│   ├── firebase-config.js        # Firebase configuration
│   ├── landing.js                # Landing page logic
│   ├── auth.js                   # Authentication logic
│   ├── dashboard.js              # Dashboard functionality
│   ├── ai-chat.js                # AI chat interface logic
│   ├── onboarding.js             # Onboarding flow
│   ├── profile.js                # Profile management
│   ├── admin-dashboard.js        # Admin dashboard logic
│   └── pages.js                  # Shared page utilities
│
├── 📂 styles/                    # CSS stylesheets
│   ├── landing.css               # Landing page styles
│   ├── dashboard.css             # Dashboard styles
│   ├── auth.css                  # Authentication styles
│   ├── ai-chat.css               # Chat interface styles
│   ├── onboarding.css            # Onboarding styles
│   ├── profile.css               # Profile styles
│   ├── admin-dashboard.css       # Admin dashboard styles
│   └── pages.css                 # Shared page styles
│
├── 📂 backend/                   # Backend server
│   ├── server.js                 # Express server with AI chat API
│   ├── package.json              # Backend dependencies
│   └── setup.sh                  # Setup script
│
├── 📄 server.js                  # Root server file
├── 📄 package.json               # Root package configuration
├── 📄 render.yaml                # Render deployment config
├── 📄 deploy.sh                  # Deployment script
│
├── 📄 README.md                  # This file
├── 📄 DEPLOYMENT.md              # Detailed deployment guide
└── 📄 QUICK_DEPLOY.md            # Quick deployment reference

📚 API Documentation

Base URL

Development: http://localhost:3001
Production: https://your-domain.com

Endpoints

Health Check

Check if the API server is running.

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2025-01-XX",
  "service": "Solace AI Backend"
}

AI Chat

Send a message to the AI companion and receive a response.

POST /api/chat

Headers:

{
  "Content-Type": "application/json"
}

Request Body:

{
  "message": "I'm feeling anxious about my exams",
  "userId": "user-id-123",
  "conversationHistory": [
    {
      "role": "user",
      "content": "Hello"
    },
    {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    }
  ]
}

Response:

{
  "response": "I understand that exam anxiety can be really challenging...",
  "timestamp": "2025-01-XXT12:00:00Z"
}

Error Responses:

400 Bad Request

{
  "error": "Missing required field: message"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 45
}

500 Internal Server Error

{
  "error": "Internal server error",
  "message": "Failed to process chat request"
}

Rate Limiting

Limit: 10 requests per minute per IP address
Window: 60 seconds (1 minute)
Headers: Retry-After header included in 429 responses

Authentication

Currently, the API uses simple rate limiting by IP address. For production, consider implementing:

JWT token authentication
User-based rate limiting
API key authentication for admin endpoints

💻 Usage Guide

For Users

Getting Started
- Visit the landing page
- Click "Get Started" or "Begin Your Journey"
- Sign up with email/password or Google account
- Complete the onboarding process
Using AI Chat
- Navigate to the AI Chat section
- Type your message and press Enter
- The AI companion will respond with empathetic guidance
- Conversation history is maintained during your session
Booking Appointments
- Go to the Appointments page
- Browse available counselors
- Select a date and time
- Confirm your booking
Journaling
- Access the Journal section
- Write your thoughts and feelings
- Entries are saved automatically
- View your journal history
Mood Tracking
- Use the Mood Tracker to log your daily mood
- View weekly and monthly trends
- Identify patterns in your emotional well-being

For Developers

Local Development

# Start development server with auto-reload
npm run dev

# Start production server
npm start

Testing API Endpoints

# Health check
curl http://localhost:3001/health

# Chat endpoint (example)
curl -X POST http://localhost:3001/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "userId": "test-user"}'

Building for Production

# Install production dependencies
npm ci --production

# Start server
npm start

🚢 Deployment

Solace can be deployed on various platforms. We provide detailed guides for multiple options:

Quick Deploy Options

Render (Recommended) - Free Node.js hosting
Railway - Alternative free hosting
Vercel - Static + serverless functions

Detailed Deployment Guides

📖 DEPLOYMENT.md - Comprehensive deployment guide
⚡ QUICK_DEPLOY.md - Quick deployment reference

Environment Variables for Production

Make sure to set these in your deployment platform:

PORT=3000
OPENAI_API_KEY=your-production-api-key
CORS_ORIGIN=https://your-domain.com
NODE_ENV=production

Deployment Checklist

Firebase project configured
Environment variables set
OpenAI API key configured
CORS origin set correctly
Database security rules configured
Custom domain configured (optional)
SSL certificate enabled
Error tracking set up (optional)

🔒 Security & Privacy

Data Protection

Encryption: All data transmitted over HTTPS
Firebase Security: Firestore security rules protect user data
API Security: Rate limiting prevents abuse
Privacy-First: User data is not shared with third parties

Compliance

MoHFW Compliant: Aligns with Indian Ministry of Health guidelines
Privacy Policy: Comprehensive privacy policy available
Terms of Service: Clear terms and conditions
Data Retention: User data retention policies in place

Best Practices

Never commit API keys or secrets to version control
Use environment variables for sensitive configuration
Regularly update dependencies for security patches
Implement proper authentication and authorization
Monitor API usage for suspicious activity

Reporting Security Issues

If you discover a security vulnerability, please email security@solace.com (or create a private security advisory on GitHub). Do not open a public issue.

🤝 Contributing

We welcome contributions to Solace! Here's how you can help:

How to Contribute

Fork the repository

# Click the Fork button on GitHub
# Then clone your fork
git clone https://github.com/yourusername/solace-main.git

Create a branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Make your changes
- Write clean, readable code
- Follow existing code style
- Add comments where necessary
- Update documentation if needed
Test your changes
- Test locally before submitting
- Ensure no breaking changes
- Test edge cases

Commit your changes

git add .
git commit -m "feat: Add new feature description"
# Use conventional commit messages:
# feat: New feature
# fix: Bug fix
# docs: Documentation changes
# style: Code style changes
# refactor: Code refactoring
# test: Adding tests
# chore: Maintenance tasks

Push and create Pull Request

git push origin feature/your-feature-name
# Then create a PR on GitHub

Contribution Guidelines

✅ Follow the existing code style
✅ Write meaningful commit messages
✅ Update documentation for new features
✅ Add comments for complex logic
✅ Test your changes thoroughly
✅ Keep PRs focused and small
✅ Respond to code review feedback

Areas for Contribution

🌍 Localization: Add support for more languages
🎨 UI/UX Improvements: Enhance user interface and experience
🧪 Testing: Add unit and integration tests
📚 Documentation: Improve docs and add examples
🐛 Bug Fixes: Fix reported issues
✨ Features: Suggest and implement new features
🔧 Performance: Optimize code and improve performance

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 Solace AI Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🆘 Support

Crisis Support (India)

If you're experiencing a mental health crisis, please reach out to:

AASRA (24/7): 📞 9152987821
iCALL Mental Health: 📞 9820466726
National Health Helpline: 📞 104
YourDOST (Students): 📞 8448440632

Note: Solace is not a replacement for emergency medical or mental health services. If you're in immediate danger, please contact your local emergency services.

Frequently Asked Questions

Q: Is Solace free to use?
A: Yes, the basic features are free. Some premium features like 1-on-1 counseling may have associated costs.

Q: Is my data private?
A: Absolutely. We use industry-standard encryption and follow strict privacy policies. Your data is never shared with third parties.

Q: Can I use Solace anonymously?
A: Some features require an account, but you can use minimal information to sign up. We prioritize your privacy.

Q: Is Solace available in languages other than English?
A: We're working on multilingual support. Currently, resources are available in multiple languages.

Q: How accurate is the AI companion?
A: The AI is designed to provide empathetic support and general guidance, but it's not a replacement for professional therapy.

🙏 Acknowledgments

OpenAI - For providing the GPT-3.5 API that powers our AI companion
Firebase - For authentication and database services
Express.js Community - For the robust web framework
Mental Health Advocates - For inspiration and guidance
Open Source Community - For the amazing tools and libraries
Students Worldwide - For trusting us with your mental wellness journey

📊 Project Status

Current Version: 1.0.0
Status: ✅ Active Development
Last Updated: January 2026

Roadmap

Made with 💙 for Student Mental Wellness

Solace - Because your mental health matters.

Website

⭐ Star this repo if you find it helpful! ⭐

Name		Name	Last commit message	Last commit date
backend		backend
scripts		scripts
styles		styles
DEPLOYMENT.md		DEPLOYMENT.md
QUICK_DEPLOY.md		QUICK_DEPLOY.md
README.md		README.md
admin-dashboard.html		admin-dashboard.html
ai-chat.html		ai-chat.html
appointments.html		appointments.html
auth.html		auth.html
community.html		community.html
contact.html		contact.html
dashboard.html		dashboard.html
deploy.sh		deploy.sh
help.html		help.html
index.html		index.html
journal.html		journal.html
mood-tracker.html		mood-tracker.html
onboarding.html		onboarding.html
package-lock.json		package-lock.json
package.json		package.json
privacy.html		privacy.html
render.yaml		render.yaml
resources.html		resources.html
server.js		server.js
terms.html		terms.html
under-construction.html		under-construction.html

Latest commit

History

Folders and files

Repository files navigation