# 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
    }
  }
}
```