ramforth/MultiChatOverlay
3
2
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity

Day close: Added memory for AI agent. Added small corrections to DEVELOPMENT_PLAN.

Browse Source
This commit is contained in:
ramforth
2025-11-17 01:45:25 +01:00
parent 35c2210305
commit cafb39d9df
2 changed files with 193 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.gitignore vendored
View File

@@ -43,3 +43,6 @@ env/
# Personal notes - will not be tracked by git # Personal notes - will not be tracked by git
personal_notes.md personal_notes.md
# Local-only directory for untracked notes and context
local/

189
CONTEXT.md Normal file
View File

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