Anonymous Chat Backend

A real-time anonymous chat backend built with NestJS, TypeORM (PostgreSQL), Redis, and Socket.IO. This system provides ephemeral chat rooms with advanced features like presence tracking, polls, mentions, message pinning, and comprehensive moderation tools.

Overview

This backend powers anonymous chat rooms where:

Users can create temporary or persistent chat rooms
Each room has a unique invite token (and optional moderator token)
Messages can be ephemeral (auto-deleted based on retention policy)
Real-time presence tracking shows who's online
Advanced features: polls, mentions, replies, message pinning
Comprehensive moderation: kick/ban users, close rooms
Rate limiting and fingerprint-based abuse prevention

Architecture & Tech Stack

Core Technologies

NestJS - Modern TypeScript framework with modular architecture
TypeORM - ORM for PostgreSQL with migration support
PostgreSQL - Primary database for persistent data
Redis - Session storage, presence tracking, pub/sub messaging
Socket.IO - Real-time WebSocket communication
ioredis - Redis client library

Module Structure

src/
├── app.module.ts          # Root module
├── main.ts                # Bootstrap with CORS, validation
├── typeorm.config.ts      # Database configuration
├── rooms/                 # Room creation, validation, management
├── participants/          # Participant tracking, bans
├── auth/                  # Session & token management
├── messages/              # Messages, polls, notifications
├── websocket/             # Socket.IO gateway
├── redis/                 # Redis client service
├── analytics/             # Usage metrics
├── health/                # Health checks
└── common/                # Shared utilities, decorators, rate limiting

Key modules:

RoomsModule: Room lifecycle (create, join, close, end)
AuthModule: Session creation and validation
WebsocketModule: Real-time chat gateway
MessagesModule: Message persistence, polls, notifications
ParticipantsModule: Participant records, ban management
RedisModule: Redis client and subscriber instances
AnalyticsModule: Metrics tracking

Installation & Setup

Prerequisites

Node.js 18+
PostgreSQL 15+
Redis 7+
npm or yarn

Local Development

Install dependencies
```
npm install
```

Set up environment variables Create a .env file in the root directory:

# Database
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASS=postgres
DATABASE_NAME=anonchat

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Application
PORT=5000
NODE_ENV=development
FRONTEND_URL=http://localhost:3000

# Session
SESSION_TTL_SECONDS=604800  # 7 days

Run database migrations
```
npm run migration:run
```
Start development server
```
npm run start:dev
```
Server runs on http://localhost:5000

Docker Compose

docker-compose up --build

This starts:

Backend service (port 5000)
PostgreSQL (port 5432)
Redis (port 6379)

Environment Variables

Variable	Description	Default
`DATABASE_HOST`	PostgreSQL host	`localhost`
`DATABASE_PORT`	PostgreSQL port	`5432`
`DATABASE_USER`	Database username	`postgres`
`DATABASE_PASS`	Database password	`postgres`
`DATABASE_NAME`	Database name	`anonchat`
`REDIS_HOST`	Redis host	`localhost`
`REDIS_PORT`	Redis port	`6379`
`REDIS_PASSWORD`	Redis password	(empty)
`PORT`	Application port	`5000`
`NODE_ENV`	Environment	`development`
`FRONTEND_URL`	Frontend origin for CORS	(required)
`SESSION_TTL_SECONDS`	Session expiry time	`604800` (7 days)

Database Schema

Tables

rooms

{
  id: string (uuid, PK)
  title: string
  description?: string
  inviteTokenHash: string          // bcrypt hash
  moderatorTokenHash?: string      // bcrypt hash
  isOpen: boolean                  // Room open for new joins
  ephemeral: boolean               // Messages auto-delete
  retentionSeconds: number         // How long messages persist
  chatDurationSeconds: number      // Room auto-close timer
  maxParticipants: number
  actualParticipants: number
  settings: json                   // Additional config
  creatorIP?: string
  creatorAgent?: string
  createdAt: timestamp
  closedAt?: timestamp
}

participants

{
  id: string (uuid, PK)
  roomId: string (uuid)
  username: string
  anonymousId: string              // 6-char hex for privacy
  sessionId?: string
  avatar?: string
  joinedAt: timestamp
  leftAt?: timestamp
  isModerator: boolean
}

messages

{
  id: string (uuid, PK)
  roomId: string (uuid)
  authorUsername: string
  anonymousId?: string
  authorAvatar?: string
  authorSessionId?: string
  authorRole?: string
  clientMsgId?: string             // For client-side dedup
  content: json                    // { text?: string, type: 'text' | 'poll' }
  replyToId?: string (uuid)        // Parent message
  mentions?: string[]              // Mentioned usernames
  pinned: boolean
  pinnedAt?: timestamp
  pinnedBy?: string
  ip?: string
  userAgent?: string
  createdAt: timestamp
}

polls

{
  id: string (uuid, PK)
  roomId: string (uuid)
  messageId: string (uuid)         // Associated message
  question: string
  options: json[]                  // [{ id, text }]
  allowMultipleAnswers: boolean
  isClosed: boolean
  closedAt?: timestamp
  creatorUsername: string
  creatorAnonymousId?: string
  creatorSessionId?: string
  createdAt: timestamp
}

poll_votes

{
  id: string (uuid, PK)
  pollId: string (uuid)
  optionId: string                 // References poll.options[].id
  sessionId: string                // Voter session
  username: string
  anonymousId: string
  createdAt: timestamp
}

room_bans

{
  id: string (uuid, PK)
  roomId: string (uuid)
  fingerprintHash?: string
  deviceId?: string
  ip?: string
  userAgent?: string
  bannedBy: string                 // Moderator username
  reason?: string
  createdAt: timestamp
  expiresAt?: timestamp
}

room_fingerprints

Used to limit room creation per fingerprint.

notifications

{
  id: string (uuid, PK)
  roomId: string (uuid)
  recipientUsername: string
  recipientSessionId: string
  type: string                     // 'mention' | 'reply' | 'poll_vote' | etc.
  content: json
  messageId?: string (uuid)
  read: boolean
  createdAt: timestamp
}

Redis Data Structures

Redis is used for session storage, presence tracking, and pub/sub messaging.

Key Patterns

Sessions

session:<sessionId>              → JSON { sessionId, roomId, username, anonymousId, avatar, role, createdAt, ... }
session_token:<token>            → sessionId
username_session:<roomId>:<username> → sessionId

TTL: SESSION_TTL_SECONDS (default 7 days)
Sessions map tokens to user state
Username→session mapping prevents hijacking

Presence

presence:<roomId>                → Hash { sessionId: JSON { username, anonymousId, role, ... } }

Stores currently connected users per room
Updated on join/leave via WebSocket

Username Locks

room:<roomId>:username:<username> → "1"

TTL: SESSION_TTL_SECONDS
Ensures usernames are unique per room
Created on join, checked on connect

Pub/Sub Channels

room:<roomId>:messages           → Published messages broadcast to all connected clients

Gateway subscribes with pattern room:*:messages
Enables horizontal scaling (multiple backend instances)

REST API Endpoints

All endpoints are prefixed with /api.

Room Management

`POST /api/rooms`

Create a new room.

Request Body:

{
  "title": "My Chat Room",
  "description": "Optional description",
  "ephemeral": true,
  "chatDurationSeconds": 3600,
  "retentionSeconds": 2592000,
  "maxParticipants": 100,
  "fingerprintHash": "abc123...",
  "deviceId": "device-uuid"
}

Response:

{
  "roomId": "uuid",
  "inviteToken": "plain-token",
  "moderatorToken": "plain-moderator-token"
}

Rate Limit: 5 rooms per fingerprint/IP per hour

`GET /api/rooms/:id`

Get room metadata.

Response:

{
  "roomId": "uuid",
  "title": "Room Title",
  "description": "Description",
  "ephemeral": true,
  "createdAt": "ISO-8601",
  "isOpen": true,
  "actualParticipants": 5,
  "closedAt": null
}

`POST /api/rooms/:id/validate-invite`

Validate invite token before join.

Request Body:

{
  "inviteToken": "plain-token"
}

Response:

{
  "ok": true
}

`POST /api/rooms/:id/join`

Join a room and create a session.

Request Body:

{
  "inviteToken": "plain-token",
  "moderatorToken": "optional-mod-token",
  "username": "Alice",
  "avatar": "optional-avatar-url",
  "fingerprintHash": "fingerprint-hash",
  "deviceId": "device-uuid"
}

Response:

{
  "sessionToken": "hex-token",
  "sessionId": "uuid",
  "anonymousId": "6-char-hex",
  "role": "participant" | "moderator"
}

Notes:

Checks if username is taken
Checks if user is banned
Creates session in Redis
Locks username
Records participant in database