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

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
│   │   └── twitch/         # Twitch API proxy
│   │       └── status/     # Check stream status
│   ├── 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
│   │   └── SupportModule.tsx # Sidebar support & social module
│   ├── overlay/            # Overlay-specific components
│   │   ├── ChatContainer.tsx
│   │   └── Message.tsx
│   └── ui/                 # Reusable UI components (buttons, inputs)
├── lib/
│   ├── supabase.ts         # Supabase client
│   ├── twitch.ts           # Twitch API helpers
│   ├── 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.
• Enhanced Settings:
  • Resolution Selection (720p/1080p).
  • Quick "Copy Overlay URL" button.
• Right Panel: Live preview component rendering mock chat messages with the current settings applied.
• Support Module: Sidebar widget showing developer's live status (via Twitch API) and social/donation links.
• 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.

Hosting & Infrastructure

• Target: Proxmox LXC or VM (standalone).
• Architecture: Client-side processing via tmi.js to ensure the server handles only authentication and configuration serving.
• Cost Efficiency: Designed for "near-zero" server overhead to allow hosting on minimal hardware resources.
• Environment: The development machine is exclusively for coding; the service will never be hosted on the dev machine.

Implementation Phases

1. Project Initialization: Scaffolding Next.js, Tailwind, and Supabase client. [Completed]
2. Authentication: Implementing NextAuth with Twitch. [In Progress]
3. Database: Designing the Schema and connecting Supabase.
4. Dashboard UI: Building the Style Creator and Preview. [Completed]
   • Added: Support Module, Resolution settings, Copy Link.
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,
    "resolution": "1080p", 
    "emotes": {
      "bttv": true,
      "seventv": true
    }
  }
}