personaltaskmanagementapi-lh74qi/README.md

# 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:
```bash
pip install -r requirements.txt
```

2. Run database migrations:
```bash
alembic upgrade head
```

3. Start the application:
```bash
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:

```javascript
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:

```bash
# 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:
```python
# 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
```javascript
// 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
```javascript
// 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
```bash
# Lint and format code
ruff check . --fix
ruff format .
```

### Database Migrations
```bash
# Create new migration
alembic revision --autogenerate -m "Description of changes"

# Apply migrations
alembic upgrade head

# Check current migration
alembic current
```

### Testing WebSocket Connection
```bash
# 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
```dockerfile
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.