💬 JoinChat — Real-Time Community Chat Platform

A lightweight real-time chat platform where users can send direct messages, create and join group conversations, and stay connected with communities — powered by Flask and Flask-SocketIO.

---

🚀 Tech Stack

Backend & API

Technology	Purpose
Flask	Python web framework
Flask-SocketIO	Real-time messaging
Flask-SQLAlchemy	ORM
Flask-Migrate	Database migrations
PyJWT	Authentication tokens
Gunicorn + Eventlet/Gevent	Production server
flask-cors	Cross-origin requests

Database & Infrastructure

Technology	Purpose
PostgreSQL	Primary database
Redis	Real-time pub/sub & socket state
Alembic	Migration engine

---

📁 Project Structure

joinchat-backend/
│
├── migrations/            # Alembic DB migrations
│
├── .env                   # Environment variables
├── models.py              # SQLAlchemy models
├── server.py              # Flask app entry point
└── requirements.txt

---

🗃️ Database Schema

Admin                         ← platform moderation

User
  ├── UserPanel (one)         ← user's message inbox/panel
  │     └── UserChat (many)   ← all messages in panel
  ├── sent_chats              ← messages sent by user
  └── received_chats          ← messages received by user

ChatGroup
  └── UserChat (many)         ← group messages (cascade delete)

UserChat
  ├── userID (sender)
  ├── recieverID (nullable)   ← null = group message
  ├── groupID (nullable)      ← null = private/direct message
  └── chat (message text)

Post
  ├── image                   ← media post (Cloudinary URL)
  └── link                    ← external link post

Chat type logic:

recieverID set, groupID null  → Private / Direct Message
groupID set, recieverID null  → Group Chat Message

---

⚙️ Environment Setup

.env

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/joinchat_db

# JWT
SECRET_KEY=your_jwt_secret_key

# Redis
REDIS_URL=redis://localhost:6379/0

# App
FLASK_ENV=development
FLASK_DEBUG=1

---

🛠️ Installation & Running

# 1. Clone the repository
git clone <repo-url>
cd joinchat-backend

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set up environment variables
cp .env.example .env
# Edit .env with your credentials

# 5. Start Redis
redis-server

# 6. Initialize database
flask db init
flask db migrate -m "initial migration"
flask db upgrade

# 7. Run the server
python server.py

---

👥 Role Hierarchy

Admin         ← platform management, moderation
  └── User    ← send/receive messages, join groups

---

📡 API Overview

🔐 Authentication — /auth

Method	Endpoint	Description
POST	/auth/register	Register new user
POST	/auth/login	Login (returns JWT)
POST	/auth/logout	Logout
GET	/auth/profile	Get own profile
PUT	/auth/profile	Update profile

---

👤 Users — /users

Method	Endpoint	Description
GET	/users	Search / list users
GET	/users/:id	Get user profile

---

💬 Direct Messages — /chat

Method	Endpoint	Description
POST	/chat/send	Send direct message
GET	/chat/:user_id	Get conversation with a user
GET	/chat/inbox	All direct message threads
DELETE	/chat/:id	Delete a message

---

👥 Group Chat — /group

Method	Endpoint	Description
POST	/group	Create a new group
GET	/group	List all groups
GET	/group/:id	Get group details + messages
PUT	/group/:id	Update group title
DELETE	/group/:id	Delete group (cascade deletes messages)
POST	/group/:id/send	Send message to group
GET	/group/:id/messages	Get all group messages

---

📋 User Panel — /panel

Method	Endpoint	Description
GET	/panel	Get own message panel
GET	/panel/chats	All messages in panel

---

📢 Posts — /posts

Method	Endpoint	Description
POST	/posts	Create a post (image or link)
GET	/posts	List all posts
GET	/posts/:id	Single post
DELETE	/posts/:id	Delete post

---

👑 Admin — /admin

Method	Endpoint	Description
POST	/admin/login	Admin login
GET	/admin/users	List all users
DELETE	/admin/user/:id	Remove user
GET	/admin/groups	List all groups
DELETE	/admin/group/:id	Delete group
GET	/admin/posts	All posts
DELETE	/admin/post/:id	Remove post

---

⚡ Real-Time Events (Flask-SocketIO)

Event	Direction	Description
connect	Client → Server	User connects
disconnect	Client → Server	User disconnects
join_group	Client → Server	Join a group chat room
leave_group	Client → Server	Leave a group chat room
send_message	Client → Server	Send message (DM or group)
receive_message	Server → Client	Receive new message
user_online	Server → Client	User came online
user_offline	Server → Client	User went offline
typing	Client → Server	User is typing indicator
stop_typing	Client → Server	Stop typing indicator

---

🚀 Deployment

Production with Gunicorn

# Eventlet worker (recommended for SocketIO)
gunicorn --worker-class eventlet -w 1 \
  --bind 0.0.0.0:5000 \
  server:app

# Or with Gevent
gunicorn --worker-class gevent -w 1 \
  --bind 0.0.0.0:5000 \
  server:app

With Nginx

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

⚠️ The Upgrade and Connection headers are required for WebSocket/SocketIO to work behind Nginx.

---

🔒 Security

• JWT-based authentication
• Admin and User roles separated
• Group message cascade delete (deletes all messages when group is deleted)
• CORS configured via flask-cors
• Credentials managed via .env

---

📊 Key Dependencies

# Web Framework
Flask==3.1.2
flask-cors==6.0.1
Flask-SocketIO==5.3.6
PyJWT==2.10.1

# Database
Flask-SQLAlchemy==3.1.1
Flask-Migrate==4.1.0
psycopg2-binary==2.9.10
alembic==1.16.5

# Real-time
redis==6.4.0
eventlet==0.40.3

# Production
gunicorn==23.0.0

---

Built with ❤️ in Bhilai, Chhattisgarh