# Multi-Platform Chat Overlay Development Plan (v3)

This document outlines the development plan for a multi-user, web-based chat overlay service.

## 1. Project Overview

The goal is to create a service where streamers can log in using their platform accounts (Twitch, YouTube), configure a personalized chat overlay, and use it in their streaming software (e.g., OBS). The service will aggregate chat from their connected accounts and provide moderation tools.

## 2. Architecture

The system will be a web application with a Python backend and a web-based frontend.

1.  **Python Backend (FastAPI):**
    *   Manages user authentication (OAuth2 for Twitch and YouTube).
    *   Stores user data, configuration, and encrypted access tokens in a database (SQLite initially).
    *   Provides a REST API for the frontend to manage user settings.
    *   Dynamically starts, stops, and manages chat listener processes for active users.
    *   Runs a WebSocket server to broadcast chat messages to the correct user's overlay.

2.  **Frontend (HTML/CSS/JavaScript):**
    *   **Login Page:** Allows users to sign in with their Twitch or YouTube accounts.
    *   **Dashboard:** A secure area for users to manage their connected accounts, configure their overlay, and get their unique overlay URL.
    *   **Web Overlay:** The customizable chat display, loaded as a Browser Source in OBS.

## 3. Technology Stack

*   **Backend:**
    *   **Language:** Python 3.9+
    *   **Web Framework:** FastAPI
    *   **Database:** SQLite with SQLAlchemy
    *   **Authentication:** OAuth2 (via `httpx` or a similar library)
    *   **Chat Listeners:** `pytchat` (YouTube), `TwitchIO` (Twitch)

*   **Frontend:**
    *   **Markup/Styling:** HTML5, CSS3
    *   **JavaScript:** Vanilla JavaScript
    *   **Communication:** Fetch API, WebSockets

## 4. Implementation Roadmap

### Phase 1: User Authentication & Database
1.  **Database Setup:**
    *   Initialize a SQLite database.
    *   Define the database schema using SQLAlchemy for a `users` table (storing profile info, channel IDs, and encrypted OAuth tokens).
2.  **Install Dependencies:** Add `SQLAlchemy` and an OAuth library to the project.
3.  **OAuth2 for Twitch:**
    *   Implement the FastAPI backend routes for Twitch login (`/login/twitch`) and the callback (`/auth/twitch/callback`).
    *   Securely store user profile information and tokens in the database.
4.  **Login Frontend:** Create a `login.html` page with a "Login with Twitch" button.
5.  **Session Management:** Implement basic session management to keep users logged in.

### Phase 2: User Dashboard & Configuration
1.  **Dashboard UI:** Create a `dashboard.html` page that is only accessible to logged-in users.
2.  **Display User Data:** Show the user's connected Twitch account information.
3.  **Configuration API:** Create backend API endpoints for users to submit and update their settings (e.g., which chat platforms to connect, overlay appearance settings).
4.  **Configuration Form:** Add a form to the dashboard for users to manage these settings.
5.  **Overlay URL:** Generate and display a unique, persistent overlay URL for the user (e.g., `/overlay/{user_id}`).

### Phase 3: Dynamic Chat Listeners & Basic Overlay
1.  **Listener Management:**
    *   Design a system to start and stop chat listener processes based on user activity (e.g., when a user is "live" or has the dashboard open). This may involve a background task manager.
    *   Refactor the existing `chat_listeners.py` to be controlled by this manager.
2.  **User-Specific Broadcasting:**
    *   Update the WebSocket system to route messages from a specific listener to that user's overlay instance.
3.  **Basic User Overlay:**
    *   When a user accesses their unique overlay URL, the backend serves the `index.html` overlay.
    *   The overlay connects to the WebSocket and receives only that user's chat messages.

### Phase 4: YouTube Integration & Advanced Features
1.  **OAuth2 for YouTube:**
    *   Implement the backend routes for YouTube login and callback.
    *   Update the database and dashboard to handle a second connected account.
2.  **Moderator & Host Panels:** Re-introduce the concepts of the Host and Moderator panels from v2, but adapted for the multi-user model. This will involve secure access and user-specific controls.
3.  **Advanced Overlay Customization:** Add more options for users to customize the look and feel of their overlay via the dashboard.

## 5. Requirements for Completion (Initial Version)

The project will be considered complete for its initial version when Phases 1, 2, and 3 are functional:
1.  Users can log in with their Twitch account.
2.  Users can see their unique overlay URL on a dashboard.
3.  The overlay successfully connects to their Twitch chat and displays messages when opened in a browser source.