commit 4ff381f941a02950148956109ac20251aab8a862
Author: ramforth <ramforth@noreply.localhost>
Date:   Mon Jan 5 20:29:58 2026 +0100

    Initial commit: Project plan and documentation

diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
new file mode 100644
index 0000000..1b832c0
--- /dev/null
+++ b/DOCUMENTATION.md
@@ -0,0 +1,38 @@
+# OpenChat Overlay Documentation
+
+## Overview
+OpenChat Overlay is a lightweight, open-source Twitch chat overlay solution designed to be hosted on minimal hardware (like a Proxmox LXC container). It provides a user-friendly dashboard for customization and a highly optimized, client-side rendered overlay URL.
+
+## Getting Started
+
+### Prerequisites
+- Node.js (v18+)
+- Supabase Account
+- Twitch Developer Application (Client ID & Secret)
+
+### Installation
+1.  Clone the repository.
+2.  Install dependencies:
+    ```bash
+    npm install
+    ```
+3.  Configure environment variables in `.env.local`:
+    ```env
+    NEXT_PUBLIC_SUPABASE_URL=...
+    NEXT_PUBLIC_SUPABASE_ANON_KEY=...
+    NEXTAUTH_SECRET=...
+    TWITCH_CLIENT_ID=...
+    TWITCH_CLIENT_SECRET=...
+    ```
+4.  Run the development server:
+    ```bash
+    npm run dev
+    ```
+
+## Architecture Notes
+- The application uses **Next.js App Router**.
+- **Dashboard:** Located in `src/app/(dashboard)`. Protected by authentication.
+- **Overlay:** Located in `src/app/overlay/[token]`. Publicly accessible but requires a valid token. Renders with a transparent background.
+
+## Deployment
+(To be added: Instructions for building the Docker image and deploying to an LXC container.)
diff --git a/PLAN.md b/PLAN.md
new file mode 100644
index 0000000..0a2976a
--- /dev/null
+++ b/PLAN.md
@@ -0,0 +1,100 @@
+# Project Plan: OpenChat Overlay
+
+## Mission
+To build "OpenChat Overlay"—a free, open-source alternative to StreamElements, focused on extraordinary simplicity. Users should never touch a line of code.
+
+## Core Technical Stack
+- **Frontend:** Next.js (App Router)
+- **Database:** Supabase (Auth + PostgreSQL)
+- **Styling:** Tailwind CSS (Dashboard), CSS Injection (Overlay)
+- **Chat Client:** `tmi.js` or `comfy.js` (Client-side)
+
+## Architecture
+
+### Next.js Folder Structure (Proposed)
+```
+src/
+├── app/
+│   ├── (dashboard)/        # Route group for the authenticated dashboard
+│   │   ├── layout.tsx      # Dashboard layout (sidebar, auth checks)
+│   │   ├── page.tsx        # Main dashboard view
+│   │   ├── editor/         # The "Style Creator"
+│   │   │   └── page.tsx
+│   │   └── settings/       # Account settings
+│   │       └── page.tsx
+│   ├── api/                # API Routes
+│   │   ├── auth/           # NextAuth handlers
+│   │   │   └── [...nextauth]/route.ts
+│   │   └── overlay/        # Overlay configuration endpoints
+│   │       └── [token]/route.ts
+│   ├── overlay/            # The public overlay view
+│   │   └── [token]/        # Dynamic route for user overlay
+│   │       ├── layout.tsx  # Transparent background layout
+│   │       └── page.tsx    # The actual chat overlay component
+│   └── globals.css         # Tailwind directives
+├── components/
+│   ├── dashboard/          # Dashboard-specific components
+│   │   ├── PreviewFrame.tsx # Live preview iframe/component
+│   │   └── StyleControls.tsx # Form for editing styles
+│   ├── overlay/            # Overlay-specific components
+│   │   ├── ChatContainer.tsx
+│   │   └── Message.tsx
+│   └── ui/                 # Reusable UI components (buttons, inputs)
+├── lib/
+│   ├── supabase.ts         # Supabase client
+│   ├── utils.ts            # Helper functions
+│   └── types.ts            # TypeScript interfaces
+└── hooks/                  # Custom React hooks (useChat, useSettings)
+```
+
+## Key Features & Logic
+
+### 1. One-Click Twitch Auth
+- **Provider:** NextAuth.js with Twitch.
+- **Action:** Authenticate user -> Check if exists in Supabase -> Create profile if new.
+
+### 2. The "Style Creator"
+- **Left Panel:** Controls for font family, size, colors, opacity, badge toggles, and 7TV/BTTV emote toggles.
+- **Right Panel:** Live preview component rendering mock chat messages with the current settings applied.
+- **State:** React state manages unsaved changes; "Save" pushes to Supabase.
+
+### 3. The "Secret Sauce" URL (`/overlay/[token]`)
+- **Route:** `src/app/overlay/[token]/page.tsx`
+- **Behavior:**
+    1.  Validates `token` against Supabase.
+    2.  Fetches user configuration JSON.
+    3.  Injects configuration into the chat component styles.
+    4.  Connects to Twitch chat via `tmi.js` using the user's channel name.
+- **Styling:** Background must be transparent (`bg-transparent`).
+
+### 4. Real-time Chat
+- **Library:** `tmi.js` (client-side execution).
+- **Cost:** Zero server-side WebSocket processing.
+
+## Implementation Phases
+1.  **Project Initialization:** Scaffolding Next.js, Tailwind, and Supabase client.
+2.  **Authentication:** Implementing NextAuth with Twitch.
+3.  **Database:** Designing the Schema and connecting Supabase.
+4.  **Dashboard UI:** Building the Style Creator and Preview.
+5.  **Overlay Logic:** Creating the standalone overlay page and chat connection.
+6.  **Deployment:** Docker/LXC containerization.
+
+## Data Schema (Settings)
+```json
+{
+  "user_id": "uuid",
+  "overlay_token": "string (unique)",
+  "settings": {
+    "fontFamily": "Inter, sans-serif",
+    "fontSize": "14px",
+    "textColor": "#ffffff",
+    "backgroundColor": "#000000",
+    "backgroundOpacity": 0.5,
+    "showBadges": true,
+    "emotes": {
+      "bttv": true,
+      "seventv": true
+    }
+  }
+}
+```