RC is a highly scalable, production-ready real-time chat backend built with Spring Boot 3, WebSockets, Redis Pub/Sub, and PostgreSQL.
The platform provides secure authentication, persistent data storage, and lightning-fast message delivery with support for horizontal scaling across multiple server instances.
Supports multiple authentication methods:
- Email & Password Login
- JWT-based Authentication
- Google OAuth2 Login
- Email OTP Verification
- Password Reset via OTP
- Brevo SMTP Integration
WebSocket connections are protected using:
JwtHandshakeInterceptor- Spring Security
- JWT validation
Message distribution is powered by:
- Redis Pub/Sub
- Multi-instance broadcasting
- Horizontal scaling support
Generate secure join codes:
XXX-XXX
Users can create and join rooms using these codes.
Supports one-to-one private conversations.
Messages can be upvoted safely using Redis Sets, preventing duplicate votes and race conditions.
Uses Redis Sorted Sets (ZSet) for:
- Chronological ordering
- Fast retrieval
- Real-time synchronization
Complete REST API documentation is provided using:
- Swagger UI
- OpenAPI 3.0
- Java 21
- Spring Boot 3.x
Stores:
- Users
- Chat Rooms
- Messages
- Participants
Handles:
- Pub/Sub broadcasting
- Session management
- Message indexing
- Chat history
- Upvotes
- Spring Security
- JWT (io.jsonwebtoken)
- Google Auth Library
- Springdoc OpenAPI
- Swagger UI
- Maven
src/main/java/org/godn/rc/
├── auth/
│ ├── controller/
│ ├── security/
│ └── service/
│
├── config/
│
├── entity/
│
├── redis/
│ ├── pubsub/
│ └── store/
│
└── websocket/
├── dto/
├── handlers/
├── manager/
└── router/
auth/
Responsible for:
- User registration
- Login
- Profile management
- OTP verification
- Password reset
- Google OAuth
config/
Contains:
- Redis configuration
- Security configuration
- WebSocket configuration
- OpenAPI configuration
entity/
JPA entities:
- User
- ChatRoom
- Message
- ChatParticipants
redis/
Provides:
Multi-instance message broadcasting.
Maintains:
- Hashes
- Sets
- Sorted Sets (ZSet)
for efficient chat operations.
websocket/
Responsible for:
- WebSocket handlers
- Routing actions
- DTOs
- Session management
Ensure the following are installed:
Required for Spring Boot.
Default port:
5432
Default port:
6379
Create a .env file alongside pom.xml.
Populate it using .env.example.
| Variable | Description |
|---|---|
| APP_NAME | Application name |
| DB_URL | PostgreSQL JDBC URL |
| DB_USERNAME | Database username |
| DB_PASSWORD | Database password |
| REDIS_HOST | Redis hostname |
| REDIS_PORT | Redis port |
| JWT_SECRET | Base64 encoded JWT signing key |
| GOOGLE_CLIENT_ID | Google OAuth Client ID |
| GOOGLE_CLIENT_SECRET | Google OAuth Client Secret |
| MAIL_USERNAME | SMTP username |
| MAIL_PASSWORD | SMTP password |
| SENDER_EMAIL | Email used to send OTPs |
APP_NAME=GodnRTC
DB_URL=jdbc:postgresql://localhost:5432/rc_db
DB_USERNAME=postgres
DB_PASSWORD=password
REDIS_HOST=localhost
REDIS_PORT=6379
JWT_SECRET=base64_encoded_secret
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
MAIL_USERNAME=your_brevo_username
MAIL_PASSWORD=your_brevo_password
SENDER_EMAIL=noreply@example.comUsing the Maven wrapper:
./mvnw clean install -DskipTests./mvnw spring-boot:runThe server starts on:
http://localhost:8080
Swagger UI becomes available after startup.
http://localhost:8080/swagger-ui/index.html
From there you can test:
- Registration
- Login
- Profile APIs
- OTP verification
- Password reset
Clients must provide a valid JWT during the handshake.
ws://localhost:8080/ws/chat?token=YOUR_JWT_TOKEN_HERE
The ChatWebSocketHandler routes requests based on the action field.
Supported actions:
- GET_CHATS
- CHAT
- UPVOTE
- CREATE_ROOM
- JOIN
- DIRECT_MESSAGE
{
"action": "CREATE_ROOM",
"roomType": "GROUP",
"name": "My Awesome Room"
}{
"action": "CHAT",
"roomId": "ABC-123",
"message": "Hello everyone!"
}{
"action": "UPVOTE",
"roomId": "ABC-123",
"chatId": "uuid-of-the-target-message"
}Store:
- Message metadata
- Sender information
- Chat details
Maintain:
- Chronological ordering
- Fast chat history retrieval
using timestamps as scores.
Track:
- Room members
- User participation
- Message upvotes
while ensuring atomic operations.
RC supports horizontal scaling.
User sends a WebSocket message.
↓
Message is published to Redis.
↓
Receives the event via:
RedisMessageListenerContainer
↓
Connected WebSocket sessions receive the message instantly.
Messages are identified using UUIDs.
Example:
7b49b89c-f2e4-4f31-bff1-6f8cfb7d3d14
Actions such as:
- UPVOTE
do not modify the original message.
Instead, votes are stored independently inside Redis Sets.
This approach:
- Prevents race conditions
- Avoids message corruption
- Improves scalability
- Maintains immutability
+----------------------+
| PostgreSQL |
+-----------+----------+
|
|
+------------v------------+
| Spring Boot |
|--------------------------|
| Authentication |
| REST APIs |
| WebSocket Handler |
| User Manager |
+------------+------------+
|
|
Publish / Subscribe
|
v
+--------------------------+
| Redis |
|--------------------------|
| Pub/Sub |
| Hashes |
| Sets |
| Sorted Sets (ZSet) |
+------------+-------------+
|
---------------------------------------
| |
v v
+---------------------+ +----------------------+
| Spring Instance A | | Spring Instance B |
| WebSocket Clients | | WebSocket Clients |
+---------------------+ +----------------------+
Potential additions:
- Typing indicators
- Message reactions
- Read receipts
- Presence tracking
- File uploads
- Media sharing
- Voice channels
- Push notifications
- Kafka integration
- End-to-end encryption
RC aims to provide a robust and scalable foundation for building modern chat applications with:
- Secure authentication
- Real-time communication
- Horizontal scalability
- Persistent storage
- High throughput
- Low latency
making it suitable for production-grade messaging systems.
MIT License