obs-ss-plugin-webui/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Next.js web application that controls multiple OBS Source Switchers. It provides a UI for managing stream sources across different screen layouts (large, left, right, topLeft, topRight, bottomLeft, bottomRight) and communicates with OBS WebSocket API to control streaming sources.

Key Commands

Development

• npm run dev - Start the development server
• npm run build - Build the production application
• npm start - Start the production server
• npm run lint - Run ESLint to check code quality
• npm run type-check - Run TypeScript type checking without emitting files

Database Management

• npm run create-sat-summer-2025-tables - Create database tables with seasonal naming convention

Architecture Overview

Technology Stack

• Frontend: Next.js 15.1.6 with React 19, TypeScript, and custom CSS with glass morphism design
• Backend: Next.js API routes
• Database: SQLite with sqlite3 driver
• OBS Integration: obs-websocket-js for WebSocket communication with OBS Studio
• Styling: Solarized Dark theme with CSS custom properties, Tailwind CSS utilities, and accessible glass morphism components

Project Structure

• /app - Next.js App Router pages and API routes
  • /api - Backend API endpoints for stream management
  • /streams - Streams management page (add new streams and view existing)
  • /teams - Team management page
  • /edit/[id] - Individual stream editing
• /components - Reusable React components (Header, Footer, Dropdown)
• /lib - Core utilities and database connection
  • database.ts - SQLite database initialization and connection management
  • obsClient.js - OBS WebSocket client with persistent connection management
  • constants.ts - Dynamic table naming system for seasonal deployments
• /types - TypeScript type definitions
• /files - Default directory for SQLite database and text files (configurable via .env.local)
• /scripts - Database setup and management scripts
• /.forgejo/workflows - Forgejo CI/CD workflows for self-hosted runners

Key Architectural Concepts

1. Dynamic Table Naming System: Uses seasonal configuration for table names (e.g., streams_2025_summer_sat, teams_2025_summer_sat) to support recurring deployments

2. Persistent OBS Connection Management: Single WebSocket connection shared across all API requests with automatic reconnection and connection state tracking

3. Dual Integration Pattern:

   • WebSocket API for direct OBS control (source creation, status monitoring)
   • Text file system for OBS Source Switcher plugin integration (source switching)

4. Solarized Dark Design System: Accessible colorblind-friendly theme based on Solarized Dark palette with:

   • High contrast ratios (7.5:1+) meeting WCAG AAA standards
   • CSS custom properties for maintainable theming
   • Glass morphism effects with proper backdrop blur
   • Distinctive active navigation states for clear wayfinding

5. Screen Position Management: Seven distinct screen positions (large, left, right, topLeft, topRight, bottomLeft, bottomRight) with individual source control

6. Real-time Status Monitoring: Footer component polls OBS status every 30 seconds showing connection, streaming, and recording status

Environment Configuration

• FILE_DIRECTORY: Directory for database and text files (default: ./files)
• OBS_WEBSOCKET_HOST: OBS WebSocket host (default: 127.0.0.1)
• OBS_WEBSOCKET_PORT: OBS WebSocket port (default: 4455)
• OBS_WEBSOCKET_PASSWORD: OBS WebSocket password (optional)
• API_KEY: Required for API authentication (set in production)

API Endpoints

Stream Management

• POST /api/addStream - Add new stream to database and create browser source in OBS
• GET /api/streams - Get all available streams
• GET /api/streams/[id] - Individual stream operations

Source Control

• POST /api/setActive - Set active stream for specific screen position
• GET /api/getActive - Get currently active sources for all screens

Team Management

• GET /api/teams - Get all teams
• GET /api/getTeamName - Get team name by ID

System Status

• GET /api/obsStatus - Real-time OBS connection and streaming status

Database Schema

Dynamic table names with seasonal configuration:

• streams_YYYY_SEASON_SUFFIX: id, name, obs_source_name, url, team_id
• teams_YYYY_SEASON_SUFFIX: team_id, team_name

OBS Integration Pattern

The app uses a sophisticated dual integration approach:

1. WebSocket Connection: Direct OBS control using obs-websocket-js with persistent connection management
2. Text File System: Each screen position has a corresponding text file that OBS Source Switcher monitors

Required OBS Source Switchers (must be created with these exact names):

• ss_large - Large screen source switcher
• ss_left - Left screen source switcher
• ss_right - Right screen source switcher
• ss_top_left - Top left screen source switcher
• ss_top_right - Top right screen source switcher
• ss_bottom_left - Bottom left screen source switcher
• ss_bottom_right - Bottom right screen source switcher

See OBS Setup Guide for detailed configuration instructions.

Source Control Workflow:

1. User selects stream in React UI
2. API writes source name to position-specific text file (e.g., large.txt, left.txt)
3. OBS Source Switcher detects file change and switches to specified source
4. Real-time status updates via WebSocket API

Connection Management: The OBS client ensures a single persistent connection across all API requests with automatic reconnection handling and connection state validation.

Component Patterns

• Client Components: All interactive components use 'use client' directive for React 19 compatibility
• Optimistic Updates: UI updates immediately with error rollback for responsive user experience
• Consistent Layout: Glass morphism design with unified component styling across all pages
• Responsive Design: Grid layouts adapt to different screen sizes with mobile-first approach

Security Architecture

Authentication: API key-based authentication protects all API endpoints through Next.js middleware

Input Validation: Comprehensive validation using centralized security utilities in /lib/security.ts:

• Screen parameter allowlisting prevents path traversal attacks
• URL validation ensures only http/https protocols
• String sanitization removes potentially dangerous characters
• Integer validation prevents injection attacks

Path Protection: File operations are restricted to allowlisted screen names, preventing directory traversal

Error Handling: Secure error responses that don't leak system information