Transient Chat Codebase Analysis & Implementation Guide

Audience: AI Engineering Agent

This document outlines the current state of the transient.chat project, detailing architectural issues, security vulnerabilities, and recommended features. It serves as a roadmap for subsequent implementation tasks.

0. Permanent Project Rules

These rules must be followed for all future modifications.

CSS Strategy: Always use Vanilla CSS; never introduce Tailwind or other heavy CSS frameworks.
Python Conventions: All new Python functions must have type hints.
Dependency Management: Minimize external dependencies. When features are requested, check if standard libraries can be used first.
Architectural Scope: The application must remain lightweight and stateless (in-memory) with no persistent databases unless explicitly approved by the user.

1. Architectural Issues & Bugs

(No pending issues in this category at this time)

2. Low-Hanging Fruit Features

Feature 2.1: WebSockets for Real-Time Communication

Description: The application currently uses HTTP polling for chat updates and watchparty video synchronization, which is inefficient. Upgrading to WebSockets will provide a true real-time experience and reduce server overhead. Implementation Plan:

Core Setup: Add Flask-SocketIO to the project dependencies and initialize SocketIO in app.py.
Text & Audio Messages: Refactor the polling routes in blueprints/chat.py to use WebSocket event handlers (e.g., @socketio.on('message'), @socketio.on('join')). The application currently supports audio messages (base64 webm blobs sent via the audio field). Crucially: Ensure the WebSocket payload for messages continues to accept and broadcast this audio field so voice notes continue to function seamlessly.
Watchparty Synchronization: Watchparties currently poll /watchparty/<room>/video to stay in sync. Refactor blueprints/watchparty.py and static/assets/js/watchparty_chat.js to broadcast video events over WebSockets (e.g., video_play, video_pause, video_sync, video_clear). This will replace the interval-based polling and provide instantaneous playback synchronization for all users in the room.
Frontend Updates: Update the frontend JavaScript files in static/assets/js/ (specifically chat.js and watchparty_chat.js) to connect via Socket.IO clients, emit messages/video-controls, and listen for incoming events instead of using setInterval.

Feature 2.2: Rate Limiting & Abuse Prevention

Description: Currently, there is no rate limiting on registration or chat endpoints. With the planned move to WebSockets (Feature 2.1), HTTP polling will be eliminated, but rate limiting is still essential. Implementation Plan:

Registration: Implement rate limiting on the HTTP /register endpoint to prevent bot account creation spam.
WebSockets: Implement a custom rate limiting mechanism within the WebSocket event handlers (e.g., tracking message timestamps per user session in memory) to prevent users from flooding chat rooms with messages (both text and base64 audio payloads) over the socket connection.

Description: Expand the watch party functionality to allow users to share their screen as an alternative to watching YouTube videos. WebSockets will be used for signaling the peer-to-peer connection. Implementation Plan:

WebRTC Signaling: Use the Flask-SocketIO setup from Feature 2.1 to act as a WebRTC signaling server, relaying SDP offers, answers, and ICE candidates between users in the watch party room.
Screen Capture: In static/assets/js/watchparty_chat.js, implement navigator.mediaDevices.getDisplayMedia() to capture the presenter's screen and audio.
Peer Connections: Establish RTCPeerConnections between the presenter and other attendees.
UI Integration: Add a "Share Screen" button to the watch party interface. When active, replace the YouTube <iframe> with a <video> element playing the incoming WebRTC stream.

3. Security Concerns