Real-Time Group Chat & Community System

A full-stack real-time community chat platform

Chat UI

Member Info

Account Settings

Overview

This project includes:

• backend/: Node.js + Express + Socket.io + MongoDB + Redis
• frontend/: Next.js (React) + Socket.io client + Zustand

Implemented capabilities:

• JWT auth (register, login, refresh, current user)
• Group/community management (create, join, leave, list)
• Real-time group chat with Socket.io
• Message persistence in MongoDB
• Previous message loading when entering a group
• Real-time online/offline presence
• Bonus features: typing indicators, read receipts, role-aware permissions (admin / member)

Tech Stack

• Node.js + Express + TypeScript
• Socket.io
• MongoDB (Mongoose)
• Redis (presence heartbeat + online state)
• Next.js + React + TypeScript
• Zustand + Axios

Architecture Summary

• REST API handles authentication, group CRUD flows, and message history fetch.
• Socket.io handles live messaging, group room membership, typing, read events, and presence broadcasts.
• MongoDB stores users, groups, and messages.
• Redis tracks online status with heartbeat TTL.

Project Structure

communezy/
  backend/
    src/
      modules/      # auth, group, message, user
      sockets/      # socket handlers (message, presence, typing, read, group)
      config/       # env, db, redis
  frontend/
    src/
      app/          # Next.js routes
      features/     # auth, chat, groups, users
      lib/socket/   # socket client + event contracts

Setup

1) Prerequisites

• Node.js 20+ (or 18+ with compatible npm)
• npm
• MongoDB running on 27017
• Redis running on 6379

If you prefer Docker for local databases:

cd backend/docker
docker compose up -d

2) Clone

git clone `https://github.com/programmerbanna/communezy`
cd communezy

3) Backend Environment

Create backend/.env from backend/.env.example:

PORT=5000
MONGO_URI=mongodb://127.0.0.1:27017/chat-app
REDIS_URL=redis://127.0.0.1:6379
JWT_ACCESS_SECRET=replace_with_a_strong_secret
JWT_REFRESH_SECRET=replace_with_a_different_strong_secret

4) Frontend Environment

Create frontend/.env from frontend/.env.example:

NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_SOCKET_URL=http://localhost:5000

5) Install Dependencies

cd backend
npm install

cd ../frontend
npm install

Run Locally

Open two terminals.

Terminal 1 (Backend):

cd backend
npm run dev

Terminal 2 (Frontend):

cd frontend
npm run dev

App URLs:

• Frontend: http://localhost:3000
• Backend health: http://localhost:5000/health
• Backend API docs (Swagger UI): http://localhost:5000/api/docs

API Summary

Base URL: http://localhost:5000

Auth:

• POST /api/auth/register
• POST /api/auth/login
• POST /api/auth/refresh
• GET /api/auth/me

Groups:

• POST /api/groups (create)
• POST /api/groups/:groupId/join
• POST /api/groups/:groupId/leave
• PATCH /api/groups/:groupId (admin/owner update)
• GET /api/groups/me
• GET /api/groups/all

Messages:

• GET /api/messages/:groupId/messages?cursor=<id>&limit=<n>

Interactive API Docs:

• GET /api/docs (Swagger UI)
• GET /api/docs.json (OpenAPI JSON)

Socket Events (Implemented)

Client to server:

• join_group, leave_group
• send_message
• heartbeat
• typing_start, typing_stop
• message_read

Server to client:

• receive_message
• message:delivered
• group:users
• user_online, user_offline
• typing_start, typing_stop
• message_read
• socket_error, message_error, presence_error