FreqChat

A real-time frequency-based chat application built with Spring Boot and WebSocket. Users can join different frequency channels (87.0 - 108.0 MHz) and chat with others on the same frequency.

Features

• Frequency-based Channels: Join any frequency between 87.0 and 108.0 MHz
• Real-time Messaging: WebSocket-based instant messaging
• Multi-instance Support: Redis pub/sub for horizontal scaling
• User Management: Automatic nickname generation and user lists per frequency
• Moderation:
  • Rate limiting (3 messages per second)
  • Profanity filter with automatic muting
  • 10-second mute duration for violations
• Privacy: No auto frequency finder - users manually select their frequency
• Responsive Design: Works on desktop and mobile devices

Tech Stack

• Java 17+
• Spring Boot
• Spring WebSocket
• Redis (for pub/sub messaging across instances)
• No Database - Ephemeral in-memory storage

Architecture

• WebSocket Handler: Manages WebSocket connections and message handling
• Frequency Manager: Tracks users and sessions per frequency channel
• Redis Subscriber: Distributes messages across multiple application instances
• Moderation System: Rate limiting and content filtering

Privacy Note

An auto frequency finder feature was previously implemented but was removed for privacy reasons. Users must manually select their frequency to join a channel.

Running with Docker

Prerequisites

• Docker Desktop
• Docker Compose

Quick Start

1. Build and start the application:

docker-compose build --no-cache app
docker-compose up -d

2. Access the application:

http://localhost:8080

-With multiple devices in same network:
    http://yourIpv4address:8080

-Testing with global link(temprorary link - not permanent):
    https://freqchat-production.up.railway.app/

3. To update after code changes:

docker-compose build --no-cache app
docker-compose up -d app

Configuration

Redis Configuration

The application uses Redis for pub/sub messaging. Configure Redis connection in application.properties:

spring.redis.host=redis
spring.redis.port=6379

For local development without Docker, set:

spring.redis.host=localhost

Banned Words Dictionary

The profanity filter uses an external dictionary file to keep banned words out of the source code. This file is gitignored for privacy and customization.

Setup:

2. Customize banned-words.dict as needed for your deployment.

File Format:

• One word or pattern per line
• Lines starting with # are comments and ignored
• Simple words are automatically wrapped with word boundaries
• Lines starting with regex: are treated as full regex patterns

Note: The banned-words.dict file is gitignored and will not appear in your repository.

Development

Requirements

• Java 17 or higher
• Maven
• Redis (for multi-instance support)

Build

./mvnw clean package

Run

./mvnw spring-boot:run

License

This project is open source and available for use.