Realtime Chat API

Realtime chat API built with FastAPI, WebSockets and Redis pub/sub.

Live Demo

API available at: https://realtime-chat-production-3725.up.railway.app

Interactive documentation: https://realtime-chat-production-3725.up.railway.app/docs

Test the chat in production

1. Register a user at /docs
2. Login and copy the access_token
3. Open test_chat.html in two browser tabs
4. Paste the token in each tab and click Connect
5. Start chatting in realtime

Note: This API is hosted on Railway's free tier. The first request may take a few seconds to respond.

Tech Stack

• FastAPI — Python web framework
• WebSockets — Realtime bidirectional communication
• Redis — Pub/sub message broker
• PostgreSQL — Message persistence
• SQLAlchemy — ORM
• bcrypt — Password hashing
• python-jose — JWT tokens
• Docker — Containerization
• pytest — Testing

Features

• JWT authentication
• Realtime messaging with WebSockets
• Multiple chat rooms
• Message persistence in PostgreSQL
• Redis pub/sub for message broadcasting

Getting Started

Prerequisites

• Docker
• Docker Compose
• Python 3.12+

Run the project

# Clone the repository
git clone git@github.com:vanDevBett/realtime-chat.git
cd task-manager-api

# Create the environment file
cp .env.example .env

# Create and activate virtual environment

# Mac / Linux
python3 -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
venv\Scripts\activate

# Start the containers
docker compose up --build

API available at http://localhost:8000

Interactive documentation at http://localhost:8000/docs

Test the chat

Open test_chat.html in two browser tabs, register two users, paste their tokens and start chatting in realtime.

API Endpoints

Auth

Method	Endpoint	Description	Auth
POST	/auth/register	Register a new user	No
POST	/auth/login	Login and get JWT token	No

Chat

Method	Endpoint	Description	Auth
GET	/chat/rooms/{room}/messages	Get room message history	No
WS	/chat/ws/{room}?token=xxx	Connect to a chat room	JWT

WebSocket Usage

const ws = new WebSocket('ws://localhost:8000/chat/ws/general?token=YOUR_JWT');

ws.onmessage = (e) => {
    const message = JSON.parse(e.data);
    console.log(`${message.full_name}: ${message.content}`);
};

ws.send(JSON.stringify({ content: "Hello world" }));

Run Tests

pytest tests/ -v

Project Structure

app/
├── api/          # Endpoints and WebSocket handlers
├── core/         # Config, database, security, dependencies
├── models/       # Database models
├── schemas/      # Pydantic schemas
├── services/     # Business logic, Redis and chat services
└── main.py       # Entry point