Skip to content

Commit 3916737

Browse files
Wcoder547Wcoder547
authored
Update README.md
1 parent 152a6d9 commit 3916737

1 file changed

Lines changed: 248 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 248 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,248 @@
1-
# MERN-CHAT-APP
2-
A real-time chat app built with the MERN stack and WebSockets. Includes secure authentication, private/group messaging, instant updates via Socket.io, and a responsive UI for seamless communication.
1+
# MERN Chat App
2+
3+
> Real-time full-stack chat application built with the MERN stack, Socket.io, and Docker.
4+
5+
![Node.js](https://img.shields.io/badge/Node.js-18+-green) ![React](https://img.shields.io/badge/React-18-blue) ![Socket.io](https://img.shields.io/badge/Socket.io-4-black) ![Docker](https://img.shields.io/badge/Docker-ready-blue) ![License](https://img.shields.io/badge/license-MIT-green)
6+
7+
---
8+
9+
## What is this?
10+
11+
A production-ready chat application that lets users exchange messages in real time. It supports private one-on-one conversations and group messaging, with secure JWT-based authentication and instant delivery via WebSockets.
12+
13+
Built as a full-stack project to demonstrate real-world usage of the MERN stack alongside Socket.io event handling, CI/CD pipelines, structured logging with Winston, and containerized deployment with Docker.
14+
15+
---
16+
17+
## Features
18+
19+
- **Real-time messaging** — instant delivery via Socket.io WebSockets
20+
- **Authentication** — JWT-based secure login and registration
21+
- **Private & group chats** — one-on-one and multi-user rooms
22+
- **Persistent history** — messages stored in MongoDB
23+
- **Structured logging** — Winston file and console transports
24+
- **Dockerized** — single `docker-compose up` to run the full stack
25+
- **CI/CD** — GitHub Actions pipeline for automated builds
26+
27+
---
28+
29+
## Preview
30+
31+
```
32+
User A Server User B
33+
|--- send message -------->| |
34+
| |--- socket.emit('msg') --->|
35+
| |--- save to MongoDB --------|
36+
|<--- acknowledgment ------| |
37+
```
38+
39+
---
40+
41+
## Tech Stack
42+
43+
| Layer | Technology |
44+
|------------|-------------------------------------|
45+
| Frontend | React 18, Vite, Socket.io-client |
46+
| Backend | Node.js, Express, Socket.io |
47+
| Database | MongoDB, Mongoose |
48+
| Auth | JWT, bcrypt |
49+
| Logging | Winston |
50+
| DevOps | Docker, Docker Compose, GitHub Actions |
51+
52+
---
53+
54+
## Getting Started
55+
56+
### Prerequisites
57+
58+
- Node.js 18+
59+
- MongoDB (local or Atlas URI)
60+
- Docker & Docker Compose (optional but recommended)
61+
62+
### Option 1 — Docker (recommended)
63+
64+
```bash
65+
git clone https://github.com/Wcoder547/MERN-CHAT-APP.git
66+
cd MERN-CHAT-APP
67+
```
68+
69+
Create a `.env` file in the root:
70+
71+
```env
72+
MONGO_URI=mongodb://mongo:27017/chatapp
73+
JWT_SECRET=your_jwt_secret
74+
PORT=5000
75+
CLIENT_URL=http://localhost:3000
76+
```
77+
78+
Then run:
79+
80+
```bash
81+
docker-compose up --build
82+
```
83+
84+
App will be live at `http://localhost:3000`.
85+
86+
---
87+
88+
### Option 2 — Manual
89+
90+
**Backend**
91+
92+
```bash
93+
cd Back-end
94+
npm install
95+
npm run dev
96+
```
97+
98+
**Frontend** (in a separate terminal)
99+
100+
```bash
101+
cd Front-end
102+
npm install
103+
npm run dev
104+
```
105+
106+
---
107+
108+
## Project Structure
109+
110+
```
111+
MERN-CHAT-APP/
112+
├── Back-end/
113+
│ ├── controllers/ # Route handlers
114+
│ ├── models/ # Mongoose schemas (User, Message, Room)
115+
│ ├── routes/ # Express route definitions
116+
│ ├── socket/ # Socket.io event handlers
117+
│ ├── middleware/ # Auth middleware, error handling
118+
│ └── utils/ # Winston logger config
119+
├── Front-end/
120+
│ ├── src/
121+
│ │ ├── components/ # Reusable UI components
122+
│ │ ├── pages/ # Route-level page components
123+
│ │ ├── context/ # Auth and socket context providers
124+
│ │ └── hooks/ # Custom React hooks
125+
└── docker-compose.yml
126+
```
127+
128+
---
129+
130+
## Environment Variables
131+
132+
| Variable | Description | Example |
133+
|--------------|------------------------------------|----------------------------------|
134+
| `MONGO_URI` | MongoDB connection string | `mongodb://localhost:27017/chat` |
135+
| `JWT_SECRET` | Secret key for signing JWTs | `supersecretkey` |
136+
| `PORT` | Backend server port | `5000` |
137+
| `CLIENT_URL` | Allowed CORS origin (frontend URL) | `http://localhost:3000` |
138+
139+
---
140+
141+
## Socket Events
142+
143+
| Event | Direction | Payload | Description |
144+
|-------------------|-------------------|--------------------------------|-------------------------------------|
145+
| `sendMessage` | Client → Server | `{ roomId, message, sender }` | Send a new message |
146+
| `receiveMessage` | Server → Client | `{ message, sender, time }` | Broadcast message to room members |
147+
| `joinRoom` | Client → Server | `{ roomId }` | Join a specific chat room |
148+
| `userOnline` | Server → Client | `{ userId }` | Notify room of a user coming online |
149+
| `userOffline` | Server → Client | `{ userId }` | Notify room of a user going offline |
150+
151+
---
152+
153+
## API Endpoints
154+
155+
### Auth
156+
157+
| Method | Route | Description |
158+
|--------|--------------------|---------------------|
159+
| POST | `/api/auth/register` | Register a new user |
160+
| POST | `/api/auth/login` | Login, returns JWT |
161+
162+
### Messages
163+
164+
| Method | Route | Description |
165+
|--------|-------------------------------|--------------------------------|
166+
| GET | `/api/messages/:roomId` | Fetch message history for room |
167+
| POST | `/api/messages` | Save a new message |
168+
169+
### Rooms
170+
171+
| Method | Route | Description |
172+
|--------|---------------------|-----------------------|
173+
| GET | `/api/rooms` | List all rooms |
174+
| POST | `/api/rooms` | Create a new room |
175+
| GET | `/api/rooms/:id` | Get a specific room |
176+
177+
All protected routes require the `Authorization: Bearer <token>` header.
178+
179+
---
180+
181+
## Logging
182+
183+
Winston is configured with two transports:
184+
185+
- **Console** — development output with colorized levels
186+
- **File** — `logs/combined.log` for all levels, `logs/error.log` for errors only
187+
188+
Log levels follow standard severity: `error > warn > info > http > debug`.
189+
190+
---
191+
192+
## CI/CD
193+
194+
GitHub Actions workflow (`.github/workflows/`) runs on every push to `main`:
195+
196+
1. Builds Docker images for frontend and backend
197+
2. Runs tests
198+
3. Pushes updated images to the container registry
199+
200+
---
201+
202+
## Caveats & Limitations
203+
204+
- No end-to-end message encryption (messages stored as plaintext in MongoDB)
205+
- File/media sharing not yet supported
206+
- No read receipts
207+
- Horizontal scaling requires a Redis adapter for Socket.io (not currently configured)
208+
209+
---
210+
211+
## Roadmap
212+
213+
- [ ] Read receipts
214+
- [ ] Media/file uploads (Cloudinary)
215+
- [ ] Redis adapter for multi-instance Socket.io
216+
- [ ] React Native mobile client
217+
218+
---
219+
220+
## Local Development Tips
221+
222+
- Use [MongoDB Compass](https://www.mongodb.com/products/compass) to inspect collections during development
223+
- Socket.io events can be debugged by setting `localStorage.debug = 'socket.io-client:socket'` in the browser console
224+
- Winston logs land in `Back-end/logs/` — tail them with `tail -f Back-end/logs/combined.log`
225+
226+
---
227+
228+
## Contributing
229+
230+
1. Fork the repo
231+
2. Create your branch: `git checkout -b feature/your-feature`
232+
3. Commit your changes: `git commit -m 'feat: add your feature'`
233+
4. Push to the branch: `git push origin feature/your-feature`
234+
5. Open a Pull Request
235+
236+
---
237+
238+
## Author
239+
240+
**Waseem** — [@Wcoder547](https://github.com/Wcoder547)
241+
242+
Full-stack developer · MERN · Next.js · TypeScript
243+
244+
---
245+
246+
## License
247+
248+
[MIT](LICENSE)

0 commit comments

Comments
 (0)