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

* `[ ]` **1.4: Basic Session Management:** Create a simple session/JWT system to know *who* is logged in.

### In Progress

### 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.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.
* *(All tasks for this phase are on hold until Phase 1 is complete)*

### To Do
* `[ ]` **2.1: Dashboard UI:** Create `dashboard.html` (only for logged-in users).
* `[ ]` **2.2: Config API:** Create API endpoints (`GET`, `POST`) for `/api/settings` to save/load user preferences (e.g., custom CSS).
* `[ ]` **2.3: Overlay URL:** Generate and display the unique overlay URL for the user (e.g., `/overlay/{user_id}`).

---

## 💬 Phase 3: Dynamic Listeners & Basic 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
* `[ ]` **3.1: Dynamic Listener Manager (The Big One):** Design a system (e.g., background service) to start/stop listener processes for users.
* `[ ]` **3.2: User-Specific Broadcasting:** Update the WebSocket system to use "rooms" (e.g., `/ws/{user_id}`) so users only get their *own* chat.
* `[ ]` **3.3: Basic Overlay UI:** Create the `overlay.html` page that connects to the WebSocket and displays messages.

---

## 💡 Backlog & Future Features

* *(Tasks from Phase 4, Gitea Issues, etc., will be added here as we go)*
* `[ ]` Implement YouTube OAuth & `pytchat` listener (Phase 4).
* `[ ]` "Single Message Focus" feature (Issue #1).
* `[ ]` Moderator panels (Issue #2).
* `[ ]` Custom CSS storage & injection (Issue #6).

10 KiB Raw Blame History