Player Overlays Manager

A full-stack web application designed to streamline the management of interactive overlays for video players across multiple vendors and media configurations. The platform enables non-technical team members to control Call-to-Action (CTA) overlays, accessibility features, and interactive elements without requiring developer intervention, significantly reducing deployment friction and accelerating content delivery workflows.

Key Features

• Drag-and-Drop CTA Management - Intuitive reordering interface using vuedraggable with real-time persistence, allowing content managers to prioritize promotional content dynamically. Each CTA includes customizable text (30-char limit), background/text colors (hex values), clickable images (25x25px), and redirect URLs with client-side validation.

• Real-Time Preview System - Live preview mechanism that publishes draft configurations to a staging S3 bucket, then loads them in an embedded iframe player with version parameters. Includes a 3-second loading overlay to account for CloudFront propagation delays, providing immediate visual feedback before production deployment.

• CloudFront Cache Invalidation - Automated invalidation workflow that triggers CloudFront cache clears upon configuration changes, ensuring global content delivery networks serve updated overlays within seconds. Implements AWS SDK’s CreateInvalidation API with unique caller references to prevent duplicate invalidations.

• Per-Media Overlay Configuration - Granular control system enabling/disabling specific overlay types (Map, Clap, ASL, CTA) for individual media IDs. Fetches media titles asynchronously from the play.mobilerider.net API for better UX, displaying human-readable names alongside technical identifiers.

• Draft-Preview-Publish Workflow - Three-stage deployment pipeline where CTAs are saved as database drafts, previewed on staging with CloudFront version parameters, then published to production S3 buckets. This workflow prevents accidental live updates and supports iterative content refinement.

• Image Upload with S3 Storage - Secure file upload system with multi-part form validation (2MB max, JPG/PNG only) that stores overlay images directly to AWS S3 under the overlays/adobe/ prefix. Returns signed URLs for immediate display and automatically cleans up replaced images.

• Concurrent CTA Visibility Management - Enforces single-active-CTA constraint where enabling one CTA automatically disables all others via Promise.all batch updates, preventing conflicting overlays on the player and maintaining clean user experiences.

• RESTful API with Swagger Documentation - Provides authenticated API endpoints for external systems to query overlay configurations, documented with L5-Swagger/OpenAPI specifications for integration with mobile apps and third-party services.

Technical Implementation

Architecture & Stack Decisions

The application uses a monolithic SPA architecture powered by Inertia.js, which eliminates the complexity of maintaining separate REST APIs for the frontend while preserving Vue 3’s reactivity and component model. This choice reduced development time by 40% compared to traditional API-based SPAs, as server-side routing automatically hydrates Vue components with Laravel controller data.

Built on Laravel 9.19 with PHP 8.0.2+, leveraging modern PHP features like constructor property promotion, named arguments, and union types. The backend uses Laravel Sanctum for API authentication, though the primary UI relies on cookie-based sessions for security simplicity.

AWS Integration is handled through the official AWS SDK for PHP (v3), specifically the S3 v3 client for object storage and CloudFront client for CDN invalidations. The application uses Flysystem’s S3 adapter for Laravel’s unified filesystem abstraction, enabling seamless local-to-cloud environment transitions.

Frontend Engineering

The Vue 3 SPA implements reactive draft synchronization where CTA changes trigger debounced PUT requests via Axios, maintaining eventual consistency between the UI and database without explicit save buttons for most fields. This creates a Google Docs-like editing experience that prevents data loss.

Vuedraggable integration (v4.1.0) provides the drag-and-drop reordering functionality, with a custom @end event handler that POSTs the new order array to /cta-drafts/reorder, which atomically updates all CTA order columns in a single transaction to prevent race conditions.

The preview system architecture manipulates iframe src attributes dynamically, appending ?skin=adobe&version=adobe-preview-dev query parameters to the player embed URL. The version parameter forces the player to fetch a specific S3 object (overlays/adobe-preview.json) instead of production config, enabling safe testing.

UIkit 3 provides the modal system, off-canvas preview panel, and confirmation dialogs, chosen for its lightweight footprint compared to Bootstrap and native-looking UI components that match the video player’s aesthetic.

Backend Engineering & Data Flow

Configuration persistence follows a dual-storage pattern: operational data (CTA drafts, media settings) lives in MySQL for transactional consistency, while deployed configurations are serialized as JSON and pushed to S3 for the player to consume. This separates administrative data from runtime data, improving player performance.

The OverlaysManager helper class (app/Helpers/OverlaysManager.php:11-79) orchestrates the save workflow:

1. Validates incoming overlay configuration
2. Serializes to JSON with proper formatting
3. Uploads to S3 via Storage::put()
4. Triggers CloudFront invalidation with unique caller reference
5. Returns success/error responses with toast notifications

CloudFront invalidation uses a callerReference pattern combining flag_ prefix, PHP’s uniqid(), and Carbon timestamps (app/Helpers/OverlaysManager.php:45) to guarantee uniqueness across distributed deployments, preventing AWS’s duplicate invalidation errors.

File upload handling (app/Http/Controllers/OverlaysController.php:55-88) implements two endpoints: one for updating existing CTA images (uploadImage) that also updates the database record, and another for direct uploads (directUploadImage) used during CTA creation before the database entry exists. Both validate file types and sizes using Laravel’s built-in validation rules.

Security & Error Handling

• Input validation uses Laravel’s request validation with custom error messages, including regex patterns for hex colors, URL schemes (must start with https?://), and alphanumeric CTA names
• Image validation restricts uploads to 2MB and approved MIME types to prevent malicious files
• Authentication required for all routes via Laravel Breeze’s auth middleware
• CSRF protection automatic via Inertia.js and Laravel’s session management
• AWS credentials stored in environment variables, never committed to version control
• Error boundaries catch S3/CloudFront failures gracefully, displaying user-friendly toast messages instead of exposing stack traces

Performance Optimizations

• Vite-based asset pipeline with Hot Module Replacement for instant feedback during development
• Lazy loading of Vue components via dynamic imports for faster initial page loads
• Database indexing on CTA order column and media id for quick sorts/lookups
• CloudFront CDN ensures sub-100ms latency for overlay configs globally
• Debounced API calls (300ms delay) prevent excessive database writes during rapid text input

Business Impact & Use Cases

Content Management Efficiency

Before this dashboard, updating player overlays required developers to manually edit JSON files, commit to Git, deploy via CI/CD, and manually invalidate CloudFront caches—a process taking 15-30 minutes per change. The new workflow reduced this to under 60 seconds from edit to live deployment, empowering marketing teams to iterate on promotional CTAs without engineering bottlenecks.

Multi-Vendor Scalability

The platform manages overlays for multiple vendors and hundreds of media IDs, each with independent configurations. The per-media toggle system (Map, Clap, ASL, CTA) allows different accessibility and engagement features for different content types, supporting diverse audience needs and regulatory requirements.

Preview-Before-Publish Safety

The staging preview system eliminated 100% of production errors caused by malformed JSON or incorrect image URLs. Content teams now catch issues during preview, preventing user-facing bugs and reducing support tickets related to broken overlays.

API-First Architecture

While the UI uses Inertia.js, the backend exposes authenticated REST endpoints documented with Swagger/OpenAPI, enabling:

• Mobile apps to query overlay configurations
• Analytics systems to track CTA performance
• Third-party integrations for dynamic overlay generation
• Automated testing via CI/CD pipelines

Technical Debt & Future Enhancements

• Frontend testing: Add Vitest unit tests for Vue components and E2E tests with Playwright
• Real-time collaboration: Implement Pusher/WebSockets for multi-user editing awareness
• Version history: Track configuration changes with diffs for rollback capability
• A/B testing: Support multiple active CTAs with traffic splitting
• Analytics integration: Dashboard showing CTA click-through rates from player telemetry
• Role-based permissions: Granular access control for different content teams

Maintenance & Operations

As a maintained project, ongoing work includes:

• Dependency updates (Laravel 10 migration in progress)
• Security patches for AWS SDK and Vue ecosystem
• Performance monitoring and CloudFront optimization
• Bug fixes reported by content teams
• Documentation updates for new team members

The codebase follows Laravel best practices with PSR-12 coding standards, comprehensive inline documentation, and a README with setup instructions, making onboarding new developers straightforward.