A comprehensive social media and mentorship platform built with modern web technologies, featuring real-time communication, AI-powered assistance, and community building tools.

• Overview
• Features
• Tech Stack
• Architecture
• Installation
• Environment Variables
• Usage
• API Documentation
• WebSocket Events
• Development
• Deployment
• Testing
• Contributing
• License
• Support

Yuthukama is a modern full-stack social media and mentorship platform designed to connect communities through meaningful interactions. Built with React 19 and Node.js, it provides a comprehensive ecosystem for users to share knowledge, engage in real-time conversations, and participate in mentorship programs.

To create a platform where knowledge sharing, mentorship, and community building thrive through innovative technology and user-centric design.

• Real-time Communication: Instant messaging with advanced features like typing indicators, read receipts, and message reactions
• AI Integration: Powered by Gemini AI for intelligent assistance and chatbot functionality
• Social Features: Complete social media experience with posts, likes, comments, follows, and personalized feeds
• Mentorship Program: Dedicated features for connecting mentors and mentees
• Admin Dashboard: Comprehensive analytics and user management tools
• Mobile-First Design: Responsive interface optimized for all devices

• JWT-based Authentication: Secure token-based authentication system
• Password Security: Bcrypt hashing with salt rounds for password protection
• Password Reset: Email-based password recovery system
• Role-based Access: User and admin role management
• Rate Limiting: Protection against brute force attacks

• Instant Messaging: 1-on-1 conversations with Socket.IO
• Typing Indicators: Real-time typing status display
• Read Receipts: Message read status tracking
• Message Reactions: Emoji reactions on messages
• File Attachments: Support for images, documents, and media files
• Online Status: Real-time user presence indicators

• AI Chatbot: Intelligent assistant powered by Gemini AI
• Mentorship Support: AI-assisted guidance and recommendations

• Post Creation: Rich text posts with image support
• Engagement: Users can like and comment on posts.
• Follow System: Follow/unfollow users with notifications
• Personalized Feeds: "For You" and "Following" feed algorithms
• Trending Posts: Popular content discovery
• Saved Posts: Bookmark posts for later reference
• Advanced Search: Search posts by content

• User Profiles: Simple user profiles with essential details
• Follower System: Social connections and networking
• Event Announcements: Community event notifications

• Real-time Notifications: Instant notification delivery
• Multiple Types: Likes, comments, follows, mentions, messages

• Dashboard Analytics: Comprehensive platform statistics
• User Management: Admin tools for user oversight
• Content Moderation: Post and user management tools

• Responsive Design: Mobile-first approach with Material-UI
• Performance Optimization: Fast loading and smooth interactions

• React 19 - Latest React with concurrent features and improved performance
• Redux Toolkit - Redux Toolkit – Centralized state management (auth, posts, chat) with thunk-based API integration
• React Router v7 - Declarative routing with data loading capabilities
• Material-UI (MUI) v6 - Comprehensive component library with theming
• TailwindCSS - Utility-first CSS framework for rapid styling
• Socket.IO Client - Real-time bidirectional communication
• Formik & Yup - Form handling with validation schema
• Framer Motion - Animation library for smooth interactions
• Date-fns - Modern date utility library
• Recharts - Data visualization and analytics charts
• Vite - Fast build tool with hot module replacement

• Node.js - JavaScript runtime with ES modules support
• Express.js - Minimal web framework with middleware support
• Socket.IO - Real-time communication with room management
• MongoDB - NoSQL document database for flexible data storage
• Mongoose - Elegant MongoDB object modeling with validation
• JWT - JSON Web Tokens for stateless authentication
• Bcrypt - Password hashing with salt rounds
• Multer - File upload handling with memory storage
• Helmet - Security middleware for HTTP headers
• CORS - Cross-origin resource sharing configuration
• Express Rate Limit - Rate limiting middleware for API protection
• Swagger/OpenAPI - API documentation and testing

• AWS S3 - Scalable object storage for file uploads
• Gemini AI - Google's AI model for chatbot functionality
• MongoDB Atlas - Cloud-hosted MongoDB database
• Vercel - Frontend deployment and hosting platform
• AWS EC2 - Virtual servers for hosting and running backend application

• ESLint - Code linting and style enforcement
• Prettier - Code formatting (via ESLint integration)
• Nodemon - Development server with auto-restart
• PostCSS - CSS processing with TailwindCSS
• Autoprefixer - CSS vendor prefix automation

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   External      │
│   (React 19)    │    │   (Node.js)     │    │   Services      │
├─────────────────┤    ├─────────────────┤    ├─────────────────┤
│ • React Router  │◄──►│ • Express.js    │◄──►│ • MongoDB Atlas │
│ • Redux Toolkit │    │ • Socket.IO     │    │ • AWS S3        │
│ • Material-UI   │    │ • Mongoose      │    │ • Gemini AI     │
│ • Socket.IO     │    │ • JWT Auth      │    │ • Email Service │
│ • TailwindCSS   │    │ • Rate Limiting │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

src/
├── components/          # Reusable UI components
│   ├── articles/       # Article-related components
│   ├── chat/          # Chat and messaging components
│   ├── LoadingStates/ # Loading and skeleton components
│   └── Toast/         # Notification components
├── features/          # Redux feature slices
│   ├── auth/          # Authentication state management
│   ├── chat/          # Chat state management
│   ├── notifications/ # Notification state management
│   ├── posts/         # Posts state management
│   └── ui/            # UI state management
├── hooks/             # Custom React hooks
├── layouts/           # Layout components
├── pages/             # Page components
├── store/             # Redux store configuration
├── theme/             # Material-UI theme configuration
└── utils/             # Utility functions and helpers

server/
├── config/            # Configuration files
│   ├── config.js     # Environment configuration
│   ├── db.js         # Database connection
│   └── swagger.js    # API documentation setup
├── controllers/       # Route handlers and business logic
├── middleware/       # Custom middleware functions
├── models/           # Mongoose data models
├── routes/           # Express route definitions
├── utils/            # Utility functions and helpers
└── server.js         # Main server entry point

• Authentication: JWT tokens with HTTP-only cookies
• Authorization: Role-based access control (RBAC)
• Rate Limiting: Per-IP request limiting for API protection
• CORS: Configured for specific origins
• Helmet: Security headers for XSS and CSRF protection
• Input Validation: Express-validator for request validation
• Password Security: Bcrypt with salt rounds

Before installing Yuthukama, ensure you have the following installed:

• Node.js (v18.0.0 or higher) - Download here
• npm (v8.0.0 or higher) - Comes with Node.js
• MongoDB (v4.4 or higher) - Download here or use MongoDB Atlas
• Git - Download here

• AWS Account - For S3 file storage integration
• Google Cloud Account - For Gemini AI integration
• Email Service - For password reset and verification emails

1. Clone the Repository

git clone https://github.com/sameeraherath/yuthukama.git
cd yuthukama

2. Install Frontend Dependencies

cd client
npm install

3. Install Backend Dependencies

cd ../server
npm install

4. Environment Configuration

Create a .env file in the server directory with the following variables:

# Database Configuration
MONGODB_URI=mongodb://localhost:27017/yuthukama
# For MongoDB Atlas: mongodb+srv://username:[email protected]/yuthukama

# Authentication
JWT_SECRET=your_super_secret_jwt_key_here_minimum_32_characters

# Server Configuration
PORT=5000
NODE_ENV=development

# AWS S3 Configuration (Optional)
AWS_ACCESS_KEY_ID=your_aws_access_key_id
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
AWS_REGION=us-east-1
AWS_S3_BUCKET=your-s3-bucket-name

# Gemini AI Configuration (Optional)
GEMINI_API_KEY=your_gemini_api_key

# Email Configuration (Optional)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=[email protected]
EMAIL_PASS=your_app_password

5. Database Setup

For local MongoDB:

# Start MongoDB service
mongod

# Or using MongoDB Compass for GUI management

For MongoDB Atlas:

1. Create a free account at MongoDB Atlas

2. Create a new cluster

3. Get your connection string and update MONGODB_URI in .env

4. Verify Installation

Start the development servers:

# Terminal 1 - Backend
cd server
npm run dev

# Terminal 2 - Frontend
cd client
npm run dev

Visit http://localhost:5173 to see the application running.

1. Start the Backend Server

cd server
npm run dev

The backend will start on http://localhost:5000

2. Start the Frontend Development Server

cd client
npm run dev

The frontend will start on http://localhost:5173

3. Access the Application
   • Frontend: http://localhost:5173
   • Backend: http://localhost:5000
   • API Documentation: http://localhost:5000/api-docs

1. Build the Frontend

cd client
npm run build

2. Start the Production Server

cd server
npm start

1. Visit the landing page at http://localhost:5173
2. Click "Sign Up" to create a new account
3. Fill in username, email, and password
4. Verify your email (if email service is configured)
5. Login with your credentials

• Create Posts: Click the "+" button on the home screen
• Like Posts: Click the heart icon on any post
• Comment: Click the comment icon and add your thoughts
• Follow Users: Visit user profiles and click "Follow"
• Save Posts: Click the bookmark icon to save posts

• Start Conversations: Click on user profiles and select "Message"
• Send Messages: Type in the chat input and press Enter
• File Attachments: Click the attachment icon to send files

• Access AI: Click the AI assistant icon in the navigation
• Ask Questions: Type your questions and get AI-powered responses
• Mentorship Support: Ask for guidance on various topics

The application includes comprehensive API documentation powered by Swagger/OpenAPI:

• Development: http://localhost:5000/api-docs
• Production: https://your-backend-url.com/api-docs

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• GET /api/auth/check - Check authentication status
• POST /api/auth/forgot-password - Request password reset
• POST /api/auth/reset-password/:token - Reset password
• PUT /api/auth/change-password - Change password

• GET /api/users/profile - Get user profile
• PUT /api/users/username - Update username
• PUT /api/users/profile-pic - Update profile picture
• GET /api/users/search - Search users
• POST /api/users/:id/follow - Follow user
• DELETE /api/users/:id/follow - Unfollow user

• GET /api/posts - Get all posts
• POST /api/posts - Create new post
• GET /api/posts/user/:userId - Get user's posts
• PUT /api/posts/:id - Update post
• DELETE /api/posts/:id - Delete post
• PUT /api/posts/:id/like - Toggle post like
• POST /api/posts/:id/comments - Add comment

• GET /api/chat - Get user conversations
• GET /api/chat/user/:receiverId - Get/create conversation
• GET /api/chat/:conversationId/messages - Get messages
• POST /api/chat/messages - Send message
• PUT /api/chat/messages/:messageId - Edit message
• DELETE /api/chat/messages/:messageId - Delete message

• GET /api/admin/dashboard-stats - Get dashboard statistics
• GET /api/admin/users - Get all users
• PUT /api/admin/users/:userId - Update user
• DELETE /api/admin/users/:userId - Delete user

For detailed API documentation with request/response examples, see API_REFERENCE.md.

The application uses Socket.IO for real-time communication. For detailed WebSocket event documentation, see WEBSOCKET_EVENTS.md.

• authenticate - Authenticate user with Socket.IO
• join_room - Join a chat room
• leave_room - Leave a chat room
• send_message - Send a message
• typing - Indicate user is typing
• stop_typing - Stop typing indicator
• add_reaction - Add reaction to message
• mark_message_read - Mark message as read

• receive_message - Receive new message
• message_delivered - Message delivery confirmation
• message_read - Message read confirmation
• typing - User typing indicator
• stop_typing - Stop typing indicator
• user_status_change - User online/offline status
• message_reaction - Message reaction update

1. Fork and Clone

git clone https://github.com/your-username/yuthukama.git
cd yuthukama

2. Create Feature Branch

git checkout -b feature/your-feature-name

3. Make Changes

   • Follow the coding standards outlined in CONTRIBUTING.md
   • Write tests for new features
   • Update documentation as needed

4. Test Your Changes

# Frontend tests
cd client
npm run lint

# Backend tests
cd ../server
npm run lint

5. Commit and Push

git add .
git commit -m "feat: add your feature description"
git push origin feature/your-feature-name

6. Create Pull Request
   • Open a pull request on GitHub
   • Follow the PR template
   • Request review from maintainers

• Components: Reusable UI components in src/components/
• Pages: Page-level components in src/pages/
• Features: Redux slices in src/features/
• Hooks: Custom hooks in src/hooks/
• Utils: Utility functions in src/utils/

• Controllers: Business logic in server/controllers/
• Models: Database models in server/models/
• Routes: API routes in server/routes/
• Middleware: Custom middleware in server/middleware/
• Utils: Utility functions in server/utils/

# Frontend tests
cd client
npm test

# Backend tests
cd ../server
npm test

• Unit tests for utility functions
• Integration tests for API endpoints
• Component tests for React components
• End-to-end tests for critical user flows

For detailed deployment instructions, see DEPLOYMENT.md.

1. Connect your GitHub repository to Vercel
2. Set build command: npm run build
3. Set output directory: dist
4. Deploy automatically on push to main branch

1. Connect your GitHub repository
2. Set environment variables
3. Deploy automatically on push to main branch

Ensure all required environment variables are set in your deployment platform:

• MONGODB_URI - Production MongoDB connection string
• JWT_SECRET - Strong secret key for production
• AWS_ACCESS_KEY_ID - AWS credentials for file uploads
• AWS_SECRET_ACCESS_KEY - AWS secret key
• AWS_S3_BUCKET - S3 bucket name
• GEMINI_API_KEY - AI service API key

We welcome contributions from the community! Please read our Contributing Guidelines for detailed information about:

• Code of conduct
• Development workflow
• Coding standards
• Pull request process
• Issue reporting
• Community guidelines

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Write tests
5. Update documentation
6. Submit a pull request

This project is licensed under the ISC License. See LICENSE.md for details.

• Documentation: Check the comprehensive documentation in this repository
• Issues: Report bugs and request features via GitHub Issues
• Discussions: Join community discussions in GitHub Discussions

• Maintainer: Sameera Herath
• Email: [email protected]
• Project Repository: https://github.com/sameeraherath/yuthukama

• Discord: Join our Discord server (if available)
• Twitter: @Yuthukama (if available)
• LinkedIn: Yuthukama Page (if available)

Thank you for using Yuthukama! 🚀