# 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 ```bash npm install ``` ### 2. Database Setup First, ensure PostgreSQL is installed and running on your system. Create a database for the application: ```bash # 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: ```bash 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: ```bash # Run migrations npm run migration:run ``` ### 5. Start the Application ```bash # 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 ```typescript // 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: ```dart // 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 ```bash npm run test npm run test:e2e npm run test:cov ``` ### Linting and Formatting ```bash npm run lint npm run format ``` ### Building for Production ```bash 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.