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
```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.