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
• npm run migrate-add-group-uuid - Add group_uuid column to existing teams table (one-time migration)

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, Toast)
• /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
  • useToast.ts - Toast notification system for user feedback
  • security.ts - Input validation and sanitization utilities
• /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

7. UUID-based OBS Group Tracking: Robust synchronization between database teams and OBS scenes using UUID identifiers to handle manual renames and ensure data consistency

8. Toast Notification System: User-friendly feedback system with success, error, and informational messages for all operations

9. Stream Deletion with Confirmation: Safe deletion workflow that removes streams from both OBS and database with user confirmation prompts

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 (accepts Twitch username, auto-generates URL)
• GET /api/streams - Get all available streams
• GET /api/streams/[id] - Get individual stream details
• DELETE /api/streams/[id] - Delete stream from both OBS and database with confirmation

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 with group information
• POST /api/teams - Create new team
• PUT /api/teams/[id] - Update team name, group_name, or group_uuid
• DELETE /api/teams/[id] - Delete team and associated streams
• GET /api/getTeamName - Get team name by ID
• POST /api/createGroup - Create OBS group from team and store UUID
• POST /api/syncGroups - Synchronize all teams with OBS groups
• GET /api/verifyGroups - Verify database groups exist in OBS with UUID tracking

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, group_name, group_uuid

Database Fields:

• streams table: Stores stream information with team associations
• teams table: Stores team information with optional OBS group mapping
  • group_name: Human-readable OBS scene name
  • group_uuid: OBS scene UUID for reliable tracking (handles renames)

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
3. UUID-based Group Management: Teams mapped to OBS scenes with UUID tracking for reliable synchronization
   • Primary matching by UUID for rename-safe tracking
   • Fallback to name matching for backward compatibility
   • Automatic detection of name changes and sync issues
   • UI actions for resolving synchronization problems

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.

Group Synchronization Workflow:

1. Team creation optionally creates corresponding OBS scene
2. UUID stored in database for reliable tracking
3. Verification system detects sync issues (missing groups, name changes)
4. UI provides actions to fix sync problems:
   • "Clear Invalid" - Remove broken group assignments
   • "Update Name" - Sync database with OBS name changes
   • Visual indicators show sync status and UUID linking

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
• Toast Notifications: Comprehensive feedback system with success/error messages for all operations
• Confirmation Dialogs: Safe deletion workflows with user confirmation prompts
• Real-time Validation: Client-side form validation with immediate feedback
• Dropdown Components: Portal-based dropdowns with proper z-index handling and scroll-aware positioning
• 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
• Accessibility: High contrast ratios, keyboard navigation, and screen reader support

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

Key Features & Recent Enhancements

Stream Management

• Twitch Integration: Simplified stream addition using just Twitch username (auto-generates full URL)
• Stream Deletion: Safe deletion workflow with confirmation that removes from both OBS and database
• Visual Feedback: Clear "View Stream" links with proper contrast for accessibility
• Team Association: Streams can be organized under teams for better management

Team & Group Management

• UUID-based Tracking: Robust OBS group synchronization using scene UUIDs
• Sync Verification: Real-time verification of database-OBS group synchronization
• Conflict Resolution: UI actions to resolve sync issues (missing groups, name changes)
• Visual Indicators: Clear status indicators for group linking and sync problems
  • 🆔 "Linked by UUID" - Group tracked by reliable UUID
  • 📝 "Name changed in OBS" - Group renamed in OBS, database needs update
  • ⚠️ "Not found in OBS" - Group in database but missing from OBS

User Experience Improvements

• Toast Notifications: Real-time feedback for all operations (success/error/info)
• Form Validation: Client-side validation with immediate error feedback
• Confirmation Prompts: Safe deletion workflows prevent accidental data loss
• Responsive Design: Mobile-friendly interface with glass morphism styling
• Loading States: Clear indicators during API operations
• Error Recovery: Graceful error handling with user-friendly messages

Developer Experience

• Type Safety: Comprehensive TypeScript definitions throughout
• API Documentation: Well-documented endpoints with clear parameter validation
• Migration Scripts: Database migration tools for schema updates
• Security: Input validation, sanitization, and secure API design
• Testing: Comprehensive error handling and edge case management