# Implementation Tasks

## 1. Database Schema
- [ ] 1.1 Create `messages` table with columns:
  - [ ] message_id (UUID, PK)
  - [ ] room_id (FK to incident_rooms)
  - [ ] sender_id (VARCHAR, user email)
  - [ ] content (TEXT)
  - [ ] message_type (ENUM: text, image_ref, file_ref, system, incident_data)
  - [ ] metadata (JSON, for structured data and mentions)
  - [ ] created_at (TIMESTAMP)
  - [ ] edited_at (TIMESTAMP, nullable)
  - [ ] deleted_at (TIMESTAMP, nullable for soft delete)
  - [ ] sequence_number (BIGSERIAL for ordering)
- [ ] 1.2 Create `message_reactions` table:
  - [ ] reaction_id (SERIAL, PK)
  - [ ] message_id (FK to messages)
  - [ ] user_id (VARCHAR)
  - [ ] emoji (VARCHAR(10))
  - [ ] created_at (TIMESTAMP)
  - [ ] UNIQUE constraint on (message_id, user_id, emoji)
- [ ] 1.3 Create `message_edit_history` table:
  - [ ] edit_id (SERIAL, PK)
  - [ ] message_id (FK to messages)
  - [ ] original_content (TEXT)
  - [ ] edited_by (VARCHAR)
  - [ ] edited_at (TIMESTAMP)
- [ ] 1.4 Create indexes:
  - [ ] Index on messages(room_id, created_at DESC)
  - [ ] Index on messages(room_id, sequence_number)
  - [ ] Full-text index on messages(content) for search
  - [ ] Index on message_reactions(message_id)
- [ ] 1.5 Create database migration using Alembic

## 2. WebSocket Infrastructure

### 2.1 Connection Management
- [ ] 2.1.1 Create `app/modules/realtime/` module structure:
  - [ ] `__init__.py`
  - [ ] `websocket_manager.py` (connection pool management)
  - [ ] `models.py` (message models)
  - [ ] `schemas.py` (WebSocket message schemas)
  - [ ] `handlers.py` (message type handlers)
  - [ ] `router.py` (WebSocket endpoint)
- [ ] 2.1.2 Implement `WebSocketManager` class:
  - [ ] `connect(websocket, room_id, user_id)` - Add connection to pool
  - [ ] `disconnect(websocket, room_id, user_id)` - Remove and cleanup
  - [ ] `broadcast_to_room(room_id, message)` - Send to all in room
  - [ ] `send_personal(user_id, message)` - Send to specific user
  - [ ] `get_room_connections(room_id)` - List active connections
- [ ] 2.1.3 Implement connection authentication:
  - [ ] Extract JWT token from WebSocket headers or query params
  - [ ] Validate token using existing auth module
  - [ ] Check room membership before allowing connection
  - [ ] Reject unauthorized connections

### 2.2 WebSocket Endpoint
- [ ] 2.2.1 Create WebSocket route `/ws/{room_id}`:
  - [ ] Accept WebSocket connection
  - [ ] Authenticate user
  - [ ] Add to connection pool
  - [ ] Listen for incoming messages
  - [ ] Handle disconnection gracefully
- [ ] 2.2.2 Implement reconnection handling:
  - [ ] Track last sequence number per connection
  - [ ] Support resume from sequence number
  - [ ] Queue messages during brief disconnections
- [ ] 2.2.3 Implement heartbeat/ping-pong:
  - [ ] Send ping every 30 seconds
  - [ ] Wait for pong response
  - [ ] Terminate stale connections

## 3. Message Handling

### 3.1 Message Models and Schemas
- [ ] 3.1.1 Create SQLAlchemy models:
  - [ ] `Message` model
  - [ ] `MessageReaction` model
  - [ ] `MessageEditHistory` model
- [ ] 3.1.2 Create Pydantic schemas:
  - [ ] `WebSocketMessage` (incoming)
  - [ ] `MessageBroadcast` (outgoing)
  - [ ] `MessageCreate` (for database)
  - [ ] `MessageResponse` (for REST API)
  - [ ] `ReactionRequest/Response`
- [ ] 3.1.3 Define message type enums:
  - [ ] MessageType (text, image_ref, file_ref, system, incident_data)
  - [ ] SystemEventType (user_joined, user_left, status_changed, etc.)

### 3.2 Message Processing
- [ ] 3.2.1 Create message handlers for each type:
  - [ ] `handle_text_message()` - Process plain text
  - [ ] `handle_image_reference()` - Validate and store image refs
  - [ ] `handle_file_reference()` - Validate and store file refs
  - [ ] `handle_incident_data()` - Process structured data
  - [ ] `handle_system_message()` - Broadcast system events
- [ ] 3.2.2 Implement mention parsing:
  - [ ] Extract @mentions from content
  - [ ] Validate mentioned users exist
  - [ ] Store mentions in metadata
- [ ] 3.2.3 Implement message validation:
  - [ ] Content length limits (10KB text, 100KB structured)
  - [ ] Rate limiting (10 messages/second per user)
  - [ ] Spam detection
  - [ ] XSS prevention (sanitize HTML)

### 3.3 Message Operations
- [ ] 3.3.1 Implement message editing:
  - [ ] Validate edit permission (own message, within 15 mins)
  - [ ] Store original in edit history
  - [ ] Update message content
  - [ ] Broadcast edit event
- [ ] 3.3.2 Implement message deletion:
  - [ ] Soft delete (set deleted_at)
  - [ ] Validate delete permission
  - [ ] Broadcast deletion event
- [ ] 3.3.3 Implement reactions:
  - [ ] Add/remove reactions
  - [ ] Aggregate reaction counts
  - [ ] Broadcast reaction updates

## 4. Message Service Layer

### 4.1 Message Service
- [ ] 4.1.1 Create `services/message_service.py`:
  - [ ] `create_message(db, room_id, sender_id, content, message_type)`
  - [ ] `get_messages(db, room_id, limit, before_timestamp)`
  - [ ] `edit_message(db, message_id, user_id, new_content)`
  - [ ] `delete_message(db, message_id, user_id)`
  - [ ] `search_messages(db, room_id, query, user_id)`
- [ ] 4.1.2 Implement message persistence:
  - [ ] Auto-assign sequence numbers
  - [ ] Handle concurrent writes
  - [ ] Maintain message ordering
- [ ] 4.1.3 Implement message retrieval:
  - [ ] Paginated history loading
  - [ ] Filter by message type
  - [ ] Include reaction aggregates

### 4.2 Reaction Service
- [ ] 4.2.1 Create `services/reaction_service.py`:
  - [ ] `add_reaction(db, message_id, user_id, emoji)`
  - [ ] `remove_reaction(db, message_id, user_id, emoji)`
  - [ ] `get_message_reactions(db, message_id)`
  - [ ] `get_reaction_counts(db, message_id)`

## 5. REST API Endpoints

### 5.1 Message Endpoints
- [ ] 5.1.1 Implement message REST endpoints:
  - [ ] `GET /api/rooms/{room_id}/messages` - Get message history
  - [ ] `GET /api/rooms/{room_id}/messages/{message_id}` - Get single message
  - [ ] `POST /api/rooms/{room_id}/messages` - Send message (alternative to WS)
  - [ ] `PATCH /api/messages/{message_id}` - Edit message
  - [ ] `DELETE /api/messages/{message_id}` - Delete message
- [ ] 5.1.2 Implement search endpoint:
  - [ ] `GET /api/rooms/{room_id}/messages/search?q={query}`
- [ ] 5.1.3 Implement reaction endpoints:
  - [ ] `POST /api/messages/{message_id}/reactions` - Add reaction
  - [ ] `DELETE /api/messages/{message_id}/reactions/{emoji}` - Remove reaction

### 5.2 Presence Endpoints
- [ ] 5.2.1 Create presence tracking:
  - [ ] `GET /api/rooms/{room_id}/online` - Get online users
  - [ ] `GET /api/rooms/{room_id}/typing` - Get typing users

## 6. Broadcasting System

### 6.1 Event Broadcasting
- [ ] 6.1.1 Create broadcast service:
  - [ ] Room-level broadcasts (all members)
  - [ ] User-level broadcasts (specific user)
  - [ ] System-wide broadcasts (all connections)
- [ ] 6.1.2 Implement event types:
  - [ ] Message events (new, edit, delete)
  - [ ] User events (joined, left, typing)
  - [ ] Room events (status changed, member added)
- [ ] 6.1.3 Create event queue:
  - [ ] Queue events during processing
  - [ ] Batch broadcasts for efficiency
  - [ ] Handle failed deliveries

### 6.2 Typing Indicators
- [ ] 6.2.1 Implement typing state management:
  - [ ] Track typing users per room
  - [ ] Auto-expire after 3 seconds
  - [ ] Broadcast typing events
- [ ] 6.2.2 Debounce typing events:
  - [ ] Limit typing event frequency
  - [ ] Aggregate multiple typing users

## 7. Client Helpers

### 7.1 Connection Recovery
- [ ] 7.1.1 Implement reconnection logic:
  - [ ] Exponential backoff (1s, 2s, 4s, 8s, max 30s)
  - [ ] Store last sequence number
  - [ ] Request missed messages on reconnect
- [ ] 7.1.2 Implement offline queue:
  - [ ] Queue messages while disconnected
  - [ ] Send queued messages on reconnect
  - [ ] Handle conflicts

### 7.2 Client SDK
- [ ] 7.2.1 Create Python client example:
  - [ ] WebSocket connection wrapper
  - [ ] Auto-reconnection
  - [ ] Message sending/receiving
- [ ] 7.2.2 Create JavaScript client example:
  - [ ] WebSocket wrapper class
  - [ ] React hooks for messages
  - [ ] TypeScript types

## 8. Testing

### 8.1 Unit Tests
- [ ] 8.1.1 Test message service:
  - [ ] Message creation with validation
  - [ ] Message ordering
  - [ ] Edit/delete permissions
  - [ ] Reaction operations
- [ ] 8.1.2 Test WebSocket manager:
  - [ ] Connection pooling
  - [ ] Broadcasting logic
  - [ ] Disconnection handling

### 8.2 Integration Tests
- [ ] 8.2.1 Test WebSocket flow:
  - [ ] Connect → Send → Receive → Disconnect
  - [ ] Multi-user message exchange
  - [ ] Reconnection with message recovery
- [ ] 8.2.2 Test REST endpoints:
  - [ ] Message history retrieval
  - [ ] Search functionality
  - [ ] Permission enforcement

### 8.3 Performance Tests
- [ ] 8.3.1 Load testing:
  - [ ] 100+ concurrent WebSocket connections
  - [ ] 1000+ messages/minute throughput
  - [ ] Message broadcast latency < 100ms
- [ ] 8.3.2 Stress testing:
  - [ ] Connection/disconnection cycling
  - [ ] Large message payloads
  - [ ] Database query performance

## 9. Security

### 9.1 Authentication & Authorization
- [ ] 9.1.1 Implement WebSocket authentication:
  - [ ] JWT token validation
  - [ ] Room membership verification
  - [ ] Permission checks for operations
- [ ] 9.1.2 Implement rate limiting:
  - [ ] Per-user message rate limits
  - [ ] Connection attempt limits
  - [ ] Global room limits

### 9.2 Input Validation
- [ ] 9.2.1 Sanitize message content:
  - [ ] XSS prevention
  - [ ] SQL injection prevention
  - [ ] Script injection prevention
- [ ] 9.2.2 Validate message size:
  - [ ] Enforce content length limits
  - [ ] Validate JSON structure
  - [ ] Reject malformed messages

## 10. Monitoring & Logging

### 10.1 Metrics
- [ ] 10.1.1 Track WebSocket metrics:
  - [ ] Active connections count
  - [ ] Messages per second
  - [ ] Broadcast latency
  - [ ] Error rates
- [ ] 10.1.2 Track message metrics:
  - [ ] Messages per room
  - [ ] Message types distribution
  - [ ] Edit/delete rates

### 10.2 Logging
- [ ] 10.2.1 Log WebSocket events:
  - [ ] Connection/disconnection
  - [ ] Authentication failures
  - [ ] Message errors
- [ ] 10.2.2 Log message operations:
  - [ ] Message sent/edited/deleted
  - [ ] Search queries
  - [ ] Permission denials

## 11. Documentation

### 11.1 API Documentation
- [ ] 11.1.1 Document WebSocket protocol:
  - [ ] Connection process
  - [ ] Message formats
  - [ ] Event types
- [ ] 11.1.2 Document REST endpoints:
  - [ ] Request/response formats
  - [ ] Error codes
  - [ ] Rate limits

### 11.2 Integration Guide
- [ ] 11.2.1 Client integration examples:
  - [ ] Python client code
  - [ ] JavaScript/React examples
  - [ ] Error handling patterns
- [ ] 11.2.2 Server deployment guide:
  - [ ] WebSocket configuration
  - [ ] Nginx proxy setup
  - [ ] Scaling considerations