Chatpulse

A modern, real-time chat system for WordPress that enables user-to-user communication with a self-hosted WebSocket server. Built with React, TypeScript, and Socket.IO for optimal performance and user experience.

✨ Features

🚀 Real-Time Communication

Instant messaging with WebSocket (Socket.IO) technology
Live typing indicators to show when users are composing messages
Connection status indicators for network reliability
Message delivery status (pending, sent, delivered, read)

💬 Chat Management

Private messaging between users
Group chat support (extensible for future features)
Thread-based conversations with persistent history
Message search and conversation filtering
Unread message counters and notifications

🎨 Modern UI/UX

Responsive design built with Tailwind CSS
React-powered frontend with TypeScript for type safety
Dark/light mode support (customizable)
Accessible interface following WCAG guidelines
Mobile-optimized chat experience

🔐 Security & Authentication

WordPress user integration with existing authentication
API key authentication for secure server communication
Permission-based access control for chat threads
Data sanitization and validation
Rate limiting and abuse prevention

⚡ Performance

Optimistic UI updates for instant feedback
Efficient database queries with proper indexing
WebSocket fallback to REST API when needed
Message pagination and lazy loading
Minimal resource footprint

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   React Frontend │    │  Socket.IO Server │    │ WordPress Plugin │
│                 │◄──►│                  │◄──►│                 │
│  - TypeScript   │    │  - Node.js       │    │  - PHP Classes  │
│  - Tailwind CSS │    │  - Express       │    │  - REST API     │
│  - Real-time UI │    │  - WebSocket     │    │  - Database     │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Components

WordPress Plugin (/wp-plugin/)
- REST API endpoints for chat operations
- Database management and migrations
- User authentication and permissions
- Admin interface for configuration
Socket.IO Server (/socket-server/)
- Real-time WebSocket communication
- Event handling for messages, typing, presence
- WordPress API integration
- Connection management
React Frontend (/wp-plugin/app/resources/)
- Modern chat interface
- Real-time message handling
- Optimistic UI updates
- Connection status management

📦 Installation

Prerequisites

WordPress 5.6+ with PHP 7.4+
Node.js 16+ with npm or bun
MySQL/MariaDB database
Web server (Apache/Nginx) with WebSocket support

1. WordPress Plugin Setup

# Clone the repository
git clone https://github.com/Ri2rathod/chatpulse.git
cd chatpulse

# Install plugin in WordPress
cp -r wp-plugin/ /path/to/wordpress/wp-content/plugins/chatpulse/

# Install PHP dependencies
cd /path/to/wordpress/wp-content/plugins/chatpulse/
composer install

2. Frontend Build

# Navigate to plugin directory
cd wp-plugin/

# Install dependencies
npm install
# or
bun install

# Build for production
npm run build
# or
bun run build

# For development
npm run dev
# or
bun run dev

3. Socket.IO Server Setup

# Navigate to server directory
cd socket-server/

# Install dependencies
npm install
# or
bun install

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start server
npm start
# or
bun start

# For development with auto-reload
npm run dev
# or
bun run dev

4. WordPress Configuration

Activate the plugin in WordPress admin
Run database migrations via WP-CLI or admin interface:
```
wp chatpulse migrate:run --path=/path/to/wordpress
```
Configure API settings in WordPress admin:
- Go to Settings > Chatpulse API
- Enable API access
- Generate API key
- Configure user permissions

5. Environment Configuration

Create /socket-server/.env file:

# WordPress Integration
WP_BASE_URL=https://yoursite.com
WP_API_NAMESPACE=chatpulse-chat/v1
WP_API_KEY=your_generated_api_key_here
WP_API_TIMEOUT=10000

# Server Configuration
PORT=3001
NODE_ENV=production

# CORS Configuration
CORS_ORIGIN=https://yoursite.com
CORS_METHODS=GET,POST

# Socket.IO Configuration
SOCKET_PING_TIMEOUT=60000
SOCKET_PING_INTERVAL=25000

🚀 Usage

For Users

Add the chat interface to any page/post using the shortcode:
```
[chatpulse-chat]
```
Start conversations by clicking the "New Chat" button
Send messages in real-time with typing indicators
Manage conversations from the sidebar

For Developers

REST API Endpoints

// Get user threads
GET /wp-json/chatpulse-chat/v1/threads

// Create new thread
POST /wp-json/chatpulse-chat/v1/threads

// Get thread messages
GET /wp-json/chatpulse-chat/v1/threads/{id}/messages

// Send message
POST /wp-json/chatpulse-chat/v1/threads/{id}/messages

// Update typing status
POST /wp-json/chatpulse-chat/v1/threads/{id}/typing

// Mark messages as read
POST /wp-json/chatpulse-chat/v1/threads/{id}/read

WebSocket Events

// Client to Server
socket.emit('join_thread', { thread_id: 1 });
socket.emit('send_message', { thread_id: 1, content: 'Hello!' });
socket.emit('typing', { thread_id: 1, is_typing: true });

// Server to Client
socket.on('message_received', (message) => { /* handle */ });
socket.on('typing_status', (status) => { /* handle */ });
socket.on('user_joined', (user) => { /* handle */ });

Hooks and Filters

// Customize user chat permissions
add_filter('chatpulse_user_can_access_chat', function($can_access, $user, $request) {
    return $user->has_cap('read'); // Customize logic
}, 10, 3);

// Modify thread access
add_filter('chatpulse_user_can_access_thread', function($can_access, $user_id, $thread_id, $thread) {
    return true; // Customize access logic
}, 10, 4);

// Chat message sent hook
add_action('chatpulse_message_sent', function($message, $thread, $user) {
    // Custom logic after message sent
}, 10, 3);

🔧 Development

Database Schema

The plugin creates these database tables:

wp_chatpulse_message_threads - Chat thread storage
wp_chatpulse_messages - Individual messages
wp_chatpulse_thread_participants - Thread membership (future)
wp_chatpulse_message_reactions - Message reactions (future)

CLI Commands

# Run migrations
wp chatpulse migrate:run

# Rollback migrations
wp chatpulse migrate:rollback

# Check migration status
wp chatpulse migrate:status

# Generate API key
wp chatpulse api:generate-key

# Test API connection
wp chatpulse api:test

Development Workflow

# Start WordPress development
cd wp-plugin/
bun run dev

# Start Socket.IO server development
cd socket-server/
bun run dev

# Watch for changes and auto-reload
# Frontend: Vite HMR enabled
# Backend: Nodemon for server restart

📊 Performance & Monitoring

Health Checks

WordPress Health: GET /wp-json/chatpulse-chat/v1/health
Socket.IO Health: GET http://localhost:3001/health
Server Stats: GET http://localhost:3001/stats

Monitoring

// Connection metrics
const stats = await chatService.getConnectionStats();
console.log('Active connections:', stats.connections);
console.log('Messages per second:', stats.messageRate);

🔒 Security

Best Practices

API Keys: Rotate regularly and store securely
Rate Limiting: Implement per-user message limits
Input Validation: All messages are sanitized
Permission Checks: Thread access validated per request
CORS Configuration: Restrict origins in production

Security Headers

# Apache .htaccess
Header always set X-Content-Type-Options nosniff
Header always set X-Frame-Options DENY
Header always set X-XSS-Protection "1; mode=block"

🚀 Deployment

Production Checklist

Docker Deployment (Optional)

# Example Dockerfile for Socket.IO server
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3001
CMD ["npm", "start"]

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run tests: npm test
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

Coding Standards

PHP: WordPress Coding Standards
JavaScript/TypeScript: ESLint + Prettier
CSS: Tailwind CSS utility classes
Commits: Conventional Commits specification

📜 License

This project is licensed under the GPL-2.0+ License - see the LICENSE file for details.

🙏 Acknowledgments

WordPress community for the robust platform
Socket.IO team for real-time communication
React and TypeScript teams for modern frontend tools
Tailwind CSS for utility-first styling
All contributors and users of this plugin

📞 Support

Issues: GitHub Issues
Documentation: Wiki
Community: Discussions

Made with ❤️ by Rathod Ritesh

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.vscode		.vscode
socket-server		socket-server
wp-plugin		wp-plugin
IMPLEMENTATION_COMPLETE.md		IMPLEMENTATION_COMPLETE.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
INTEGRATION_GUIDE.md		INTEGRATION_GUIDE.md
MESSAGE_STATUS_IMPLEMENTATION.md		MESSAGE_STATUS_IMPLEMENTATION.md
PRESENCE_AND_UNREAD_FEATURES.md		PRESENCE_AND_UNREAD_FEATURES.md
README.md		README.md
SCROLL_NOTIFICATION_FEATURE.md		SCROLL_NOTIFICATION_FEATURE.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
VISUAL_GUIDE_PRESENCE_UNREAD.md		VISUAL_GUIDE_PRESENCE_UNREAD.md

Ri2rathod/chatpulse

Folders and files

Latest commit

History

Repository files navigation