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

The project is in Phase 1: User Authentication & Database. Most of this phase is complete.

A solid FastAPI application skeleton is in place.
The database schema (User, Setting models) is defined using SQLAlchemy and a SQLite database.
A secure Twitch OAuth2 authentication flow is fully functional. It correctly:
1. Redirects users to Twitch.
2. Handles the callback.
3. Exchanges the authorization code for tokens.
4. Fetches user details from the Twitch API.
5. Encrypts the tokens using the cryptography library.
6. Saves or updates the user's record in the database.
A basic HTML login page is served at the root URL (/).
Configuration and secrets are managed securely via a config.py file that reads from a .env file.

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.

Dashboard Progress (Phase 2)

We have started work on Phase 2, focusing on the user dashboard. The following features have been implemented on the feature/dashboard-ui branch:

Dynamic Dashboard: The dashboard now uses the Jinja2 templating engine to dynamically display the logged-in user's username and their unique overlay URL.
Theme Selection: A theme selection dropdown has been added to the dashboard, allowing users to choose between a "Dark Purple" and a "Bright Green" overlay theme.
Settings API: A /api/settings endpoint has been created. This endpoint handles saving the user's chosen theme to the database.
Dynamic Overlay Theming: The /overlay/{user_id} endpoint now dynamically loads the correct HTML template based on the user's saved theme preference, providing a personalized overlay.

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).

11 KiB Raw Blame History