Update documentation to reflect recent enhancements

- Add studio mode support with preview/program controls and transition API
- Document API key authentication middleware for production security
- Add collapsible stream groups and consolidated CSS architecture
- Split API documentation into separate docs/API.md file for better organization
- Update feature descriptions and endpoint specifications
- Include new system scenes and enhanced footer functionality

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -23,10 +23,11 @@ This is a Next.js web application (branded as "Live Stream Manager") that contro
 
 ### Technology Stack
 - **Frontend**: Next.js 15.1.6 with React 19, TypeScript, and custom CSS with glass morphism design
-- **Backend**: Next.js API routes
+- **Backend**: Next.js API routes with authentication middleware
 - **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
+- **Styling**: Consolidated CSS architecture with Solarized Dark theme, CSS custom properties, Tailwind CSS utilities, and accessible glass morphism components
+- **Security**: API key authentication middleware for production deployments
 
 ### Project Structure
 - `/app` - Next.js App Router pages and API routes
@@ -34,7 +35,8 @@ This is a Next.js web application (branded as "Live Stream Manager") that contro
   - `/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)
+- `/components` - Reusable React components (Header, Footer, Dropdown, Toast, CollapsibleGroup)
+- `/middleware.ts` - API authentication middleware for security
 - `/lib` - Core utilities and database connection
   - `database.ts` - SQLite database initialization and connection management
   - `obsClient.js` - OBS WebSocket client with persistent connection management
@@ -76,6 +78,10 @@ This is a Next.js web application (branded as "Live Stream Manager") that contro
 
 10. **OBS Scene Control**: Direct scene switching controls with dynamic state tracking and real-time synchronization between UI and OBS
 
+11. **Studio Mode Support**: Full preview/program scene management with transition controls for professional broadcasting
+
+12. **Collapsible Stream Groups**: Organized stream display with expandable team groups for better UI management
+
 ### Environment Configuration
 - `FILE_DIRECTORY`: Directory for database and text files (default: ./files)
 - `OBS_WEBSOCKET_HOST`: OBS WebSocket host (default: 127.0.0.1)
@@ -117,9 +123,10 @@ This is a Next.js web application (branded as "Live Stream Manager") that contro
 #### OBS Scene Control
 - `POST /api/setScene` - Switch OBS to specified scene layout (1-Screen, 2-Screen, 4-Screen)
 - `GET /api/getCurrentScene` - Get currently active OBS scene for state synchronization
+- `POST /api/triggerTransition` - Trigger studio mode transition from preview to program (requires studio mode enabled)
 
 #### System Status
-- `GET /api/obsStatus` - Real-time OBS connection and streaming status
+- `GET /api/obsStatus` - Real-time OBS connection, streaming, recording, and studio mode status
 
 ### Database Schema
 
@@ -188,6 +195,9 @@ See [OBS Setup Guide](./docs/OBS_SETUP.md) for detailed configuration instructio
 ### Security Architecture
 
 **Authentication**: API key-based authentication protects all API endpoints through Next.js middleware
+- Middleware intercepts all API requests when `API_KEY` is set
+- Bypasses authentication for localhost in development
+- Returns 401 for unauthorized requests
 
 **Input Validation**: Comprehensive validation using centralized security utilities in `/lib/security.ts`:
 - Screen parameter allowlisting prevents path traversal attacks
@@ -212,6 +222,8 @@ See [OBS Setup Guide](./docs/OBS_SETUP.md) for detailed configuration instructio
 - **Visual Feedback**: Clear "View Stream" links with proper contrast for accessibility
 - **Team Association**: Streams organized under teams with proper naming conventions
 - **Active Source Detection**: Properly reads current active sources from text files on page load and navigation
+- **Collapsible Organization**: Streams grouped by team in expandable sections for cleaner UI
+- **Enhanced Stream Display**: Shows stream status with preview/program indicators in studio mode
 
 ### Team & Group Management
 - **UUID-based Tracking**: Robust OBS group synchronization using scene UUIDs
@@ -247,12 +259,15 @@ See [OBS Setup Guide](./docs/OBS_SETUP.md) for detailed configuration instructio
 - **Error Recovery**: Graceful error handling with user-friendly messages
 - **Enhanced Footer**: Real-time team/stream counts, OBS connection status with visual indicators
 - **Optimistic Updates**: Immediate UI feedback with proper stream group name matching
+- **Studio Mode Status**: Footer displays studio mode state with preview/program scene information
+- **Transition Controls**: "Cut to Preview" button available when studio mode is active
 
 ### OBS Integration Improvements
 - **Text Size**: Team name overlays use 96pt font for better visibility
 - **Color Display**: Fixed background color display (#002b4b) using proper ABGR format
 - **Standardized APIs**: All endpoints use consistent `{ success: true, data: [...] }` response format
 - **Performance Optimization**: Reduced code duplication and improved API response handling
+- **CSS Consolidation**: Eliminated repetitive styles, centralized theming in globals.css
 
 ### Developer Experience
 - **Type Safety**: Comprehensive TypeScript definitions throughout

README.md

@@ -7,19 +7,22 @@ A professional [Next.js](https://nextjs.org) web application for managing live s
 
 ## Features
 
+- **Studio Mode Support**: Full preview/program scene management with transition controls for professional broadcasting
 - **OBS Scene Control**: Switch between OBS layouts (1-Screen, 2-Screen, 4-Screen) with dynamic button states
 - **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
 - **Enhanced Stream Management**: Create, edit, and delete streams with comprehensive OBS cleanup
 - **Team Organization**: Organize streams by teams with full CRUD operations and scene synchronization
+- **Collapsible Stream Groups**: Organized stream display with expandable team groups for better UI management
 - **Comprehensive Deletion**: Remove streams/teams with complete OBS component cleanup (scenes, sources, text files)
 - **Audio Control**: Browser sources created with muted audio and OBS control enabled
 - **Modern UI**: Glass morphism design with responsive layout and accessibility features
 - **Professional Broadcasting**: Audio routing, scene management, and live status indicators
 - **Dual Integration**: WebSocket API + text file monitoring for maximum compatibility
 - **UUID-based Tracking**: Robust OBS group synchronization with rename-safe tracking
-- **Enhanced Footer**: Real-time team/stream counts and OBS connection status
+- **Enhanced Footer**: Real-time team/stream counts, OBS connection status, and studio mode indicators
-- **Optimized Performance**: Reduced code duplication and standardized API responses
+- **API Security**: Optional API key authentication for production deployments
+- **Optimized Performance**: Consolidated CSS architecture and standardized API responses
 
 ## Quick Start
 
@@ -109,54 +112,22 @@ npm run type-check   # TypeScript validation
 - **Styling**: Custom CSS with glass morphism and Tailwind utilities
 - **CI/CD**: Forgejo workflows with self-hosted runners
 
-## API Endpoints
+## API Documentation
 
-### Stream Management
+The application provides a comprehensive REST API for managing streams, teams, and OBS integration. 
-- `GET /api/streams` - List all streams with team information
-- `GET /api/streams/[id]` - Get individual stream details
-- `POST /api/addStream` - Create new stream with browser source and team association
-- `PUT /api/streams/[id]` - Update stream information
-- `DELETE /api/streams/[id]` - Delete stream with comprehensive OBS cleanup:
-  - Removes stream's nested scene
-  - Deletes browser source
-  - Removes from all source switchers
-  - Clears text files referencing the stream
 
-### Source Control
+**📚 [Complete API Documentation](docs/API.md)**
-- `POST /api/setActive` - Set active stream for screen position (writes team-prefixed name to text file)
-- `GET /api/getActive` - Get currently active sources for all screen positions
 
-### Team Management
+Key endpoints include:
-- `GET /api/teams` - Get all teams with group information and sync status
+- Stream management (CRUD operations)
-- `POST /api/teams` - Create new team with optional OBS scene creation
+- Source control for 7 screen positions  
-- `PUT /api/teams/[teamId]` - Update team name, group_name, or group_uuid
+- Team and OBS group management
-- `DELETE /api/teams/[teamId]` - Delete team with comprehensive OBS cleanup:
+- Scene switching and studio mode controls
-  - Deletes team scene/group
+- Real-time status monitoring
-  - Removes team text source
-  - Deletes all associated stream scenes
-  - Removes all browser sources with team prefix
-  - Clears all related text files
-- `GET /api/getTeamName` - Get team name by ID
 
-### OBS Group/Scene Management
+All endpoints support API key authentication for production deployments.
-- `POST /api/createGroup` - Create OBS scene 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
-  - Detects orphaned groups (excludes system scenes)
-  - Identifies name mismatches
-  - Shows sync status for all teams
 
-### OBS Scene Control
+See [`CLAUDE.md`](CLAUDE.md) for detailed architecture documentation and [`docs/API.md`](docs/API.md) for complete endpoint specifications.
-- `POST /api/setScene` - Switch OBS to specified scene (1-Screen, 2-Screen, 4-Screen)
-- `GET /api/getCurrentScene` - Get currently active OBS scene
-
-### System Status
-- `GET /api/obsStatus` - Real-time OBS connection, streaming, and recording status
-
-### Authentication
-All endpoints require API key authentication when `API_KEY` environment variable is set.
-
-See `CLAUDE.md` for detailed architecture documentation and implementation details.
 
 ## Known Issues
 
@@ -167,7 +138,7 @@ See `CLAUDE.md` for detailed architecture documentation and implementation detai
 
 ### System Scene Exclusion
 Infrastructure scenes containing source switchers are excluded from orphaned group detection:
-- 1-Screen, 2-Screen, 4-Screen, Starting, Ending, Audio, Movies
+- 1-Screen, 2-Screen, 4-Screen, Starting, Ending, Audio, Movies, Resources
 - Additional scenes can be added to the `SYSTEM_SCENES` array in `/app/api/verifyGroups/route.ts`
 
 

docs/API.md

@@ -0,0 +1,288 @@
+# API Documentation
+
+This document provides detailed information about all API endpoints available in the Live Stream Manager application.
+
+## Base URL
+All API endpoints are available at `/api/*` relative to your application's base URL.
+
+## Authentication
+All endpoints require API key authentication when the `API_KEY` environment variable is set. Include the API key in the `Authorization` header:
+
+```
+Authorization: Bearer your_api_key_here
+```
+
+Authentication is bypassed for localhost requests in development mode.
+
+## Response Format
+All endpoints return JSON responses in the following format:
+
+```json
+{
+  "success": true,
+  "data": { /* response data */ },
+  "message": "Optional success message"
+}
+```
+
+Error responses:
+```json
+{
+  "success": false,
+  "error": "Error description",
+  "message": "User-friendly error message"
+}
+```
+
+## Stream Management
+
+### GET /api/streams
+List all streams with team information.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": 1,
+      "name": "StreamerName",
+      "obs_source_name": "TeamName_StreamerName",
+      "url": "https://twitch.tv/streamername",
+      "team_id": 1,
+      "team_name": "Team Alpha"
+    }
+  ]
+}
+```
+
+### GET /api/streams/[id]
+Get individual stream details by ID.
+
+### POST /api/addStream
+Create new stream with browser source and team association.
+
+**Request Body:**
+```json
+{
+  "name": "StreamerName",
+  "url": "https://twitch.tv/streamername", // or just "streamername"
+  "team_id": 1
+}
+```
+
+### PUT /api/streams/[id]
+Update stream information.
+
+### DELETE /api/streams/[id]
+Delete stream with comprehensive OBS cleanup:
+- Removes stream's nested scene
+- Deletes browser source
+- Removes from all source switchers
+- Clears text files referencing the stream
+
+## Source Control
+
+### POST /api/setActive
+Set active stream for screen position (writes team-prefixed name to text file).
+
+**Request Body:**
+```json
+{
+  "screen": "large", // large, left, right, top_left, top_right, bottom_left, bottom_right
+  "source": "TeamName_StreamerName"
+}
+```
+
+### GET /api/getActive
+Get currently active sources for all screen positions.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "large": "TeamName_StreamerName",
+    "left": "TeamName_StreamerName2",
+    "right": "",
+    // ... other positions
+  }
+}
+```
+
+## Team Management
+
+### GET /api/teams
+Get all teams with group information and sync status.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "team_id": 1,
+      "team_name": "Team Alpha",
+      "group_name": "Team Alpha",
+      "group_uuid": "abc123-def456-ghi789"
+    }
+  ]
+}
+```
+
+### POST /api/teams
+Create new team with optional OBS scene creation.
+
+**Request Body:**
+```json
+{
+  "team_name": "New Team",
+  "create_group": true // optional
+}
+```
+
+### PUT /api/teams/[teamId]
+Update team name, group_name, or group_uuid.
+
+### DELETE /api/teams/[teamId]
+Delete team with comprehensive OBS cleanup:
+- Deletes team scene/group
+- Removes team text source
+- Deletes all associated stream scenes
+- Removes all browser sources with team prefix
+- Clears all related text files
+
+### GET /api/getTeamName
+Get team name by ID.
+
+**Query Parameters:**
+- `teamId`: Team ID to lookup
+
+## OBS Group/Scene Management
+
+### POST /api/createGroup
+Create OBS scene from team and store UUID.
+
+**Request Body:**
+```json
+{
+  "team_id": 1
+}
+```
+
+### POST /api/syncGroups
+Synchronize all teams with OBS groups. Updates database with current OBS scene information.
+
+### GET /api/verifyGroups
+Verify database groups exist in OBS with UUID tracking.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "teams": [
+      {
+        "team_id": 1,
+        "team_name": "Team Alpha",
+        "group_name": "Team Alpha",
+        "group_uuid": "abc123",
+        "status": "linked", // linked, name_changed, not_found
+        "obs_name": "Team Alpha Modified" // if name changed in OBS
+      }
+    ],
+    "orphanedGroups": [
+      {
+        "sceneName": "Orphaned Scene",
+        "sceneUuid": "orphan123"
+      }
+    ]
+  }
+}
+```
+
+Features:
+- Detects orphaned groups (excludes system scenes)
+- Identifies name mismatches
+- Shows sync status for all teams
+
+## OBS Scene Control
+
+### POST /api/setScene
+Switch OBS to specified scene (1-Screen, 2-Screen, 4-Screen).
+
+**Request Body:**
+```json
+{
+  "scene": "2-Screen" // 1-Screen, 2-Screen, or 4-Screen
+}
+```
+
+### GET /api/getCurrentScene
+Get currently active OBS scene.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "currentScene": "2-Screen"
+  }
+}
+```
+
+### POST /api/triggerTransition
+Trigger studio mode transition from preview to program (requires studio mode enabled).
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "programScene": "2-Screen",
+    "previewScene": "1-Screen"
+  },
+  "message": "Successfully transitioned preview to program"
+}
+```
+
+**Error Conditions:**
+- Studio mode not enabled (400 error)
+- OBS connection issues (500 error)
+
+## System Status
+
+### GET /api/obsStatus
+Real-time OBS connection, streaming, recording, and studio mode status.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "connected": true,
+    "streaming": false,
+    "recording": true,
+    "studioMode": {
+      "enabled": true,
+      "previewScene": "1-Screen",
+      "programScene": "2-Screen"
+    }
+  }
+}
+```
+
+## Error Codes
+
+- **400**: Bad Request - Invalid parameters or studio mode not enabled
+- **401**: Unauthorized - Missing or invalid API key
+- **404**: Not Found - Resource doesn't exist
+- **500**: Internal Server Error - OBS connection issues or server errors
+
+## Rate Limiting
+
+Currently no rate limiting is implemented, but consider implementing it for production deployments to prevent abuse.
+
+## WebSocket Integration
+
+The application maintains a persistent WebSocket connection to OBS Studio for real-time communication. All API endpoints use this shared connection for optimal performance.