Pulse

⚡ Chat instantly. Share effortlessly. Stay connected.

---

🔗 Live Demo  ·  Report Bug  ·  Request Feature

---

📋 Table of Contents

• ✨ Overview
• 🎥 Demo
• 🌟 Features
• 🖥️ Tech Stack
• 📁 Project Structure
• ⚡ Real-Time Architecture
• 🔒 Auth Flow
• ⚙️ Environment Variables
• 🚀 Getting Started
• 🎯 Roadmap
• 💡 Lessons Learned
• 🤝 Contributing

---

✨ Overview

Pulse is a production-grade full-stack real-time chat app built on the MERN stack — crafted to deliver fast, beautiful, and secure messaging experiences.

Unlike barebones chat demos, Pulse is built with a real architecture:

• Optimistic UI so messages feel instant
• Socket.IO for true bi-directional, event-driven communication
• Cloudinary for image hosting
• Arcjet for security middleware
• JWT + HTTP-only cookies for bulletproof auth

Whether you're learning full-stack dev or want a solid chat foundation to build on — Pulse has you covered.

---

🎥 Demo

📸 Application Preview

📝 Sign Up	🔐 Login

💬 Chat Page	🖼️ Image Sharing

---

🌟 Features

💬 Core Messaging

Feature	Description
⚡ Real-time messaging	Powered by Socket.IO — no refresh needed
🚀 Optimistic UI	Messages appear instantly before server confirms
🖼️ Image sharing	Send images with preview before you hit send
📜 Auto-scroll	Chat always anchors to the latest message
🕒 Timestamps	Every message has human-readable time

👥 User Experience

Feature	Description
🔐 Secure Auth	JWT tokens stored in HTTP-only cookies
🟢 Online Presence	See who's online in real-time
👤 Profile Picture	Upload and update your avatar via Cloudinary
📋 Contacts List	Browse and start conversations easily
🕓 Recent Chats	Quick access to your active conversations

🎵 The Fun Stuff

Feature	Description
⌨️ Typing sounds	Satisfying keyboard clicks as you type
🔔 Notification sounds	Hear incoming messages
🔇 Toggle sounds	Turn effects on/off anytime
🎞️ Smooth animations	Polished transitions throughout

⚙️ Backend Power

Feature	Description
📡 Express REST API	Clean, modular route structure
🍃 MongoDB Atlas	Cloud-hosted database
☁️ Cloudinary	Optimized image uploads & hosting
📧 Resend Emails	Welcome emails on signup
🛡️ Arcjet	Rate limiting & security layer
🔌 Socket.IO	Full-duplex real-time events

---

🖥️ Tech Stack

Frontend

Technology	Purpose
	UI Library
	Global State Management
	Utility-first Styling
	Component Library
	HTTP Client
	Client-side Routing
	Icon Library

Backend

Technology	Purpose
	Server Runtime
	Web Framework
	Database
	ODM
	Real-time Engine
	Authentication
	Image Hosting
	API Security

---

📁 Project Structure

💜 Pulse/
│
├── 🖥️  frontend/
│   ├── 🧩  components/          # Reusable UI components
│   ├── 🪝  hooks/               # Custom React hooks
│   ├── 📄  pages/               # Route-level page components
│   ├── 🗃️  store/               # Zustand global state stores
│   ├── 🛠️  lib/                 # Utility functions & config
│   └── 🎨  assets/             # Images, sounds, static files
│
├── ⚙️  backend/
│   ├── 🎮  controllers/         # Route handler logic
│   ├── 🔒  middleware/          # Auth, error, Arcjet middleware
│   ├── 📐  models/             # Mongoose data schemas
│   ├── 🛣️  routes/             # Express API routes
│   ├── 🛠️  lib/                # DB connection, Cloudinary, utils
│   ├── 📧  emails/             # Resend email templates
│   └── 🔌  socket/             # Socket.IO setup & events
│
└── 📖  README.md

---

⚡ Real-Time Architecture

---

🔒 Auth Flow

flowchart TD
    A(["Signup / Login"])
    B["JWT Generated — HS256 Signed"]
    C["HTTP-Only Cookie — Sent to browser"]
    D{"Protected Route request?"}
    E["Auth Middleware — Verify JWT from cookie"]
    F["401 Unauthorized"]
    G["Socket Handshake — Token verified on connect"]
    H(["Connected & Online"])

    A --> B --> C --> D
    D -- Yes --> E
    D -- No --> H
    E -- Valid --> G --> H
    E -- Invalid --> F

Loading

---

⚙️ Environment Variables

Create a .env file in /backend:

# ── Server ──────────────────────────────────────
PORT=3000
CLIENT_URL=http://localhost:5173

# ── Database ─────────────────────────────────────
MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/pulse

# ── Auth ─────────────────────────────────────────
JWT_SECRET=your_super_secret_jwt_key_here

# ── Cloudinary ───────────────────────────────────
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# ── Email (Resend) ────────────────────────────────
RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxx
EMAIL_FROM=hello@yourdomain.com
EMAIL_FROM_NAME=Pulse

# ── Security (Arcjet) ─────────────────────────────
ARCJET_KEY=ajkey_xxxxxxxxxxxxxxxxxxxx

💡 Tip: Never commit your .env file. Add it to .gitignore immediately!

---

🚀 Getting Started

Prerequisites

Make sure you have these installed:

node --version   # v18+
npm --version    # v9+

You'll also need accounts for:

• MongoDB Atlas — free tier works great
• Cloudinary — free tier works great
• Resend — for welcome emails
• Arcjet — for security

1️⃣ Clone the Repository

git clone https://github.com/LovelySharma-dev/Pulse.git
cd Pulse

2️⃣ Set Up the Backend

cd backend
npm install

Create your .env file (see Environment Variables above), then:

npm run dev
# ✅ Server running at http://localhost:3000

3️⃣ Set Up the Frontend

Open a new terminal:

cd frontend
npm install
npm run dev
# ✅ App running at http://localhost:5173

4️⃣ Open the App

Navigate to http://localhost:5173 and start chatting! 🎉

---

📸 Screenshots

🔐 Login Screen

---

💬 Chat Screen

---

📋 Contacts

---

📱 Mobile View

---

🎯 Roadmap

What's coming next for Pulse 👀

• ⌨️ Typing Indicator — See when someone is typing
• ✅ Read Receipts — Know when your message is seen
• 😊 Emoji Picker — React and express yourself
• 🎙️ Voice Messages — Record and send audio
• 📹 Video Calling — Face-to-face in the browser
• 🔔 Push Notifications — Never miss a message
• 👥 Group Chats — Bring everyone together
• 🔍 Message Search — Find any conversation instantly
• ↩️ Reply to Messages — Thread-style replies
• ✏️ Edit / Delete Messages — Because typos happen
• 🌙 Dark & Light Themes — Choose your vibe

💜 Want to help build any of these? Open a PR!

---

💡 Lessons Learned

Building Pulse was a deep dive into real-world full-stack challenges. Here's what made it interesting:

⚡ Optimistic UI Updates Making messages appear instantly while the server processes them — and gracefully rolling back on failure — required careful state management with Zustand.

🔄 Real-Time Synchronization Keeping socket events, REST state, and UI in sync without stale data or race conditions taught the importance of a single source of truth.

🔌 Socket Lifecycle Management Connecting, disconnecting, and reconnecting sockets cleanly — especially across auth boundaries — is more nuanced than the docs suggest.

🖼️ Image Upload Pipeline Handling file selection → preview → base64 encoding → Cloudinary upload → URL storage in MongoDB without blocking the UI.

🔒 JWT + Cookie Auth Understanding why HTTP-only cookies beat localStorage for token storage, and how to propagate auth context to Socket.IO handshakes.

🗃️ Zustand State Design Structuring stores so that chat state, auth state, and socket state stay decoupled but reactive to each other.

🔗 REST + WebSockets Together Knowing when to use a REST call vs. a socket event — and why you often need both for the same action.

---

🤝 Contributing

Contributions are what make open source awesome. Any contributions you make are genuinely appreciated.

1. Fork the repository
2. Create your feature branch: git checkout -b feature/AmazingFeature
3. Commit your changes: git commit -m 'Add some AmazingFeature'
4. Push to the branch: git push origin feature/AmazingFeature
5. Open a Pull Request

Found a bug? Open an issue Have an idea? Start a discussion

---

⭐ Support

If Pulse helped you learn something or saved you hours of boilerplate...

Give it a star! ⭐ It genuinely helps.

---

Made with ☕ & 💜.

Happy Building 🚀