ChatApp

A real-time chat application built with Flask and Socket.IO, featuring multiple chat rooms, message editing, emoji support, and user management.

Features

Core Functionality

• Real-time messaging using WebSocket connections via Flask-SocketIO
• Multiple chat rooms with customizable room codes (default: GLOBAL)
• Public and private rooms with dynamic room status management
• Message threading with reply functionality
• Message editing and deletion with real-time updates across all clients
• Emoji support with custom emoji picker and shortcode conversion (e.g., :smile:)
• Rich text formatting: Bold (**text**), Italic (*text*), Underline (__text__)
• Automatic URL detection and clickable link conversion
• Profanity filtering for message content
• Rate limiting to prevent spam (0.25s between messages for regular users)

User Management

• User authentication with username/password login
• Claim code system for account registration
• Two user types:
  • Regular users: Standard messaging capabilities
  • Superusers: Additional privileges including:
    • Markdown support in messages
    • Access to admin commands
    • View all registered users
    • Create claim codes for new users
    • Bypass rate limiting

Admin Features

• Command system for superusers:
  • /purge N - Delete the last N messages from the current room
• User management page displaying all registered accounts
• Claim code generation for controlled user registration

Tech Stack

Backend

• Flask 3.0.0 - Web framework
• Flask-SocketIO 5.3.6 - WebSocket support for real-time communication
• Flask-Session 0.6.0 - Server-side session management
• PyMongo 4.3.2 - MongoDB database driver
• Python-dotenv 0.20.0 - Environment variable management

Additional Libraries

• Markdown 3.4.1 - Markdown parsing for superuser messages
• filter-profanity 1.0.9 - Profanity filtering
• python-dateutil 2.8.2 - Date/time utilities
• pytz 2022.5 - Timezone support (EST)

Database

• MongoDB - Primary database for users and messages
• SQLite - Alternative database implementation (legacy support)

Installation

Prerequisites

• Python 3.10+
• MongoDB instance (local or cloud)
• pip package manager

Setup Steps

1. Clone the repository

git clone <repository-url>
cd ChatApp

2. Install dependencies

pip install -r requirements.txt

3. Create environment file

Create a .env file in the project root with the following variables:

DB_CONNECTION_STRING=mongodb://localhost:27017/
DEBUG=True
HOST=0.0.0.0
PORT=2001
SECRET_KEY=your-secret-key-here
SITE_URL=http://localhost:2001

4. Initialize the database

Run the management script to create your first superuser:

python manage.py

Select option 1 to create a new user account, and set user_type to 1 for superuser privileges.

Running the Application

Development Mode

python wsgi.py

The application will be available at http://localhost:2001 (or the port specified in your .env file).

Production Mode (Docker)

The application includes Docker support for easy deployment.

Build and run using the provided script:

./run.sh

Or manually:

# Build the Docker image
docker build -t chatapp .

# Run the container
docker run -d --name chatapp -p 2001:2001 --env-file ./.env chatapp

Database Management

The manage.py script provides utilities for database operations:

python manage.py

Available operations:

• 0 - Delete all messages from the database
• 1 - Create a new user account
• 2 - Recover a user account's password

Project Structure

ChatApp/
├── application/
│   ├── __init__.py          # Flask app factory
│   ├── api.py               # API routes for AJAX requests
│   ├── views.py             # Main view routes
│   ├── database.py          # Database models and operations
│   ├── user.py              # User model
│   ├── message.py           # Message model
│   ├── utils.py             # Utility functions and decorators
│   ├── static/              # CSS and JavaScript files
│   │   ├── base.css
│   │   ├── index.js
│   │   └── login.js
│   └── templates/           # HTML templates
│       ├── base.html
│       ├── index.html       # Main chat interface
│       ├── login.html
│       ├── users.html       # User management (superuser only)
│       ├── claim.html       # Account claiming page
│       └── emojis.html      # Emoji picker page
├── config.py                # Configuration management
├── wsgi.py                  # Application entry point
├── manage.py                # Database management script
├── requirements.txt         # Python dependencies
├── Dockerfile               # Docker configuration
├── run.sh                   # Docker deployment script
├── emojis.json             # Emoji data
└── .env                     # Environment variables (create this)

API Endpoints

Public Routes

• GET /login - Login page
• POST /login - Authenticate user
• GET /logout - Logout current user
• GET /claim_account - Account claiming page
• POST /claim_account - Claim account with code
• GET /emojis - View emoji list

Protected Routes (Requires Login)

• GET / or GET /home - Main chat interface
• GET /api/get_user - Get current user data
• GET /api/get_room_code - Get current room code
• GET /api/get_message_by_id/<msg_id> - Get specific message

Superuser Routes

• GET /users - View all registered users
• GET /create_claim_code - Create account claim code page
• POST /create_claim_code - Generate new claim code

WebSocket Events

Client → Server

• client connected - Initial connection, requests room messages
• send message - Send a new message
• on message edit - Edit an existing message
• on message delete - Delete a message
• room status update - Change room public/private status

Server → Client

• after connection - Send room messages and public room list
• new message - Broadcast new message to all clients
• message edited - Broadcast message edit to all clients
• message deleted - Broadcast message deletion to all clients
• room status changed - Broadcast room status change

Configuration

All configuration is managed through environment variables in the .env file:

Variable	Description	Example
DB_CONNECTION_STRING	MongoDB connection string	mongodb://localhost:27017/
DEBUG	Enable debug mode	True or False
HOST	Server host address	0.0.0.0
PORT	Server port	2001
SECRET_KEY	Flask secret key for sessions	your-secret-key
SITE_URL	Public URL of the application	http://localhost:2001

User Types

Regular Users (user_type = 0)

• Send and receive messages
• Edit and delete own messages
• Reply to messages
• Use emoji shortcodes and text formatting
• Join public rooms
• Subject to rate limiting (4 messages per second max)

Superusers (user_type = 1)

• All regular user capabilities
• Additional privileges:
  • Use markdown syntax in messages
  • Execute admin commands (/purge)
  • View all registered users
  • Create claim codes for new accounts
  • No rate limiting

Security Features

• Session management using Flask-Session with filesystem storage
• Password storage (Note: Passwords are stored as provided - consider adding hashing)
• HTML escaping for non-superuser messages to prevent XSS
• Profanity filtering on all messages
• Rate limiting to prevent message spam
• Claim code system for controlled registration

Browser Support

The application uses modern web technologies including:

• WebSocket (Socket.IO)
• Modern JavaScript (ES6+)
• CSS3

Recommended browsers:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

Contributing

When contributing to this project:

1. Follow the existing code style
2. Test all changes thoroughly
3. Update documentation as needed
4. Consider security implications of changes

License

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

Support

For issues, questions, or contributions, please [add contact information or issue tracker link].