# Gemini Code Assist: Project Context This document outlines my core instructions and my current understanding of the MultiChatOverlay project. --- ## Part 1: My Core Instructions My primary function is to act as a world-class senior software engineering assistant. My goal is to provide insightful answers that prioritize code quality, clarity, and adherence to best practices. My core instructions are: * **Persona:** Gemini Code Assist, a very experienced coding assistant. * **Objective:** Answer questions thoroughly, review code, and suggest improvements. * **Output Format:** * Provide all code changes as diffs in the unified format, using full absolute file paths. * Ensure all code blocks are valid and well-formatted. * Suggest relevant next steps or prompts for our workflow. * Maintain a conversational, accurate, and helpful tone. --- ## Part 2: My Understanding of the Project ### Project Goal The objective is to build a multi-platform chat overlay SaaS (Software as a Service) for streamers. The service will aggregate chat from Twitch and YouTube into a single, customizable browser source for use in streaming software like OBS. ### Current Status **Phases 1, 2, and 3 are complete.** The application is now a fully functional chat overlay service for Twitch. * **Phase 1 (Authentication):** A secure Twitch OAuth2 flow is implemented, with user data and encrypted tokens stored in a SQLite database. * **Phase 2 (Dashboard & Configuration):** A dynamic user dashboard is available after login. It includes a theme switcher (light/dark), a theme selector for the overlay, and a full CRUD system for users to create and manage their own private CSS themes. * **Phase 3 (Real-time Chat):** A decoupled background listener manager successfully starts `twitchio` listeners for each user. A WebSocket manager broadcasts incoming chat messages to the correct user's overlay in real-time. * A basic HTML login page is served at the root URL (`/`). ### Core Architecture The project is built on the "hybrid architecture" detailed in the `RESEARCH_REPORT.md`: * **Authentication:** Always use the official, secure OAuth2 flows for each platform. * **Twitch Chat Ingestion:** Use the stable and scalable Twitch IRC protocol (via `twitchio`). * **YouTube Chat Ingestion:** Use an unofficial, reverse-engineered "InnerTube" API (via `pytchat`). This is the primary technical risk of the project due to its fragility and will require careful implementation with proxy rotation and monitoring. ### Immediate Next Task Based on the `TASKS.md` file, the only remaining task for Phase 1 is: * **Task 1.4: Basic Session Management:** After a user successfully logs in, we need to create a persistent session for them. This will allow us to "remember" who is logged in, protect routes like the future `/dashboard`, and provide a seamless user experience. The current flow correctly authenticates the user but does not yet establish this persistent session. ## References: ### Development plan ``` # Multi-Platform Chat Overlay Development Plan (v4 - Simplified Stack) This document outlines the development plan for a multi-user, web-based chat overlay service using a simplified technology stack. ## 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. Technology Stack * **Team Communications:** Discord and Nextcloud, primarily. This can change. There's a list of links in the [README.md](README.md) * **Backend:** Python 3.13+ (FastAPI) * **Database:** SQLite (for initial development) with SQLAlchemy ORM * **Frontend:** Vanilla HTML, CSS, and JavaScript * **Chat Listeners:** `twitchio` (Twitch), `pytchat` (YouTube) ## 3. Implementation Roadmap ### Phase 1: User Authentication & Database (FastAPI) 1. **Project Skeleton:** Establish the core FastAPI application structure, dependencies, and version control. 2. **Database Schema:** Define the data models for users and settings using SQLAlchemy. 3. **Twitch OAuth2:** Implement the server-side OAuth2 flow within FastAPI to authenticate users and securely store encrypted tokens in the database. 4. **Session Management:** Create a system to manage logged-in user sessions. 5. **Basic Frontend:** Develop a simple login page. ### Phase 2: User Dashboard & Configuration 1. **Dashboard UI:** Create a dashboard page accessible only to authenticated users. 2. **Settings API:** Build API endpoints for users to save and retrieve their overlay settings (e.g., custom CSS). 3. **Overlay URL Generation:** Display a unique, persistent overlay URL for each user on their dashboard. ### Phase 3: Dynamic Listeners & Basic Overlay 1. **Dynamic Listener Manager:** Design and build a background service that starts and stops chat listener processes (`twitchio`, `pytchat`) based on user activity. 2. **Real-time Message Broadcasting:** Implement a WebSocket system within FastAPI to push chat messages to the correct user's overlay in real-time. 3. **Basic Overlay UI:** Create the `overlay.html` page that connects to the WebSocket and renders incoming chat messages. ### Phase 4: Integration & Refinement 1. **YouTube Integration:** Implement the full YouTube OAuth2 flow and integrate the `pytchat` listener into the dynamic listener manager. 2. **Advanced Overlay Customization:** Add more features for users to customize their overlay's appearance and behavior. 3. **Twitch Chat Writeback:** Re-introduce the `chat:write` scope during authentication to allow the service (and potentially moderators, as per Issue #2) to send messages to the user's Twitch chat. ## 4. 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. ## 6. Future Enhancements from Gitea Issues These are enhancement suggestions gathered from the project's Gitea issues, representing potential future features or considerations: * **Issue #1: Multi select chat display order** * Allow streamer to click on messages that appear whilst discussing chat message already on screen. This will enable quick progress through important messages without having to scroll back up chat. * **Issue #2: Moderator chat assistance with streamer over ride** * Moderators can select messages on their end, marking them for discussion, freeing up the streamer to simply stream. The streamer would have override to reject messages as the stream owner. * **Issue #3: Chat Speed toggle for busier chat streams** * Implement a toggle to adjust the display speed of chat messages, useful for very active streams. * **Issue #4: Auto add YT Superchats to Highlights** * Add a setting to automatically include YouTube Superchats in the highlighted messages. * **Issue #5: Donations page somewhere** * Consider integrating a donations page or feature within the service. ``` ### Tasks ``` # Project Task List This file tracks all active development tasks. It is based on the official `DEVELOPMENT_PLAN.md`. ## 📋 How to Use This List 1. Find a task in the "To Do" section that you want to work on. 2. Add your name next to it (e.g., `[ ] Task Name - @YourName`). 3. When you start, move it to "In Progress" and follow the `CONTRIBUTING.md` workflow. 4. When your Pull Request is *merged*, move it to "Done." If you want to use emojis for visibility, here's some I have used: ✔️ - Done | 🧑‍🔧 - In progress | ↗️ - Task evolved (should correspond with an edit in the [DEVELOPMENT_PLAN.md](DEVELOPMENT_PLAN.md) ) --- ## 🚀 Phase 1: User Authentication & Database * **Goal:** Get the basic API, database, and Twitch login flow working. ### To Do ### Done * `[✔️]` **1.0: Project Skeleton** - @ramforth * *Task:* Setup `main.py`, `requirements.txt`, and `.gitignore`. * `[✔️]` **1.1: Database Schema:** Define SQLAlchemy models for `User` (id, username, platform, encrypted_tokens) and `Settings`. @ramforth * `[✔️]` **1.1.5: Discord Overview:** Create an automated 'TASK-LIST' and post to Discord whenever someone pushes a change to the repository. @ramforth * `[✔️]` **1.2: Twitch OAuth API:** Create FastAPI endpoints for `/login/twitch` (redirect) and `/auth/twitch/callback` (handles token exchange). @ramforth * `[✔️]` **1.3: Secure Token Storage:** Implement helper functions to `encrypt` and `decrypt` OAuth tokens before storing them in the database. @ramforth * `[✔️]` **1.4: Basic Session Management:** Create a simple session/JWT system to know *who* is logged in. @ramforth * `[✔️]` **1.5: Login Frontend:** Create a basic `login.html` file with a "Login with Twitch" button. @ramforth --- ## ⏳ Phase 2: User Dashboard & Configuration * **Goal:** Allow logged-in users to see a dashboard, get their overlay URL, and save settings. Now that Phase 1 is done, these tasks are ready to be worked on. ### To Do * `[ ]` **2.4: Create Logo and Favicon:** The project should have a logo and a favicon. ### Done * `[✔️]` **2.0: CSS Refactor & Styling:** Improved the general look and feel of the application pages, including a light/dark theme switcher. * `[✔️]` **2.1: Dashboard UI:** Created `dashboard.html` for logged-in users to manage settings. * `[✔️]` **2.2: Config API:** Created API endpoints for `/api/settings` to save user preferences. * `[✔️]` **2.3: Overlay URL:** Generated and displayed the unique overlay URL for the user on the dashboard. * `[✔️]` **2.5: Custom CSS Themes:** Implemented a system for users to create, preview, and delete their own private CSS overlay themes. * `[✔️]` **2.6: CSS Help Page:** Created a guide for users on how to write custom CSS for their overlays. --- ## 💬 Phase 3: Real-time Chat & Overlay * **Goal:** The core magic. Start chat listeners for users and show messages in the overlay. * *(All tasks for this phase are on hold until Phase 2 is complete)* ### To Do --- ### Done * `[✔️]` **3.1: Dynamic Listener Manager:** Designed and implemented a system to start/stop listener processes for users on application startup/shutdown. * `[✔️]` **3.2: User-Specific Broadcasting:** Implemented a WebSocket manager and endpoint (`/ws/{user_id}`) to broadcast messages to the correct user's overlay. * `[✔️]` **3.3: Basic Overlay UI:** Created dynamic overlay templates that connect to the WebSocket and display incoming chat messages. ## 💡 Backlog & Future Features * `[ ]` Implement YouTube OAuth & `pytchat` listener (Phase 4). * `[ ]` "Single Message Focus" feature (Issue #1). * `[ ]` Moderator panels (Issue #2). ```