💬 PulseChat (Real-Time Microservices Chat Platform)

A highly scalable, containerized real-time chat application built with a modern microservices architecture. It utilizes event streaming, key-value presence state management, time-series message history, and high-resilience database configurations.

---

website link is : https://ConfluxChat.digitaldigimart.shop this website is run on render platform and it is take server to start upto 15 minites in first time after that 30 second to start server

🔗 Quick Access Links (When Docker Compose is running)

• 🖥️ Frontend Client (React Web UI): http://localhost:5173
• 🔌 API Gateway & Socket Server: http://localhost:3000
• 📊 Databases & Services Expose Ports:
  • Redis (Presence Store): redis://localhost:6379
  • Apache Cassandra (Database): localhost:9042
  • Apache Kafka (Event Broker): localhost:9092 (via host dual-listener)

---

🏗️ System Architecture & Data Flow

This application is split into multiple decoupled microservices communicating asynchronously via Kafka event queues, while maintaining live connection states via Redis.

graph TD
    %% Frontend
    Client[React Frontend + Tailwind] <-->|WebSocket & REST| Gateway[API Gateway / Socket Service]

    %% Gateway & Redis
    Gateway <-->|Presence Map Check| Redis[(Redis Presence Store)]
    Gateway -->|Publish Send_Message Event| Kafka[Kafka Message Broker]

    %% Kafka Consumer / Message Service
    Kafka -->|Consume Event| MsgConsumer[Message processing Service / Consumer]
    MsgConsumer <-->|Lookup Target Presence| Redis
    
    %% Delivery Paths
    MsgConsumer -->|Deliver Message Event| Gateway
    MsgConsumer -->|Trigger Push Notification| PushService[Notification Service FCM]
    PushService -->|Mock Background Push| Client

    %% Storage
    MsgConsumer -->|Persist Chat History| Cassandra[(Cassandra DB)]
    Gateway <-->|REST API: Fetch History| Cassandra

Loading

---

🛠️ Microservice Stack & Components

1. React Frontend (/frontend)

• Technology: React 19, Tailwind CSS, Vite.
• WebSocket Client: Uses socket.io-client with automatic reconnection disabled. Reconnection is handled intelligently by listening to the browser's online/offline events.
• Vessel: Containerized in Alpine Node environment, configured with dev-server binding to --host 0.0.0.0 for host browser access.

2. API Gateway Service (/backend/gateway.js)

• Technology: Node.js, Express, Socket.io, Redis Client, KafkaJS.
• Responsibilities:
  • Exposes HTTP REST API endpoints for user registration, user login, and fetching historical chats.
  • Manages active WebSocket connections from clients.
  • Updates online/offline status in Redis on connection/disconnection.
  • Publishes incoming messages to the chat-messages Kafka topic.

3. Background Message Consumer (/backend/consumer.js)

• Technology: Node.js, KafkaJS, Cassandra Driver, Redis Client.
• Responsibilities:
  • Subscribes to the chat-messages Kafka topic.
  • Persists incoming chat messages asynchronously to Apache Cassandra.
  • Queries Redis to check if the target recipient is currently online.
    • If online: Routes the message payload to the gateway-deliveries Kafka topic to deliver it to the active gateway socket.
    • If offline: Triggers a mock FCM (Firebase Cloud Messaging) background push notification.

---

🐳 How to Run (Docker Compose)

The entire application stack can be launched with a single command.

1. Startup Stack

Ensure Docker is running, then execute the following in the root folder:

docker compose up --build -d

Docker Compose will download the images, build custom images for your frontend and backend, configure the network bridge, and boot all 6 services.

2. Verify Services are Running

Check container status to confirm everything is up:

docker compose ps

3. Review Logs

To check the connection logs of the API Gateway or Consumer (e.g., verifying connection setup):

docker compose logs backend-gateway
docker compose logs backend-consumer

---

⚙️ Resilience & Reliability Enhancements

• Resilient Database Connections: Node.js services start in milliseconds, while Cassandra and Kafka can take up to 30 seconds to boot up in Docker. Both the Gateway and Consumer implement retry connection logic that retries connecting every 3 seconds up to 20 times before shutting down.
• Dual-Listener Kafka Network:
  • INTERNAL listener (kafka:9092): Used internally inside the Docker Compose bridge network.
  • EXTERNAL listener (localhost:9092 via port 9094): Exposes a channel to your host machine. This enables you to run tests and debug tools on your local host without conflicts.

---

🧪 Running Integration Tests

Integration tests verify database storage (Cassandra schema/CRUD) and presence mapping (Redis reads/writes) directly from the host.

To run tests on your host machine:

1. Navigate to the backend directory:

   cd backend

2. Install node dependencies:

   npm install

3. Run the native test runner:

   npm run test