realtimechatapiwithmediasupport-t50lz6/README.md

Real-time Chat API with Multi-Tenant Organization Support

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

1. User logs in and gets list of organizations
2. User selects/switches between organizations
3. All chat data is filtered by current organization
4. 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

1. Owner - Full control over organization
2. Admin - Management capabilities except role changes
3. Moderator - Content moderation and limited management
4. 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.