diff --git a/.gitignore b/.gitignore index 1d14aae..bc3495f 100644 --- a/.gitignore +++ b/.gitignore @@ -42,4 +42,7 @@ env/ !.env.example # Personal notes - will not be tracked by git -personal_notes.md \ No newline at end of file +personal_notes.md + +# Local-only directory for untracked notes and context +local/ \ No newline at end of file diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..45c3fe8 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,189 @@ +# 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. + +## 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). + +``` \ No newline at end of file