howto, tasks and readme update

.gitignore

@@ -0,0 +1,42 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environments
+venv/
+env/
+.venv/
+.env/
+
+# SQLite databases
+*.db
+*.sqlite
+*.sqlite3
+
+# Environment variables
+.env
+.env.*
+!.env.example

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.

README.md

@@ -0,0 +1,28 @@
+# MultiChatOverlay
+
+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 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.

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

main.py

@@ -0,0 +1,7 @@
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.get("/")
+async def read_root():
+    return {"message": "MultiChatOverlay API"}

requirements.txt

@@ -0,0 +1,4 @@
+fastapi
+uvicorn[standard]
+sqlalchemy
+httpx