From 91ef418b1b27941d5b88f1e2858964872c158c0d Mon Sep 17 00:00:00 2001 From: Decobus Date: Sat, 19 Jul 2025 04:47:47 -0400 Subject: [PATCH] Update project documentation with comprehensive architecture details MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Enhanced CLAUDE.md with detailed architectural concepts and patterns - Added dynamic table naming system documentation - Documented persistent OBS connection management and dual integration - Explained glass morphism UI architecture and real-time monitoring - Updated README.md with modern professional presentation - Added comprehensive setup instructions and feature highlights - Included all development commands and API endpoint references - Cross-referenced CLAUDE.md for detailed technical documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 96 ++++++++++++++++++++++++++++++++++++------------------- README.md | 86 +++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 133 insertions(+), 49 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c841b0b..3484327 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,68 +15,98 @@ This is a Next.js web application that controls multiple OBS Source Switchers. I - `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 Tailwind CSS +- **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**: Tailwind CSS with @tailwindcss/forms plugin +- **Styling**: Custom CSS with Tailwind CSS utilities and modern glass card components ### Project Structure - `/app` - Next.js App Router pages and API routes - `/api` - Backend API endpoints for stream management - - `/add` - Page for adding new stream clients -- `/components` - Reusable React components (e.g., Dropdown) + - `/add` - 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 for communicating with OBS Studio - - `constants.ts` - Shared constants (table names, etc.) + - `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 Concepts +### Key Architectural Concepts -1. **Stream Management**: The app manages stream sources that can be assigned to different screen positions. Each stream has: - - name: Display name - - obs_source_name: Name of the source in OBS - - url: Stream URL - - team_id: Associated team identifier +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. **Screen Types**: Seven different screen positions are supported: large, left, right, topLeft, topRight, bottomLeft, bottomRight +2. **Persistent OBS Connection Management**: Single WebSocket connection shared across all API requests with automatic reconnection and connection state tracking -3. **Text File Integration**: The app writes the active source name to text files that OBS Source Switcher reads to switch sources automatically +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. **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) +4. **Glass Morphism UI Architecture**: Modern design system with backdrop blur effects, gradient backgrounds, and responsive glass card components + +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 Endpoints -- `POST /api/addStream` - Add new stream to database and OBS +#### 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/teams` - Get all teams +- `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 -- `POST /api/setActive` - Set active stream for a specific screen + +#### 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 -Two main tables: -- `streams`: id, name, obs_source_name, url, team_id -- `teams`: team_id, team_name +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 communicates with OBS through: -1. WebSocket connection using obs-websocket-js -2. Text files that OBS Source Switcher monitors for source changes -3. Direct source management through OBS WebSocket API +The app uses a sophisticated dual integration approach: -When setting an active source: -1. User selects stream in UI -2. API writes source name to corresponding text file (e.g., largeScreen.txt) -3. OBS Source Switcher detects file change and switches to that source \ No newline at end of file +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 + +**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 \ No newline at end of file diff --git a/README.md b/README.md index 7392ddd..916ddcd 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,82 @@ -This is a [Next.js](https://nextjs.org) app to control multiple OBS [Source Switchers](https://obsproject.com/forum/resources/source-switcher.941/) +# OBS Source Switcher Plugin UI + +A professional [Next.js](https://nextjs.org) web application for controlling multiple OBS [Source Switchers](https://obsproject.com/forum/resources/source-switcher.941/) with real-time WebSocket integration and modern glass morphism UI. + +## Features + +- **Multi-Screen Source Control**: Manage 7 different screen positions (large, left, right, and 4 corners) +- **Real-time OBS Integration**: WebSocket connection with live status monitoring +- **Team & Stream Management**: Organize streams by teams with full CRUD operations +- **Modern UI**: Glass morphism design with responsive layout +- **Professional Broadcasting**: Audio routing, scene management, and live status indicators +- **Dual Integration**: WebSocket API + text file monitoring for maximum compatibility + +## Quick Start + +```bash +npm install +npm run dev +``` + +Open [http://localhost:3000](http://localhost:3000) to access the control interface. ## Configuration -The application uses a configurable directory for storing files and the database. To update the directory: create `.env.local` in the root of the project. -`.env.local` should look like: -``` +### Environment Variables + +Create `.env.local` in the project root: + +```env +# File storage directory (optional, defaults to ./files) FILE_DIRECTORY=C:\\OBS\\source-switching -``` -If no `.env.local` file is created, it will default to `./files`, as seen in `config.js` - -```javascript - const config = { - FILE_DIRECTORY: path.resolve('./files'), - }; +# OBS WebSocket settings (optional, these are defaults) +OBS_WEBSOCKET_HOST=127.0.0.1 +OBS_WEBSOCKET_PORT=4455 +OBS_WEBSOCKET_PASSWORD=your_password_here ``` -In the "Source Switcher" properties in OBS, at the bottom, is a setting called `Current Source File`. Enable that, point it to the location of one of the text files, and put the read interval to 1000ms. Your source will change whenever the text file changes to a source _that is defined in the Source Switcher properties_ +### OBS Source Switcher Setup -The list of available sources is defined in a SQLite3 DB, location set in the `api/setActive.ts` route. +1. In OBS, configure Source Switcher properties +2. Enable "Current Source File" at the bottom +3. Point to one of the generated text files (e.g., `large.txt`, `left.txt`) +4. Set read interval to 1000ms +5. Sources will switch automatically when files change -`npm install` and -`npm run dev` to run it. +### Database Setup -This is my first [Next.js](https://nextjs.org) app and I am not a Javascript Developer professionally, use at your own risk. +```bash +# Create seasonal database tables +npm run create-sat-summer-2025-tables +``` + +## Development Commands + +```bash +npm run dev # Start development server +npm run build # Build for production +npm run start # Start production server +npm run lint # Run ESLint +npm run type-check # TypeScript validation +``` + +## Architecture + +- **Frontend**: Next.js 15 with React 19 and TypeScript +- **Backend**: Next.js API routes with SQLite database +- **OBS Integration**: WebSocket connection + text file monitoring +- **Styling**: Custom CSS with glass morphism and Tailwind utilities +- **CI/CD**: Forgejo workflows with self-hosted runners + +## API Endpoints + +- `GET /api/streams` - List all streams +- `POST /api/addStream` - Create new stream and OBS source +- `POST /api/setActive` - Set active stream for screen position +- `GET /api/obsStatus` - Real-time OBS connection status +- `GET /api/teams` - Team management + +See `CLAUDE.md` for detailed architecture documentation.