twitchChatOverlayServer/PLAN.md

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)

{
  "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
    }
  }
}