React-gRPC Chat Application

JUL 2025

Overview

The React-gRPC Chat Application is a full-stack, real-time chat platform designed to showcase modern web communication patterns using gRPC streaming. Unlike traditional chat solutions relying on WebSockets, this project leverages gRPC-Web to deliver efficient, type-safe, and bidirectional streaming directly between browser clients and a Node.js backend.

This project demonstrates how gRPC can be used for real-time web applications, providing benefits like automatic code generation, Protocol Buffers for serialization, and streaming APIs, all while maintaining clean separation of concerns and scalable infrastructure.

Architecture

The system implements a microservices architecture with real-time communication through gRPC streaming:

All components communicate using Protocol Buffers for efficient serialization and type-safe contracts across the entire system.

Key Features

Real-Time Messaging with gRPC Streaming

The application uses bidirectional gRPC streaming for instant message delivery:

• Server-side streaming for continuous message flow
• Client-side streaming for efficient message sending
• No WebSocket dependencies - pure gRPC communication
• Type-safe message contracts via Protocol Buffers

Live User Management

Real-time user presence and management features:

• User registration with avatar support
• Live user list displaying currently connected users
• Join/leave notifications streamed to all clients
• Persistent user state management through Redis

Modern Frontend Architecture

Built with contemporary web technologies:

• React 19+ with functional components and hooks
• TypeScript for complete type safety
• Material-UI (MUI) for responsive, accessible design
• Auto-generated gRPC client code from Protocol Buffer definitions

Implementation Details

Protocol Buffer Service Definition

The chat service defines streaming RPCs for real-time communication:

syntax = "proto3";

package randomPackage;

service ChatService {
  rpc ChatInitiate(User) returns (User); // Initiate the session by joining the chat room
  rpc SendMessage(ChatMessage) returns (google.protobuf.Empty); // Send a chat message
  rpc UserStream(google.protobuf.Empty) returns (stream User); // Receive list of connected users in real time
  rpc ChatStream(google.protobuf.Empty) returns (stream ChatMessage); // Receive chat messages in real time
}

message User {
  string username = 1;
  int32 id = 2;
  string avatar = 3;
  bool joined = 4;
}

message ChatMessage {
  string username = 1;
  string message = 2;
  string timestamp = 3;
  int32 userId = 4;
}

Backend gRPC Server Implementation

The Node.js backend implements the ChatService with sophisticated real-time streaming capabilities. The server architecture centers around Redis pub/sub integration to enable scalable message broadcasting across multiple connected clients.

When users join the chat, the ChatInitiate RPC assigns unique identifiers, stores user data in memory, and publishes join events to Redis. This triggers real-time notifications to all connected clients through active user streams.

The SendMessage RPC handles incoming messages by adding timestamps, persisting to in-memory storage, and broadcasting through Redis pub/sub channels. This ensures instant delivery to all subscribers without requiring direct client-to-client connections.

The streaming RPCs (UserStream and ChatStream) maintain persistent connections with clients. They subscribe to Redis channels and forward updates in real-time, handling connection lifecycle events like cancellation and cleanup to prevent memory leaks.

Frontend React Implementation

The React frontend leverages auto-generated gRPC-Web client stubs to communicate seamlessly with the backend services. The application initializes a ChatServiceClient instance targeting the Envoy proxy endpoint, which handles the gRPC-Web to gRPC translation.

The main chat component manages real-time state through React hooks, maintaining separate state arrays for messages and connected users. Upon mounting, the component establishes persistent streaming connections for both chat messages and user updates using the generated client methods.

The ChatStream subscription continuously receives new messages and updates the local state, triggering automatic UI re-renders for instant message display. Similarly, the UserStream maintains a live user list by handling join/leave events and updating user presence indicators.

Message sending utilizes the unary SendMessage RPC with optimistic UI updates and error handling. The component properly manages stream lifecycle, canceling subscriptions during cleanup to prevent memory leaks and connection buildup.

Envoy Proxy Configuration

Envoy serves as the critical translation layer between browser-based gRPC-Web clients and the standard gRPC server. The proxy configuration establishes HTTP/2 listeners with comprehensive CORS support to handle cross-origin requests from the React development server.

The proxy implements intelligent routing that forwards all incoming gRPC-Web requests to the backend gRPC server while preserving streaming semantics. It handles protocol translation by converting HTTP/1.1 and HTTP/2 gRPC-Web calls into native gRPC format that the Node.js server expects.

Envoy's configuration includes specialized filters for gRPC-Web processing, CORS handling, and request routing. The setup enables bidirectional streaming by maintaining persistent connections and properly forwarding stream events in both directions.

The load balancing configuration targets the dockerized gRPC server with appropriate timeouts and connection pooling. This architecture ensures seamless communication while abstracting the complexity of gRPC-Web protocol handling from both the frontend and backend implementations.

Docker Orchestration

The system employs a comprehensive Docker Compose orchestration strategy that manages four critical services in a coordinated startup sequence. The Envoy proxy container serves as the entry point, configured with custom YAML settings that enable gRPC-Web translation and CORS support for browser compatibility.

The Redis container utilizes the Bitnami image with persistent volume mounting to ensure message pub/sub state survives container restarts. Environment variables configure Redis for development use with simplified authentication, while production deployments would implement proper security credentials.

The gRPC server container builds from the Node.js TypeScript source with multi-stage Docker builds optimizing image size and security. The container exposes the gRPC port internally to the Docker network while connecting to Redis through container hostname resolution.

Dependency management ensures services start in the correct order: Redis first, then the gRPC server, and finally Envoy proxy. Health checks and restart policies maintain system resilience, while shared networks enable seamless inter-service communication using container names as DNS entries.

Getting Started

Prerequisites

Ensure you have the following installed:

• Node.js (v16+) and npm/yarn
• Docker and Docker Compose
• Protocol Buffers Compiler (protoc)
• protoc-gen-js and protoc-gen-grpc-web plugins

Quick Start

1. Clone and setup backend:

git clone https://github.com/A-KGeorge/grpc-realtime-chat.git
cd grpc-realtime-chat/backend

# Install dependencies and start infrastructure
npm install
docker-compose up -d

# Generate Protocol Buffer files
npm run proto:gen

# Start gRPC server
npm start

2. Setup frontend:

cd ../frontend

# Install dependencies and start React app
npm install
npm start

3. Access the application:

• Frontend: localhost:3000
• gRPC Server: localhost:8082
• Envoy Proxy: localhost:8080

Development Workflow

Protocol Buffer regeneration:

# Unix/Linux/Mac
npm run proto:gen

# Windows PowerShell
npm run win:proto:gen

Multi-user testing:

For testing with multiple users, use different browsers or incognito windows due to HTTP/2 connection limits per origin in the same browser session.

Technical Achievements

Advanced Streaming Patterns

• Bidirectional streaming: Real-time message and user event streams
• Server-side streaming: Continuous data flow from server to clients
• Connection management: Graceful handling of stream lifecycle
• Error handling: Robust error recovery and reconnection logic

Production-Ready Infrastructure

• Containerized deployment: Docker Compose orchestration
• Proxy layer: Envoy for gRPC-Web translation
• Message broker: Redis pub/sub for scalable real-time updates
• Type safety: End-to-end TypeScript with generated gRPC types

Modern Web Patterns

• React Hooks: Functional components with state management
• Material Design: Responsive, accessible UI components
• Real-time UX: Instant feedback and live user presence
• Progressive enhancement: Graceful degradation for network issues

Future Enhancements

Authentication & Security

• JWT-based authentication with refresh tokens
• OAuth integration (Google, GitHub, Discord)
• Role-based access control and permissions
• Message encryption and secure communication

Scalability & Performance

• Kubernetes deployment with horizontal scaling
• Database integration for persistent message history
• Message pagination and infinite scrolling
• Connection pooling and load balancing

Feature Expansion

• Direct messaging and private channels
• File and media sharing capabilities
• Message reactions and threading
• Push notifications for offline users

Demo video

Loading demo...

Real-time chat demo showing multiple users sending messages with live user presence indicators

Loading demo content...

Resources & Links

Conclusion

The React-gRPC Chat Application demonstrates that gRPC can effectively replace WebSockets for real-time web applications while providing superior type safety, code generation, and protocol efficiency. This project showcases modern patterns for building scalable, real-time communication systems using cutting-edge web technologies.

Whether you're learning about real-time streaming, exploring gRPC-Web capabilities, or building production chat systems, this project provides a solid foundation with production-ready patterns, comprehensive Docker orchestration, and modern React architecture.

Built to showcase the future of real-time web communication through gRPC streaming and modern JavaScript frameworks.