A comprehensive real-time chat API built with NestJS (TypeScript) featuring WebSocket support, organizational multi-tenancy, direct messaging, group chats, end-to-end encryption, push notifications, mention alerts, and media file sharing.

Features

🏢 Multi-Tenant Organization Support

Complete data isolation between organizations
Organization management with roles and permissions (Owner, Admin, Moderator, Member)
Member invitation system with email-based invites
Organization switching for users in multiple organizations
Configurable organization settings and limits
Organization-scoped chat rooms and messaging
Real-time organization context in WebSocket connections

Core Chat Features

Real-time messaging with WebSocket support
Direct Messages (DM) between users within organizations
Group chat functionality with member management
Message editing and deletion
Reply to messages functionality
Typing indicators
Online/offline status tracking
Message read receipts

Media Support

File uploads (images, videos, audio, documents)
Media types supported: JPG, PNG, GIF, WebP, SVG, MP4, MPEG, QuickTime, AVI, MP3, WAV, OGG, PDF, Word, Excel, PowerPoint, ZIP, RAR, 7z
File size limit: Up to 100MB per file
Automatic media type detection
Secure media access (only chat members can access)

Security & Encryption

End-to-end encryption for messages
JWT-based authentication
User key pair generation for encryption
Secure file uploads with access control
Input validation and sanitization

Push Notifications

Firebase Cloud Messaging (FCM) integration
New message notifications for offline users
Mention alerts with push notifications
Device management for multi-device support
Automatic retry for failed notifications
Notification cleanup (removes old notifications)

User Management

User registration and authentication
Profile management with avatar support
User search functionality
Public key sharing for encryption
Online status management

Tech Stack

Framework: NestJS (TypeScript)
Database: PostgreSQL with TypeORM
Real-time: Socket.IO
Authentication: JWT with Passport
File Storage: Local filesystem
Push Notifications: Firebase Cloud Messaging
API Documentation: Swagger/OpenAPI
Encryption: CryptoJS (AES encryption)

Project Structure

src/
├── auth/                 # Authentication module
│   ├── dto/             # Data transfer objects
│   ├── guards/          # Authentication guards
│   └── strategies/      # Passport strategies
├── chat/                # Chat functionality
│   └── dto/             # Chat DTOs
├── database/            # Database entities
│   └── entities/        # TypeORM entities
├── encryption/          # Encryption service
├── media/               # Media upload handling
├── notification/        # Push notifications
├── users/               # User management
│   └── dto/             # User DTOs
├── app.module.ts        # Main application module
└── main.ts             # Application entry point

Quick Start

1. Install Dependencies

npm install

2. Database Setup

First, ensure PostgreSQL is installed and running on your system. Create a database for the application:

# Connect to PostgreSQL (adjust connection details as needed)
psql -U postgres -h localhost

# Create database
CREATE DATABASE realtime_chat_db;

# Exit PostgreSQL
\q

3. Environment Configuration

Copy the example environment file and configure it:

cp .env.example .env

Required environment variables:

DB_HOST: PostgreSQL host (default: localhost)
DB_PORT: PostgreSQL port (default: 5432)
DB_USERNAME: PostgreSQL username (default: postgres)
DB_PASSWORD: PostgreSQL password (default: postgres)
DB_NAME: PostgreSQL database name (default: realtime_chat_db)
PORT: Server port (default: 3000)
JWT_SECRET: Secret key for JWT tokens
ENCRYPTION_KEY: 32-character key for end-to-end encryption
FIREBASE_SERVICE_ACCOUNT: Firebase service account JSON for push notifications

4. Database Migration

Run the database migrations to set up the schema:

# Run migrations
npm run migration:run

5. Start the Application

# Development
npm run start:dev

# Production
npm run build
npm run start:prod

The application will be available at:

API: http://localhost:3000
Documentation: http://localhost:3000/docs
OpenAPI JSON: http://localhost:3000/openapi.json
Health Check: http://localhost:3000/health

API Endpoints

Authentication

POST /auth/register - Register new user
POST /auth/login - Login user
POST /auth/logout - Logout user

Organizations

POST /organizations - Create new organization
GET /organizations - Get user organizations
GET /organizations/active - Get user's active organization
POST /organizations/:orgId/set-active - Set active organization
GET /organizations/:orgId - Get organization details
PUT /organizations/:orgId - Update organization
GET /organizations/:orgId/members - Get organization members
POST /organizations/:orgId/invite - Invite user to organization
POST /organizations/accept-invite/:token - Accept organization invitation
DELETE /organizations/:orgId/members/:memberId - Remove member
PUT /organizations/:orgId/members/:memberId/role - Update member role
POST /organizations/:orgId/leave - Leave organization

Users

GET /users - Get all users (with search)
GET /users/me - Get current user profile
PUT /users/me - Update user profile
PUT /users/me/avatar - Update user avatar
GET /users/:id - Get user by ID
GET /users/username/:username - Get user by username
GET /users/:id/public-key - Get user's public key

Chat (Organization Context Required)

Note: All chat endpoints require organization context via x-organization-id header or active organization.

GET /chat/rooms - Get user's chat rooms in organization
POST /chat/rooms/direct - Create/get direct message room in organization
POST /chat/rooms/group - Create group chat room in organization
GET /chat/rooms/:roomId - Get chat room details
GET /chat/rooms/:roomId/messages - Get chat room messages
POST /chat/messages - Create new message
PUT /chat/messages/:messageId - Edit message
DELETE /chat/messages/:messageId - Delete message
POST /chat/rooms/:roomId/members - Add members to group
DELETE /chat/rooms/:roomId/members/:memberId - Remove member from group

Media

POST /media/upload/:messageId - Upload media file
GET /media/:mediaId - Get media file details
DELETE /media/:mediaId - Delete media file
GET /media/message/:messageId - Get all media for message

Notifications

GET /notifications - Get user notifications
GET /notifications/unread-count - Get unread notification count
PUT /notifications/:notificationId/read - Mark notification as read
PUT /notifications/read-all - Mark all notifications as read

WebSocket Events

Connection Setup

// Connect with JWT token and organization context
const socket = io('ws://localhost:3000', {
  auth: {
    token: 'your-jwt-token',
    organizationId: 'org-uuid' // Optional - uses active org if not provided
  },
  headers: {
    'x-organization-id': 'org-uuid' // Alternative way to specify organization
  }
});

Client to Server

join_room - Join a chat room within organization
leave_room - Leave a chat room
send_message - Send a new message in organization context
edit_message - Edit existing message
delete_message - Delete message
typing_start - Start typing indicator
typing_stop - Stop typing indicator
mark_as_read - Mark message as read
switch_organization - Switch to different organization context

Server to Client

connected - Connection established with organization context
new_message - New message received
message_edited - Message was edited
message_deleted - Message was deleted
user_typing - User started typing
user_stopped_typing - User stopped typing
message_read - Message was read
mentioned - User was mentioned
user_online - User came online in organization
user_offline - User went offline in organization
joined_room - Successfully joined room
left_room - Successfully left room
organization_switched - Successfully switched organizations
error - Error occurred

Flutter SDK Integration

This API is designed to work seamlessly with Flutter applications with full multi-tenant organization support. Key considerations for Flutter integration:

Organization Context

Every API call and WebSocket connection must include organization context:

// HTTP Headers
final headers = {
  'Authorization': 'Bearer $jwtToken',
  'x-organization-id': currentOrganizationId,
};

// WebSocket Connection
final socket = io('ws://localhost:3000', {
  'auth': {
    'token': jwtToken,
    'organizationId': currentOrganizationId,
  }
});

Multi-Organization User Flow

User logs in and gets list of organizations
User selects/switches between organizations
All chat data is filtered by current organization
WebSocket automatically switches context when organization changes

File Upload

The API supports multipart/form-data uploads, compatible with Flutter's HTTP client and dio package.

Push Notifications

Firebase Cloud Messaging integration allows direct push notification support in Flutter apps.

Real-time Features

Socket.IO events are designed to map directly to Flutter state management patterns (Provider, Bloc, Riverpod).

Database Schema

The application uses PostgreSQL with the following main entities:

Organizations: Multi-tenant organization containers
OrganizationMembers: User membership in organizations with roles
OrganizationInvites: Email-based invitation system
Users: User accounts with encryption keys
ChatRooms: Direct and group chat rooms (organization-scoped)
Messages: Chat messages with encryption support (organization-scoped)
MessageMedia: File attachments
MessageMentions: User mentions in messages
UserDevices: Device registration for push notifications
Notifications: Push notification records (organization-scoped)

Organization Roles & Permissions

Role Hierarchy

Owner - Full control over organization
Admin - Management capabilities except role changes
Moderator - Content moderation and limited management
Member - Basic chat participation

Permission Matrix

Permission	Owner	Admin	Moderator	Member
Manage Organization Settings	✅	✅	❌	❌
Invite Users	✅	✅	✅	❌
Manage Roles	✅	❌	❌	❌
Kick Members	✅	✅	❌	❌
Create Channels	✅	✅	✅	❌
Delete Messages	✅	✅	✅	❌
Access Analytics	✅	✅	❌	❌
Send Messages	✅	✅	✅	✅

Security Features

Multi-Tenant Data Isolation: Complete separation between organizations
JWT Authentication: Secure token-based auth with organization context
Role-Based Access Control: Granular permissions based on organization roles
End-to-end Encryption: Messages encrypted with room-specific keys
File Access Control: Only organization members can access uploaded files
Input Validation: All inputs validated and sanitized
CORS Configuration: Configured for cross-origin requests
Organization Membership Verification: All operations verify user membership

Development

Running Tests

npm run test
npm run test:e2e
npm run test:cov

Linting and Formatting

npm run lint
npm run format

Building for Production

npm run build

Environment Variables

Variable	Description	Required	Default
`DB_HOST`	PostgreSQL host	No	localhost
`DB_PORT`	PostgreSQL port	No	5432
`DB_USERNAME`	PostgreSQL username	No	postgres
`DB_PASSWORD`	PostgreSQL password	No	postgres
`DB_NAME`	PostgreSQL database name	No	realtime_chat_db
`PORT`	Server port	No	3000
`NODE_ENV`	Environment	No	development
`JWT_SECRET`	JWT secret key	Yes	-
`ENCRYPTION_KEY`	32-character encryption key	Yes	-
`FIREBASE_SERVICE_ACCOUNT`	Firebase config JSON	No	-

Storage

The application uses local filesystem storage:

Media Files: /app/storage/media/
User Avatars: /app/storage/media/avatars/
Message Media: /app/storage/media/messages/

Database is stored in PostgreSQL server as configured in environment variables.

Health Check

The API includes a comprehensive health check endpoint at /health that reports:

Service status
Uptime
Memory usage
Environment information

License

MIT License - see LICENSE file for details.

Support

For issues and questions, please check the API documentation at /docs or refer to the source code.