From 62ee9ad95428fb78c7419001f850f117825df0c6 Mon Sep 17 00:00:00 2001 From: ramforth Date: Sun, 16 Nov 2025 17:04:19 +0100 Subject: [PATCH] howto, tasks and readme update --- CONTRIBUTING.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 27 ++++++++++++++-- TASKS.md | 64 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 171 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 TASKS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8cf64be --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,82 @@ +# Contribution & Workflow Guide + +Welcome to the MultiChatOverlay project! To ensure we can collaborate effectively and avoid errors, we follow a strict and professional development workflow. + +## 📜 The Golden Rules + +1. **Gitea is the Source of Truth.** The `main` branch on our Gitea server is the *only* source of truth. +2. **NEVER Commit to `main`.** All work must be done in a separate "feature branch" and submitted as a Pull Request. +3. **NEVER Work on the Server.** The staging server (`192.168.10.33`) is for *testing* the `main` branch. It is **NOT** a development environment. All development must be done on your **local machine**. + +--- + +## 🛠️ Your Local Setup (One Time) + +You only need to do this once. + +1. **Install Tools:** + * [Git](https://git-scm.com/downloads) + * [Visual Studio Code](https://code.visualstudio.com/) + * [Python 3.9+](https://www.python.org/downloads/) +2. **Clone the Repo:** Clone the project from our Gitea server to your local computer: + ```bash + git clone [https://gitea.ramforth.net/ramforth/MultiChatOverlay.git](https://gitea.ramforth.net/ramforth/MultiChatOverlay.git) + cd MultiChatOverlay + ``` +3. **Install VS Code Extensions:** + * Open the `MultiChatOverlay` folder in VS Code. + * Go to the Extensions tab and install: + * `Python` (Microsoft) + * `Gemini` (Google) +4. **Create Your Virtual Environment:** + ```bash + # From the terminal in VS Code + python -m venv venv + ``` + * VS Code should auto-detect this and ask to use it. Click "Yes." +5. **Install Dependencies:** + ```bash + # Make sure your 'venv' is activated + pip install -r requirements.txt + ``` + +You are now ready to develop! + +--- + +## 💡 Your Daily Workflow (The "Loop") + +This is the process you will follow *every time* you want to add a new feature or fix a bug. + +1. **Get Latest Code:** Make sure your local `main` branch is up-to-date. + ```bash + git checkout main + git pull + ``` +2. **Create a New Branch:** Create a new branch for your task. Name it clearly (e.g., `feature/twitch-auth`, `bugfix/css-error`). + ```bash + git checkout -b feature/my-new-feature + ``` +3. **Write Code!** + * This is where you do your work. + * Use the **Gemini plugin** in VS Code to help you. + * **Pro-tip:** Open the Gemini chat and give it context by pasting in files like `DEVELOPMENT_PLAN.md` or the `TASKS.md` file so it understands the goal. +4. **Test Locally:** Run the FastAPI server on your *local* machine to make sure your feature works and doesn't break anything. + ```bash + uvicorn main:app --reload + ``` +5. **Commit Your Work:** Once it's working, save your changes. + ```bash + git add . + git commit -m "Add new feature: brief description here" + ``` +6. **Push Your Branch:** Push your *new branch* (not `main`) to Gitea. + ```bash + git push -u origin feature/my-new-feature + ``` +7. **Open a Pull Request:** + * Go to the Gitea website. + * You will see a prompt to "Open a Pull Request" for your new branch. + * Fill it out, describe your changes, and submit it for review. + +A project lead will then review your code, and once approved, it will be merged into the `main` branch and deployed to the staging server for final testing. \ No newline at end of file diff --git a/README.md b/README.md index f733fa7..97af82e 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,28 @@ # MultiChatOverlay -A multi-user, web-based chat overlay service for streamers on platforms like Twitch and YouTube. +MultiChatOverlay is a web-based, multi-platform chat overlay service designed for streamers. The goal is to create a "SaaS" (Software as a Service) project where users can log in with their platform accounts (Twitch, YouTube, etc.) and get a single, unified, and customizable chat overlay for their stream. -This service aggregates chat from connected accounts into a customizable browser source for use in streaming software. \ No newline at end of file +This project is currently in **Phase 1: Initial Development**. + +## 🚀 Project Goal + +* **Unified Chat:** Aggregate chat from multiple platforms (starting with Twitch & YouTube) into one browser source. +* **Customization:** Allow users to save their own custom CSS and use templates. +* **Interaction:** Provide "single message focus" and other moderation tools for streamers and their teams. +* **Self-Hosted:** The service is hosted by the project owner (you) and provided to users. + +## 💻 Technology Stack + +* **Backend:** Python 3.9+ (FastAPI) +* **Database:** SQLite (initially, for simplicity) with SQLAlchemy +* **Chat Listeners:** `twitchio` (Twitch), `pytchat` (YouTube) +* **Frontend:** Vanilla HTML5, CSS3, and JavaScript (Fetch API, WebSockets) +* **Authentication:** OAuth2 for all external platforms. + +## 📖 Development & Contribution + +This project follows a professional development workflow. Gitea is our single source of truth. + +* **Want to contribute?** See our `CONTRIBUTING.md` file for the complete setup guide and workflow rules. +* **Looking for a task?** See the `TASKS.md` file for a list of current jobs, broken down by phase. +* **Want the full plan?** See the `DEVELOPMENT_PLAN.md` for the complete project roadmap. \ No newline at end of file diff --git a/TASKS.md b/TASKS.md new file mode 100644 index 0000000..12a71f8 --- /dev/null +++ b/TASKS.md @@ -0,0 +1,64 @@ +# 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." + +--- + +## 🚀 Phase 1: User Authentication & Database + +* **Goal:** Get the basic API, database, and Twitch login flow working. + +### To Do +* `[ ]` **1.1: Database Schema:** Define SQLAlchemy models for `User` (id, username, platform, encrypted_tokens) and `Settings`. +* `[ ]` **1.2: Twitch OAuth API:** Create FastAPI endpoints for `/login/twitch` (redirect) and `/auth/twitch/callback` (handles token exchange). +* `[ ]` **1.3: Secure Token Storage:** Implement helper functions to `encrypt` and `decrypt` OAuth tokens before storing them in the database. +* `[ ]` **1.4: Basic Session Management:** Create a simple session/JWT system to know *who* is logged in. +* `[ ]` **1.5: Login Frontend:** Create a basic `login.html` file with a "Login with Twitch" button. + +### In Progress +* `[ ]` **1.0: Project Skeleton** - @ProjectLead + * *Task:* Setup `main.py`, `requirements.txt`, and `.gitignore`. + +### Done +* *(Nothing yet!)* + +--- + +## ⏳ 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