Real-time Chat API

A comprehensive real-time chat API built with FastAPI, WebSocket, and advanced features including media sharing, end-to-end encryption, and push notifications. Perfect for building modern chat applications.

🚀 Features

Core Chat Features

• Real-time Messaging: WebSocket-based instant messaging
• Direct Messages: Private one-on-one conversations
• Group Chats: Multi-user chat rooms with admin controls
• Message Types: Text, images, videos, audio, documents
• Message Status: Sent, delivered, read receipts
• Typing Indicators: Real-time typing status
• Message Replies: Reply to specific messages
• Message Editing: Edit and delete messages

Media & File Sharing

• Image Sharing: Upload and share images with automatic thumbnail generation
• Video Support: Share video files with metadata extraction
• Document Support: PDF, Word, Excel, PowerPoint, and more
• Audio Messages: Voice recordings and audio file sharing
• File Validation: Size limits and type restrictions
• Secure Storage: Files stored securely with access control

Security & Encryption

• End-to-End Encryption: RSA + AES hybrid encryption for messages
• JWT Authentication: Secure token-based authentication
• Key Management: Automatic RSA key pair generation
• Message Encryption: Client-side encryption capabilities
• Secure File Storage: Protected media file access

Notifications & Alerts

• Push Notifications: Firebase-based mobile notifications
• Mention Alerts: @username notifications
• Real-time Notifications: WebSocket-based instant alerts
• Notification History: Persistent notification storage
• Custom Notification Types: Message, mention, group invites

Advanced Features

• User Presence: Online/offline status tracking
• Last Seen: User activity timestamps
• Chat Management: Admin/owner roles and permissions
• Member Management: Add/remove users, role assignment
• Message Search: Find messages across chats
• Unread Counts: Track unread messages per chat

Quick Start

Prerequisites

• Python 3.8+
• pip

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Run database migrations:

alembic upgrade head

3. Start the application:

uvicorn main:app --reload

The API will be available at http://localhost:8000

API Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

WebSocket Connection

Connect to the WebSocket endpoint for real-time messaging:

const ws = new WebSocket('ws://localhost:8000/ws/{access_token}');

// Send a message
ws.send(JSON.stringify({
    type: 'send_message',
    chat_id: 1,
    content: 'Hello, world!',
    message_type: 'text'
}));

// Listen for messages
ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Received:', data);
};

📡 API Endpoints

Authentication (/api/auth)

• POST /register - Register a new user
• POST /login - Login with username and password
• GET /me - Get current user information
• PUT /me - Update user profile
• POST /device-token - Update device token for push notifications

Chats (/api/chats)

• GET / - Get user's chat list
• POST /direct - Create or get direct chat with another user
• POST /group - Create a new group chat
• GET /{chat_id} - Get chat details and members
• PUT /{chat_id} - Update chat information (admin/owner only)
• POST /{chat_id}/members - Add member to chat
• DELETE /{chat_id}/members/{user_id} - Remove member from chat

Messages (/api/messages)

• GET /{chat_id} - Get chat messages with pagination
• PUT /{message_id} - Edit a message
• DELETE /{message_id} - Delete a message
• POST /{message_id}/read - Mark message as read

Media (/api/media)

• POST /upload/{message_id} - Upload media files for a message
• GET /{media_id} - Download media file
• GET /{media_id}/thumbnail - Get media thumbnail
• GET /{media_id}/info - Get media file information
• DELETE /{media_id} - Delete media file

Notifications (/api/notifications)

• GET / - Get user notifications
• GET /mentions - Get unread mentions
• POST /{notification_id}/read - Mark notification as read
• POST /mentions/{mention_id}/read - Mark mention as read
• POST /read-all - Mark all notifications as read
• GET /count - Get unread notification count

Encryption (/api/encryption)

• POST /generate-keys - Generate new RSA key pair
• GET /public-key - Get current user's public key
• GET /public-key/{user_id} - Get another user's public key
• POST /encrypt - Encrypt a message for a user
• POST /decrypt - Decrypt a message
• PUT /public-key - Update user's public key

System

• GET / - API information and features
• GET /health - Health check endpoint
• GET /api/status - System status and statistics

🏗️ Data Models

User

• id: Unique identifier
• username: Username (unique, required)
• email: Email address (unique, required)
• full_name: Optional full name
• avatar_url: Profile picture URL
• bio: User biography
• is_active: Account status
• is_online: Current online status
• last_seen: Last activity timestamp
• public_key: RSA public key for E2E encryption
• device_token: Firebase device token for push notifications

Chat

• id: Unique identifier
• name: Chat name (null for direct messages)
• description: Chat description
• chat_type: "direct" or "group"
• avatar_url: Chat avatar image
• is_active: Active status

Message

• id: Unique identifier
• chat_id: Associated chat
• sender_id: Message sender
• reply_to_id: Replied message ID (optional)
• content: Message content (encrypted)
• content_type: "text", "image", "video", "audio", "file", "system"
• status: "sent", "delivered", "read", "failed"
• is_edited: Edit status
• is_deleted: Deletion status
• created_at: Send timestamp

Media

• id: Unique identifier
• message_id: Associated message
• filename: Stored filename
• original_filename: Original upload name
• file_size: Size in bytes
• mime_type: File MIME type
• media_type: "image", "video", "audio", "document", "other"
• width/height: Image/video dimensions
• duration: Audio/video duration
• thumbnail_path: Thumbnail file path

Chat Member

• id: Unique identifier
• chat_id: Associated chat
• user_id: User ID
• role: "member", "admin", "owner"
• nickname: Chat-specific nickname
• is_muted: Mute status
• joined_at: Join timestamp
• last_read_message_id: Last read message for unread count

Notification

• id: Unique identifier
• user_id: Recipient user
• notification_type: "message", "mention", "group_invite"
• title: Notification title
• body: Notification content
• data: Additional JSON data
• is_read: Read status
• created_at: Creation timestamp

🔧 Environment Variables

Set the following environment variables for production:

# Required
SECRET_KEY="your-super-secret-key-change-in-production"

# Optional - Firebase Push Notifications
FIREBASE_CREDENTIALS_PATH="/path/to/firebase-credentials.json"
# OR
FIREBASE_CREDENTIALS_JSON='{"type": "service_account", ...}'

# Optional - Redis for caching (if implemented)
REDIS_URL="redis://localhost:6379"

💾 Database

The application uses SQLite by default with the database file stored at /app/storage/db/chat.sqlite. The database is automatically created when the application starts.

File Storage Structure:

/app/storage/
├── db/
│   └── chat.sqlite          # Main database
├── media/                   # Uploaded media files
│   ├── image_file.jpg
│   └── document.pdf
└── thumbnails/              # Generated thumbnails
    └── thumb_image_file.jpg

🔐 Authentication & Security

JWT Authentication

1. Register a new user or login with existing credentials
2. Include the access token in the Authorization header: Authorization: Bearer <token>
3. For WebSocket connections, pass the token in the URL: /ws/{access_token}

End-to-End Encryption

1. Key Generation: Each user gets an RSA key pair on registration
2. Message Encryption: Messages encrypted with recipient's public key
3. Hybrid Encryption: Uses RSA + AES for large messages
4. Client-Side: Encryption/decryption can be done client-side

Example encryption workflow:

# Get recipient's public key
GET /api/encryption/public-key/{user_id}

# Encrypt message client-side
POST /api/encryption/encrypt
{
    "message": "Hello, this is encrypted!",
    "recipient_user_id": 123
}

# Send encrypted message via WebSocket
ws.send({
    "type": "send_message",
    "chat_id": 1,
    "content": "encrypted_content_here"
})

📱 WebSocket Events

Client → Server Events

// Send message
{
    "type": "send_message",
    "chat_id": 1,
    "content": "Hello!",
    "message_type": "text",
    "reply_to_id": null
}

// Typing indicators
{
    "type": "typing_start",
    "chat_id": 1
}

{
    "type": "typing_stop", 
    "chat_id": 1
}

// Mark message as read
{
    "type": "message_read",
    "message_id": 123,
    "chat_id": 1
}

// Join/leave chat room
{
    "type": "join_chat",
    "chat_id": 1
}

Server → Client Events

// New message received
{
    "type": "new_message",
    "message": {
        "id": 123,
        "chat_id": 1,
        "sender_id": 456,
        "sender_username": "john_doe",
        "content": "Hello!",
        "created_at": "2024-12-20T12:00:00Z"
    }
}

// User status updates
{
    "type": "user_status",
    "user_id": 456,
    "username": "john_doe", 
    "status": "online"
}

// Typing indicators
{
    "type": "typing_start",
    "chat_id": 1,
    "user_id": 456,
    "username": "john_doe"
}

// Notifications
{
    "type": "mention_notification",
    "title": "Mentioned by john_doe",
    "body": "You were mentioned in a message",
    "chat_id": 1
}

🔧 Development

Code Quality

# Lint and format code
ruff check . --fix
ruff format .

Database Migrations

# Create new migration
alembic revision --autogenerate -m "Description of changes"

# Apply migrations
alembic upgrade head

# Check current migration
alembic current

Testing WebSocket Connection

# Install websocat for testing
pip install websockets

# Test WebSocket connection
python -c "
import asyncio
import websockets
import json

async def test():
    uri = 'ws://localhost:8000/ws/your_jwt_token_here'
    async with websockets.connect(uri) as websocket:
        # Send a test message
        await websocket.send(json.dumps({
            'type': 'send_message',
            'chat_id': 1,
            'content': 'Test message'
        }))
        
        # Listen for response
        response = await websocket.recv()
        print(json.loads(response))

asyncio.run(test())
"

🏗️ Architecture

Technology Stack

• FastAPI: Modern, fast web framework with WebSocket support
• SQLAlchemy: Python ORM for database operations
• Alembic: Database migration management
• Pydantic: Data validation using Python type annotations
• WebSocket: Real-time bidirectional communication
• JWT: JSON Web Tokens for authentication
• SQLite: Lightweight database for development
• Cryptography: RSA + AES encryption for E2E security
• Firebase Admin: Push notification service
• Pillow: Image processing and thumbnail generation

Project Structure

app/
├── api/                    # API route handlers
│   ├── auth.py            # Authentication endpoints
│   ├── chats.py           # Chat management
│   ├── messages.py        # Message operations
│   ├── media.py           # File upload/download
│   ├── notifications.py   # Notification management
│   └── encryption.py      # E2E encryption utilities
├── core/                  # Core utilities
│   ├── deps.py           # Dependency injection
│   └── security.py       # Security functions
├── db/                   # Database configuration
│   ├── base.py          # SQLAlchemy base
│   └── session.py       # Database session management
├── models/              # SQLAlchemy models
│   ├── user.py         # User model
│   ├── chat.py         # Chat model
│   ├── message.py      # Message model
│   └── ...
├── schemas/            # Pydantic schemas
│   ├── user.py        # User schemas
│   ├── chat.py        # Chat schemas
│   └── ...
├── services/          # Business logic services
│   ├── media_service.py        # File handling
│   ├── encryption_service.py   # Encryption logic
│   ├── notification_service.py # Notification management
│   └── push_notification_service.py
├── websocket/         # WebSocket handling
│   ├── connection_manager.py  # Connection management
│   └── chat_handler.py       # Message handling
└── utils/            # Utility functions

Design Patterns

• Repository Pattern: Data access abstraction
• Service Layer: Business logic separation
• Dependency Injection: Loose coupling
• Event-Driven: WebSocket event handling
• Clean Architecture: Separation of concerns

📊 Performance Considerations

• Connection Pooling: SQLAlchemy connection management
• File Storage: Local storage with direct file serving
• Memory Management: Efficient WebSocket connection tracking
• Thumbnail Generation: Automatic image thumbnail creation
• Message Pagination: Efficient large chat history loading
• Real-time Optimization: WebSocket connection pooling

🚀 Deployment

Production Checklist

• Set strong SECRET_KEY environment variable
• Configure Firebase credentials for push notifications
• Set up proper file storage (S3, etc.) for production
• Configure reverse proxy (nginx) for WebSocket support
• Set up SSL/TLS certificates
• Configure database backups
• Set up monitoring and logging
• Configure CORS for your frontend domain

Docker Deployment

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

This comprehensive chat API provides a solid foundation for building modern messaging applications with real-time communication, security, and scalability in mind.