# 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:**
1. **Core Setup:** Add `Flask-SocketIO` to the project dependencies and initialize SocketIO in `app.py`.
2. **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. 
3. **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.
4. **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:**
1. **Registration:** Implement rate limiting on the HTTP `/register` endpoint to prevent bot account creation spam.
2. **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.

### Feature 2.3: WebSocket Screen Sharing for Watch Parties
**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:**
1. **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.
2. **Screen Capture:** In `static/assets/js/watchparty_chat.js`, implement `navigator.mediaDevices.getDisplayMedia()` to capture the presenter's screen and audio.
3. **Peer Connections:** Establish `RTCPeerConnection`s between the presenter and other attendees.
4. **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
*(No pending issues in this category at this time)*