Eurus Studio - Creative AI Workflow Platform

A cutting-edge Next.js application featuring Eurus Studio landing page design, built for creative AI workflows, collaborative content creation, and professional video editing with advanced Remotion integration and worker thread optimization.

✨ Features

🎯 Core Functionality

• Interactive 3D Canvas: Drag-and-drop nodes with real-time 3D model rendering

• AI-Powered Workflows: Integrated text, image, and video AI models

• Real-time Collaboration: Multi-user editing with cursor presence

• Unified Asset Management: Single source of truth with Azure-exclusive storage

• Credit System: Usage tracking and billing integration

• Visual node-based workflow editor with React Flow

• AI-powered content generation: Images, videos, and text

• Advanced image analysis with Azure OpenAI 4o mini integration

• Context-aware generation - Intelligent content creation based on connected nodes

• Optimistic UI updates - Instant deletion and real-time collaboration

• Azure Blob Storage integration for scalable asset management

• Auto-detection - Dynamic port and base URL recognition

• Discovery and sharing platform

🎬 Enhanced Video Editor

• Remotion Integration: Professional video rendering with React components

• Worker Thread Architecture: Non-blocking video processing with dedicated workers

• Performance Monitoring: Real-time FPS, memory, and render time tracking

• Adaptive Quality System: Dynamic quality adjustment based on system performance

• Multi-format Support: Video, audio, image, and text track editing

• Background Processing: Frame extraction, thumbnail generation, waveform analysis

• Intelligent Caching: Frame caching with automatic memory management

• Timeline Optimization: Advanced timeline calculations and track arrangements

🎪 Eurus Studio Design

• Immersive Hero Section: "Irreplacably Creative" with interactive draggable nodes

• 3D Model Integration: Real-time GLB model rendering with Three.js

• Scroll-triggered Animations: Smooth transitions and dynamic content

• Professional Tools Showcase: Video backgrounds and interactive elements

• Ideas Scroll Section: Animated node interactions and creative prompts

🛠️ Technical Features

• Next.js 15: Latest React framework with App Router

• TypeScript: Full type safety and developer experience

• Tailwind CSS: Utility-first styling with custom animations

• Three.js Integration: 3D graphics and WebGL rendering

• Firebase Integration: Authentication and real-time database

• Azure Blob Storage: Cloud asset management

• Responsive Design: Mobile-first approach with smooth interactions

• Worker Thread Management: Dedicated workers for video, audio, image, and timeline processing

• Remotion Rendering: React-based video composition and rendering

Recent Updates (October 2025)

🗂️ Unified Asset Management System (ENHANCED)

Complete asset management overhaul providing seamless integration across all application modes:

• Azure-Exclusive Storage: Complete elimination of IndexedDB and local storage fallbacks

• Single Source of Truth: All asset operations consolidated into /src/lib/unifiedAssetManager.ts

• Cross-Mode Integration: Seamless asset sharing between Project, Canvas, and Edit modes

• Intelligent Storage Strategy: Context-aware storage with dual persistence for canvas assets

• Comprehensive Hook System: Full React integration with useUnifiedAssets.ts

• Type-Safe Architecture: Complete TypeScript integration with proper interfaces

• Performance Optimized: Efficient queries, caching, and background processing

🏗️ Unified Asset Management Architecture

The Eurus platform features a completely unified asset management system that provides seamless asset operations across Project, Canvas, and Edit modes with intelligent context-aware storage.

🎯 Cross-Mode Asset Flow

┌─ PROJECT MODE ────────────────────┐    ┌─ CANVAS MODE ─────────────────────┐    ┌─ EDIT MODE ───────────────────────┐
│                                   │    │                                   │    │                                   │
│ 📁 Asset Library Management      │    │ 🎨 Node-Specific Uploads         │    │ 🎬 Timeline Asset Integration    │
│ ┌─────────────────────────────┐   │    │ ┌─────────────────────────────┐   │    │ ┌─────────────────────────────┐   │
│ │ • Upload to Project Gallery │   │    │ │ • Upload to Canvas Node     │   │    │ │ • Access Project Assets     │   │
│ │ • Organize & Tag Assets     │   │    │ │ • Store in Node + Collection│   │    │ │ • Import from Canvas Nodes  │   │
│ │ • Share Across Team        │   │    │ │ • Real-time Canvas Updates  │   │    │ │ • Timeline Integration      │   │
│ │ • Global Asset Search      │   │    │ │ • Context-Aware Display     │   │    │ │ • Export Ready Assets       │   │
│ └─────────────────────────────┘   │    │ └─────────────────────────────┘   │    │ └─────────────────────────────┘   │
│           │                       │    │           │                       │    │           │                       │
│           ▼                       │    │           ▼                       │    │           ▼                       │
│    Azure + Firestore             │    │    Azure + Firestore + Node      │    │    Azure + Firestore             │
└───────────────────────────────────┘    └───────────────────────────────────┘    └───────────────────────────────────┘
                                    ▲                                      ▲                                      ▲
                                    │                                      │                                      │
                                    └─────────── UNIFIED SYSTEM ──────────┴──────────────────────────────────────┘
                                              /src/lib/unifiedAssetManager.ts

📂 Storage Architecture

Azure Blob Storage Structure:
projects/{projectId}/
├── assets/                    # Project & Edit mode assets
│   ├── {timestamp}_{hash}_image.jpg
│   ├── {timestamp}_{hash}_video.mp4
│   └── {timestamp}_{hash}_audio.wav
└── nodes/{nodeId}/           # Canvas mode node-specific assets
    ├── {timestamp}_{hash}_upload.jpg
    └── {timestamp}_{hash}_media.mp4

Firestore Collection: 'project-assets'
├── Document: {assetId}
│   ├── projectId: string     # Index for efficient queries
│   ├── nodeId?: string       # Set for canvas uploads
│   ├── azureUrl: string      # Primary CDN URL
│   ├── fileName: string      # Original filename
│   ├── contentType: string   # MIME type for filtering
│   ├── isNodeAsset: boolean  # Canvas vs Project distinction
│   └── metadata: object      # Size, tags, upload info

🔧 Core Components

1. UnifiedAssetManager (/src/lib/unifiedAssetManager.ts)

Central orchestrator managing all asset operations across modes:

• Azure Integration: Direct blob storage with CDN delivery

• Firestore Metadata: Efficient queries and real-time updates

• Context-Aware Storage: Intelligent routing based on upload context

• Type-Safe Operations: Full TypeScript integration throughout

2. React Hooks Ecosystem (/src/hooks/useUnifiedAssets.ts)

Complete React integration for all asset operations:

• useAssetUpload: Universal file upload with progress tracking across all modes

• useProjectAssets: Project-level asset management with filtering and search

• useMediaLibrary: Complete media browser with cross-mode asset aggregation

• useNodeAssets: Canvas-specific operations with node context integration

3. Mode-Specific Integration

Project Mode (/src/modules/project/):

• Asset gallery with bulk operations

• Team sharing and collaboration features

• Advanced filtering and categorization

• Export and download capabilities

Canvas Mode (/src/modules/canvas/):

• Node-specific upload via useNodeUpload

• Real-time canvas asset updates

• Drag-and-drop integration

• Context-aware asset suggestions

Edit Mode (/src/modules/studio-editor/):

• Timeline asset integration

• Video/audio track management

• Asset compatibility validation

• Render-ready optimization

4. API Architecture (/src/app/api/assets/)

Unified REST endpoints supporting all modes:

• POST /api/assets - Universal upload with context detection

• GET /api/assets/list - Cross-mode asset fetching with filters

• DELETE /api/assets/delete - Safe deletion with metadata cleanup

• POST /api/upload-media - Canvas legacy compatibility endpoint

🎯 Key Features

Cross-Mode Asset Integration

• Unified Access: All modes can access and utilize the same asset pool

• Context Intelligence: Assets uploaded in Canvas mode are available in Project and Edit modes

• Smart Organization: Automatic categorization based on upload context and content type

• Real-Time Sync: Instant asset availability across all open modes and collaborators

Intelligent Storage Strategy

• Azure Primary: All files stored in Azure Blob Storage with global CDN

• Firestore Metadata: Rich metadata for search, filtering, and organization

• Dual Persistence: Canvas uploads stored in both collection and node data for performance

• Automatic Cleanup: Orphaned assets and metadata automatically cleaned up

Performance & Scalability

• Lazy Loading: Assets loaded on-demand with intelligent prefetching

• Caching Strategy: Multi-level caching for instant repeated access

• Progress Tracking: Real-time upload progress with pause/resume capabilities

• Batch Operations: Efficient bulk upload and management operations

Type-Safe Architecture

interface AssetMetadata {
  id: string;
  projectId: string;
  fileName: string;
  originalName: string;
  size: number;
  contentType: string;
  azureUrl: string; // Primary CDN URL
  blobName: string; // Azure blob identifier
  uploadedAt: string;
  uploadedBy: string;
  nodeId?: string; // Canvas context
  tags?: string[];
  isNodeAsset?: boolean; // Mode differentiation
}

🚀 Usage Examples Across Modes

Project Mode: Asset Gallery Management

import { useAssetUpload, useProjectAssets } from "@/hooks/useUnifiedAssets";

function ProjectAssetGallery() {
  const { uploadFile, uploading, progress } = useAssetUpload();
  const { assets, loading, refetch } = useProjectAssets({
    contentType: "image",
    limit: 50,
  });

  const handleGalleryUpload = async (files: File[]) => {
    for (const file of files) {
      await uploadFile(file, {
        tags: ["gallery", "project-asset"],
        generateThumbnail: true,
      });
    }
    refetch(); // Refresh gallery
  };
}

Canvas Mode: Node-Specific Upload

import { useNodeUpload } from "@/modules/canvas/hooks";

function CanvasNode({ nodeId }) {
  const { uploadToNode, uploading } = useNodeUpload(nodeId, dispatch);

  const handleCanvasUpload = async (file: File) => {
    // Uploads to Azure + Firestore + updates node.mediaUrl
    const result = await uploadToNode([file], {
      generateThumbnail: true,
      nodeContext: true,
    });
  };
}

Edit Mode: Timeline Asset Integration

import { useMediaLibrary } from "@/hooks/useUnifiedAssets";

function TimelineAssetPanel() {
  const { allMedia, firestoreAssets, nodeAssets } =
    useMediaLibrary(canvasNodes);

  // Access assets from all modes
  const projectImages = firestoreAssets.filter(
    (a) => a.contentType.startsWith("image/") && !a.isNodeAsset
  );
  const canvasMedia = nodeAssets; // From canvas nodes
  const combinedMedia = allMedia; // Everything together
}

Cross-Mode Asset Sharing

// Asset uploaded in Canvas becomes available everywhere
import { useProjectAssets } from "@/hooks/useUnifiedAssets";

function CrossModeAssetAccess() {
  // Get all assets including canvas uploads
  const { assets } = useProjectAssets({ includeNodeAssets: true });

  // Filter by source
  const projectAssets = assets.filter((a) => !a.isNodeAsset);
  const canvasAssets = assets.filter((a) => a.isNodeAsset);
}

🔄 Migration Benefits & Cross-Mode Advantages

Before: Fragmented systems with separate upload logic per mode, IndexedDB inconsistencies After: Unified system with seamless cross-mode integration and intelligent context awareness

Performance Gains

• Faster Cross-Mode Access: Assets uploaded in any mode instantly available elsewhere

• Intelligent Caching: Smart prefetching based on usage patterns across modes

• Reduced Network Overhead: Single CDN with optimized delivery paths

• Background Processing: Non-blocking uploads with progress across all contexts

User Experience Improvements

• Seamless Workflow: Upload in Canvas, access in Project, use in Edit timeline

• Consistent Interface: Same upload experience regardless of current mode

• Smart Suggestions: Context-aware asset recommendations based on current work

• Real-Time Collaboration: Asset changes propagate instantly to all team members

Developer Benefits

• Single API Surface: One set of hooks and functions for all asset operations

• Type Safety: Comprehensive TypeScript interfaces across all modes

• Maintainability: Zero code duplication, single source of truth

• Testing: Unified test suite covering all asset operation scenarios

🎬 Enhanced Video Editor Integration

• Remotion & Worker Threads: Fully integrated professional video editing capabilities

• Performance Architecture: Worker pools for video, audio, image, timeline, and Remotion processing

• EditorOrchestrator: Central service coordinator managing all video editor services

• Adaptive Rendering: Dynamic quality adjustment based on system performance

• Background Processing: Non-blocking video operations with progress tracking

• Enhanced Video Player: Dual rendering modes (Canvas/Remotion) with fallback support

🎯 Context-Based Image Analysis

• Smart node behavior: Nodes with existing media create NEW analysis nodes when describing images

• Base state optimization: Empty nodes with image context update directly with descriptions

• Azure OpenAI 4o mini: Fixed parameter compatibility (max_completion_tokens, temperature: 1, top_p: 1)

• Intelligent routing: Text generation automatically detects image-to-text requests

🗑️ Optimistic Deletion System

• Instant UI updates: Nodes and edges delete immediately without waiting for server confirmation

• Smart edge cleanup: Connected edges automatically removed when nodes are deleted

• Multiple delete keys: Support for both Delete and Backspace keys

• Collaborative broadcasting: Real-time deletion sync across all users

🌐 Auto-Detection & Reliability

• Dynamic port detection: Automatically detects server port (3000, 3001, 3002, etc.)

• Request-based URL resolution: Uses request headers to determine correct base URL

• Development flexibility: No more manual port updates when Next.js switches ports

• Robust error handling: Graceful fallbacks for all network operations

🔧 Technical Improvements

• Enhanced logging: Comprehensive debug information for troubleshooting

• Performance optimization: Reduced API call latency and improved response times

• Context data processing: Better handling of image URLs and metadata

• Edge case handling: Improved stability for various content types

• Modular architecture: Clean separation of concerns with service-oriented design

🚀 Tech Stack

Frontend

• Framework: Next.js 15 with App Router

• Language: TypeScript

• Styling: Tailwind CSS

• 3D Graphics: Three.js, @react-three/fiber, @react-three/drei

• Icons: React Icons, Lucide React

• Animations: Framer Motion, CSS Animations

• Video Editing: Remotion, Enhanced Video Player

• Worker Threads: Web Workers for background processing

Backend & Services

• Authentication: Firebase Auth

• Database: Firestore (project-assets collection)

• Storage: Azure Blob Storage (exclusive, no fallbacks)

• Asset Management: Unified system with zero redundancy

• API Routes: Next.js API Routes with unified endpoints

• AI Models: OpenAI, Gemini, Flux, Stable Diffusion

• Video Processing: FFmpeg.wasm, Remotion rendering

• Performance Monitoring: Custom performance tracking system

Video Editor Architecture

• Worker Pools: Video, Audio, Image, Timeline, Remotion processing

• Service Layer: EditorOrchestrator, RemotionService, PerformanceMonitor

• Rendering Engine: Dual-mode Canvas/Remotion rendering

• Caching System: Intelligent frame caching with memory management

• Health Monitoring: Automatic service restart and failure recovery

Development

• Package Manager: pnpm

• Linting: ESLint

• Code Formatting: Prettier

• Version Control: Git

🚀 Getting Started

Quick Setup

# Clone repository
git clone https://github.com/EurusLabs/eurus-studio.git
cd eurus-studio

# Install dependencies
pnpm install

# Set up environment variables
cp azure.env.template .env.local
# Fill in your Azure credentials and API keys

# Add your API keys and configuration
# - Firebase configuration (Auth + Firestore)
# - Azure Blob Storage credentials (REQUIRED for asset management)
# - AI model API keys

# Required for Unified Asset Management:
AZURE_STORAGE_CONNECTION_STRING=your_connection_string
AZURE_STORAGE_CONTAINER_NAME=user-assets
AZURE_STORAGE_BASE_URL=https://yourstorage.blob.core.windows.net

# Start development server
pnpm dev
# Server will auto-detect available port (3000, 3001, 3002, etc.)

📋 Setup Documentation

Core Setup

See SETUP_GUIDE.md for detailed configuration of:

• Azure AI Foundry (GPT-4o + SORA)

• Multi-image composition pipeline

• Troubleshooting and team collaboration

Remotion Lambda Setup

See src/remotion/README.md for complete serverless video rendering setup:

• AWS IAM policy and role configuration

• Lambda function deployment (with optimized settings)

• Environment variables setup

• Testing and troubleshooting

• Cost optimization and monitoring

🎯 New: Multi-Image Composition

Upload multiple images and ask the system to "combine" or "merge" them:

1. GPT-4o analyzes all images simultaneously

2. SORA creates video compositions (Azure AI Foundry)

3. Enhanced FLUX fallback with intelligent prompts

🎤 Enhanced Audio Recording

Ultra-smooth voice-to-text functionality with Azure Whisper:

• Instant visual feedback with pulsing recording animations

• Optimized audio settings for clear speech recognition

• Smart error handling with user-friendly messages

• Real-time transcription with immediate prompt population

🎬 Enhanced Video Editor

🏗️ Architecture Overview

The enhanced video editor is built with a modular architecture that separates concerns and enables efficient background processing:

┌─────────────────────────────────────────────────────────────┐
│                     Editor Orchestrator                      │
│                  (Service Coordinator)                       │
├─────────────────────────────────────────────────────────────┤
│  Worker Manager  │  Remotion Service  │ Performance Monitor │
├──────────────────┼────────────────────┼─────────────────────┤
│   Video Worker   │    Audio Worker    │   Image Worker      │
│ Timeline Worker  │  Remotion Worker   │                     │
└─────────────────────────────────────────────────────────────┘

🎯 Video Editor Features

Worker Thread Management

• WorkerPool: Manages multiple worker instances with automatic scaling

• WorkerManager: Central coordinator for all worker pools

• Task Prioritization: Intelligent task queuing and priority management

• Health Monitoring: Automatic worker restart and failure recovery

Remotion Integration

• Background Rendering: Non-blocking video frame generation

• Caching System: Intelligent frame caching for smooth playback

• Adaptive Quality: Dynamic quality adjustment based on performance

• Preview Optimization: Fast preview rendering with lower quality

Performance Monitoring

• Real-time Metrics: CPU, memory, and rendering performance tracking

• Health Reports: Comprehensive system health analysis

• Automatic Optimization: Performance-based feature adjustments

• Developer Tools: Development-time performance overlays

🛠️ Worker Types

Video Processing Worker

• Frame Extraction: Extract frames from video files

• Thumbnail Generation: Generate video thumbnails

• Video Analysis: Analyze video properties and metadata

• Compression: Video compression with quality settings

Audio Processing Worker

• Waveform Extraction: Generate audio waveform data

• Peak Analysis: Extract audio peak information

• Audio Normalization: Normalize audio levels

• Format Conversion: Convert between audio formats

Remotion Rendering Worker

• Frame Rendering: Render individual Remotion frames

• Sequence Rendering: Render frame sequences

• Video Export: Export complete videos

• Preview Generation: Fast preview rendering

Image Processing Worker

• Image Resizing: Resize images with quality options

• Filter Application: Apply various image filters

• Color Extraction: Extract dominant colors

• Optimization: Optimize images for web

Timeline Calculator Worker

• Layout Calculation: Calculate timeline layouts

• Track Optimization: Optimize track arrangements

• Keyframe Generation: Generate animation keyframes

• Validation: Validate timeline integrity

🎮 Enhanced Video Player

The EnhancedVideoPlayer provides advanced features:

Features

• Dual Rendering Modes: Canvas and Remotion rendering

• Performance Monitoring: Real-time FPS and render time display

• Adaptive Streaming: Quality adjustment based on performance

• Background Preloading: Smooth playbook with predictive loading

Usage

Usage**

import { Editor, editorOrchestrator } from "@/components/editor";

function VideoEditorApp() {
  useEffect(() => {
    // Initialize all services
    editorOrchestrator.initialize();

    return () => {
      // Cleanup on unmount
      editorOrchestrator.shutdown();
    };
  }, []);

  return (
    <Editor
      onStateChange={(state) => console.log("Editor state:", state)}
      className="h-screen"
    />
  );
}

🗂️ Unified Asset Management

The application features a completely unified asset management system that eliminates all redundancy and provides a single source of truth for all media operations.

🏗️ Architecture Overview

┌─ Project Tab ─────────────────────┐    ┌─ Canvas Tab ──────────────────────┐    ┌─ Edit Tab ────────────────────────┐
│ Add Asset → Azure → Firestore     │    │ Upload → Azure → Firestore + Node │    │ Same as Project Tab               │
│ Media Library ← Firestore Only    │    │ View ← Firestore + Node Extract   │    │ Azure → Firestore → Display      │
└───────────────────────────────────┘    └───────────────────────────────────┘    └───────────────────────────────────┘
                                    ▲                                      ▲                                      ▲
                                    │                                      │                                      │
                                    └─────────── UNIFIED SYSTEM ──────────┴──────────────────────────────────────┘
                                              /src/lib/unifiedAssetManager.ts

🎯 Cross-Mode Asset Flow

Project Mode: Asset Library Management

1. Upload Flow: Gallery Upload → Azure Blob → Firestore Collection → Real-time Sync

2. Organization: Tag-based categorization, bulk operations, team sharing

3. Cross-Mode Availability: Instantly accessible in Canvas and Edit modes

4. Use Cases: Brand assets, stock images, project resources, team libraries

Canvas Mode: Node-Specific Asset Integration

1. Context Upload: Node Upload → Azure Blob → Firestore Collection + Node Data

2. Dual Persistence: Asset stored in collection for cross-mode access + node for performance

3. Real-Time Canvas: Immediate node visual update with asset preview

4. Use Cases: AI-generated content, workflow outputs, iterative creations

Edit Mode: Timeline Asset Integration

1. Asset Access: Aggregated view of Project assets + Canvas node outputs

2. Smart Filtering: Content-type filtering for timeline compatibility

3. Performance Optimization: Lazy loading with intelligent prefetching

4. Use Cases: Video editing, audio tracks, image sequences, final compositions

Universal Cross-Mode Benefits

• Asset Discoverability: Upload anywhere, find everywhere

• Context Preservation: Metadata tracks origin mode and usage context

• Collaborative Workflow: Team members see assets regardless of their current mode

• Version Control: Full audit trail of asset usage across different modes

🛠️ Cross-Mode Component Integration

Unified UI Components

// Universal Asset Upload Dialog - works in all modes
<UnifiedAssetUploadDialog
  isOpen={showDialog}
  onAssetUploaded={handleUpload}
  mode="project"          // "project" | "canvas" | "edit"
  nodeId={nodeId}         // Optional: for canvas context
  allowedTypes={['image', 'video', 'audio']}
  showProgress={true}
/>

// Cross-Mode Media Library - aggregates all assets
<UnifiedMediaLibrary
  onAssetSelect={handleSelect}
  showCanvasAssets={true}   // Include canvas node assets
  showProjectAssets={true}  // Include project gallery assets
  filterByMode="all"        // "project" | "canvas" | "edit" | "all"
  contentTypeFilter="image" // Type-specific filtering
/>

Mode-Aware Hook System

// Automatically detects current mode and optimizes accordingly
const { uploadFile } = useAssetUpload(); // Universal uploader
const { assets } = useProjectAssets(); // Project + Canvas assets
const { allMedia } = useMediaLibrary(canvasNodes); // Everything combined

// Canvas-specific with cross-mode integration
const { uploadToNode } = useNodeUpload(nodeId); // Canvas + Collection storage

🛠️ Core Components

Single Source of Truth

// /src/lib/unifiedAssetManager.ts
export async function uploadAsset(
  file: File,
  options: UploadOptions
): Promise<UploadResult>;
export async function uploadAssetFromUrl(
  url: string,
  fileName: string,
  options: UploadOptions
): Promise<UploadResult>;
export async function getProjectAssets(
  projectId: string,
  filter?: AssetFilter
): Promise<AssetMetadata[]>;
export async function deleteAsset(
  assetId: string,
  blobName: string
): Promise<boolean>;

React Hook System

// /src/hooks/useUnifiedAssets.ts
const { uploadFile, uploading, progress } = useAssetUpload();
const { assets, loading, refetch } = useProjectAssets();
const { allMedia, firestoreAssets, nodeAssets } = useMediaLibrary();

UI Components

// Unified upload dialog for all contexts
<UnifiedAssetUploadDialog
  isOpen={showDialog}
  onAssetUploaded={handleUpload}
  nodeId="canvas-node-123" // Optional: for canvas uploads
  allowedTypes={['image', 'video']}
/>

// Complete media library with filtering
<UnifiedMediaLibrary
  onAssetSelect={handleSelect}
  allowedTypes={['image']}
  showUploadButton={true}
/>

📁 Storage Architecture

Azure Blob Storage Structure

user-assets/
├── projects/{projectId}/
│   ├── assets/{timestamp}-{randomId}-{filename}     ← Project/Edit Tab uploads
│   └── nodes/{nodeId}/{timestamp}-{randomId}-{filename}  ← Canvas Tab uploads
└── Public URLs: https://storage.azure.com/container/...

Firestore Collection Structure

// Collection: project-assets
interface AssetMetadata {
  id: string;
  projectId: string; // Index for efficient queries
  fileName: string;
  azureUrl: string; // Primary URL field
  blobName: string;
  nodeId?: string; // Set for canvas uploads
  isNodeAsset?: boolean; // Differentiates canvas vs project uploads
  uploadedAt: string;
  uploadedBy: string;
  tags?: string[];
}

🚀 Cross-Mode API Architecture

Universal Upload Endpoint

// POST /api/assets - Handles all modes with context detection
{
  "files": [File],           // Multipart file upload
  "projectId": "proj_123",   // Required for organization
  "userId": "user_456",      // Authentication context
  "nodeId": "node_789",      // Optional: Canvas mode context
  "tags": ["gallery"],       // Optional: Categorization
  "mode": "canvas"           // "project" | "canvas" | "edit"
}

// Response includes cross-mode metadata
{
  "success": true,
  "assets": [{
    "id": "asset_123",
    "azureUrl": "https://cdn.../file.jpg",
    "isNodeAsset": true,        // Indicates canvas origin
    "availableInModes": ["canvas", "project", "edit"]
  }]
}

Cross-Mode Asset Retrieval

// GET /api/assets/list - Aggregated asset fetching
{
  "projectId": "proj_123",
  "includeNodeAssets": true,    // Include canvas uploads
  "contentType": "image/*",     // Filter by type
  "mode": "all",                // "project" | "canvas" | "edit" | "all"
  "tags": ["gallery", "ai-generated"]
}

// Returns unified asset array with mode context
{
  "assets": [
    { "id": "1", "isNodeAsset": false, "uploadedInMode": "project" },
    { "id": "2", "isNodeAsset": true, "uploadedInMode": "canvas", "nodeId": "node_789" }
  ]
}

Mode-Specific Endpoints

// Canvas-specific with cross-mode persistence
POST /api/upload-media
- Canvas node uploads with dual storage
- Maintains canvas functionality while enabling cross-mode access
- Automatic metadata enrichment for discoverability

// Project gallery management
POST /api/assets/bulk
- Bulk operations for project asset management
- Team sharing and collaboration features
- Cross-mode availability by default

🎯 Cross-Mode Integration Benefits

• Seamless Workflow: Upload in any mode, access everywhere instantly

• Zero Context Switching: Assets available regardless of current working mode

• Intelligent Organization: Context-aware categorization with cross-mode discoverability

• Performance Optimized: Smart caching and prefetching across all modes

• Real-Time Collaboration: Asset changes propagate instantly to all team modes

• Type-Safe Operations: Full TypeScript integration with mode-aware interfaces

• Unified Developer Experience: Single API surface for all asset operations

• Scalable Architecture: Cloud-native with automatic cross-mode synchronization

🔧 Service Management

EditorOrchestrator

Central service coordinator that manages:

• Service initialization and shutdown

• Cross-service communication

• Health monitoring and reporting

• Event coordination

Key Methods

// Initialize all services
await editorOrchestrator.initialize();

// Get system health report
const health = await editorOrchestrator.getHealthReport();

// Listen for system events
editorOrchestrator.on("performance-warning", handleWarning);

// Restart services if needed
await editorOrchestrator.restart();

🚨 Error Handling & Fallbacks

Graceful Degradation

• Service Failures: Automatic fallback to basic functionality

• Worker Crashes: Automatic worker restart and task retry

• Memory Pressure: Reduced quality modes to free memory

• Network Issues: Offline mode with cached resources

Error Recovery

try {
  await remotionService.renderFrame(options);
} catch (error) {
  // Automatic fallback to canvas rendering
  console.warn("Remotion render failed, falling back to canvas");
  useCanvasRenderer();
}

Azure Integration

This project uses Azure Blob Storage and Azure OpenAI for comprehensive AI workflows:

Storage Configuration

• Storage Account: eurusworkflows

• Containers: discover-assets, node-autosave

• Assets: Images, videos, and generated content

• Management: See AZURE_ASSET_MANAGEMENT.md for detailed instructions

AI Services

• Azure OpenAI 4o mini: Image analysis and description

• Azure OpenAI 4.1 nano: Intent processing and context understanding

• Azure Whisper: Ultra-smooth speech-to-text transcription

• Optimized parameters: Configured for maximum compatibility and performance

🎮 Usage

Landing Page

1. Hero Section: Experience the interactive "Irreplacably Creative" canvas

2. Drag & Drop: Move nodes around the canvas to see real-time interactions

3. 3D Models: Click on 3D nodes to see GLB models rendered in real-time

4. Scroll Experience: Smooth scroll through different sections

Authentication

• Click "Get Started" to open the authentication modal

• Sign in with email/password or social providers

• Access the full creative workspace after authentication

Creative Workflows

• Node-based Interface: Drag and drop AI tools

• Real-time Preview: See results as you work

• Collaboration: Work with team members in real-time

• Asset Management: Upload and organize your creative assets

Video Editor Workflows

• Professional Video Editing: Timeline-based editing with multiple tracks

• Remotion Compositions: React-based video component creation

• Background Processing: Non-blocking video operations with worker threads

• Performance Optimization: Automatic quality adjustment and resource management

• Real-time Collaboration: Multi-user video editing with live cursors

• Export Options: Multiple format support with quality presets

📁 Project Structure

eurus-studio/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   ├── discover/          # Discovery page
│   ├── pricing/           # Pricing page
│   └── project/           # Project workspace
├── components/            # React components
│   ├── ui/               # Reusable UI components
│   ├── collaboration/    # Real-time collaboration
│   ├── nodes/            # Workflow nodes
│   ├── editor/           # Enhanced video editor
│   │   ├── core/         # Core editor components
│   │   ├── workers/      # Worker thread management
│   │   ├── services/     # Service layer (Orchestrator, Remotion, Performance)
│   │   ├── player/       # Enhanced video player
│   │   ├── timeline/     # Timeline components
│   │   └── panels/       # Editor panels
│   ├── landing-page.tsx  # Main landing page
│   └── navigation.tsx    # Navigation component
├── lib/                  # Utility libraries
│   ├── models/           # AI model integrations
│   ├── unifiedAssetManager.ts  # UNIFIED Asset Management (Single Source of Truth)
│   ├── azure-storage.ts  # Azure Blob Storage
│   └── firebase.ts       # Firebase configuration
├── hooks/                # Custom React hooks
│   ├── useUnifiedAssets.ts    # Unified asset management hooks
│   └── use-auth.tsx      # Authentication hooks
├── components/           # React components
│   ├── shared/           # Shared components
│   │   ├── UnifiedAssetUploadDialog.tsx  # Universal upload dialog
│   │   └── UnifiedMediaLibrary.tsx       # Complete media library
│   └── ...               # Other components
├── public/               # Static assets
│   ├── images/           # Image assets
│   ├── videos/           # Video assets
│   └── workers/          # Web worker scripts
│       ├── video-processor.js     # Video processing worker
│       ├── audio-processor.js     # Audio processing worker
│       ├── remotion-renderer.js   # Remotion rendering worker
│       ├── image-processor.js     # Image processing worker
│       └── timeline-calculator.js # Timeline calculation worker
├── hooks/                # Custom React hooks
├── types/                # TypeScript type definitions
└── styles/               # Global styles

🎨 Key Components

Landing Page Features

• InfiniteCanvasBackground: Animated particle background

• DraggableNodesLayer: Interactive node system

• ProductsScrollSection: AI model showcase with videos

• IdeasScrollNodesSection: Creative inspiration section

• Model3D: 3D model rendering with error boundaries

3D Model Integration

• Error Boundaries: Graceful fallback for 3D model failures

• Auto-rotation: Smooth 3D model animations

• Optimized Loading: Preloaded GLB models for performance

Video Editor Components

• Editor: Main video editor orchestrator with service management

• EnhancedVideoPlayer: Advanced video player with dual rendering modes

• Timeline: Professional timeline with multi-track support

• WorkerManager: Centralized worker thread coordination

• PerformanceMonitor: Real-time performance tracking and optimization

• RemotionService: High-performance React-based video rendering

🚀 Deployment

Vercel (Recommended)

# Deploy to Vercel
vercel --prod

# Or connect your GitHub repository to Vercel dashboard

Docker

# Build Docker image
docker build -t eurus-studio .

# Run container
docker run -p 3000:3000 eurus-studio

🔧 Configuration

Environment Variables

# Firebase
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id

# Azure Storage
AZURE_STORAGE_CONNECTION_STRING=your_connection_string
AZURE_STORAGE_CONTAINER_NAME=your_container_name

# AI Models
OPENAI_API_KEY=your_openai_key
GEMINI_API_KEY=your_gemini_key

🎯 Performance Optimizations

• Code Splitting: Dynamic imports for heavy components

• Image Optimization: Next.js Image component with lazy loading

• 3D Model Caching: GLB model preloading and caching

• Bundle Analysis: Optimized bundle sizes

• SSR/SSG: Server-side rendering for better SEO

🐛 Troubleshooting

Common Issues

3D Models Not Loading

• Check GLB file paths in /public/images/

• Ensure files are not corrupted

• Check browser WebGL support

Firebase Auth Issues

• Verify environment variables

• Check Firebase console configuration

• Ensure auth domain is whitelisted

Video Editor Performance Issues

• Check worker thread support in browser

• Ensure sufficient system memory (4GB+ recommended)

• Verify Remotion dependencies are properly installed

• Monitor performance overlay in development mode

• Try fallback canvas rendering if Remotion fails

Worker Thread Issues

• Ensure worker scripts are accessible in /public/workers/

• Check browser console for worker initialization errors

• Verify CORS settings for worker script loading

• Monitor worker pool status via EditorOrchestrator health reports

Performance Issues

• Reduce 3D model complexity

• Optimize image sizes

• Check network requests in DevTools

• Monitor memory usage with performance overlay

• Use adaptive quality settings in video editor

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices

• Use Tailwind CSS for styling

• Write meaningful commit messages

• Add JSDoc comments for complex functions

• Test your changes thoroughly

� Performance Best Practices

1. Worker Pool Sizing

// Optimal worker configuration based on CPU cores
const optimalConcurrency = Math.max(
  1,
  Math.floor(navigator.hardwareConcurrency / 2)
);

2. Memory Management

• Monitor memory usage with performance.memory

• Implement automatic cache cleanup

• Use object pools for frequently created objects

3. Frame Rate Optimization

• Target 30 FPS for smooth playback

• Drop frames when performance is poor

• Preload frames during idle time

4. Quality Scaling

• Start with medium quality, adjust based on performance

• Use lower quality for previews

• Scale resolution for better performance on low-end devices

🎨 Customization

Adding New Worker Types

1. Create worker script in /public/workers/

2. Add task types to workers/types.ts

3. Register with WorkerManager

4. Implement task handlers

Custom Effects and Filters

1. Extend the Remotion composition

2. Add effect types to the schema

3. Implement rendering logic

4. Register with the effects system

Performance Metrics

1. Extend the PerformanceMonitor

2. Add custom metric collection

3. Implement analysis functions

4. Create visualization components

🧪 Development Tools

Performance Overlay

Development mode shows real-time performance metrics:

• FPS counter

• Render time

• Memory usage

• System health status

Debug Controls

• Service restart (Ctrl+R)

• Performance logging

• Worker pool status

• Cache statistics

Health Monitoring

Comprehensive health reports include:

• Service status

• Performance metrics

• Recommendations

• System capabilities

🚀 Production Considerations

Build Optimization

• Bundle workers separately for better caching

• Minimize worker script sizes

• Use efficient data transfer formats

Monitoring

• Implement error reporting

• Track performance metrics

• Monitor user behavior patterns

Scaling

• Adjust worker pools based on device capabilities

• Implement progressive enhancement

• Use feature detection for advanced capabilities

📝 API Reference

Core Services

• editorOrchestrator - Central service coordinator

• workerManager - Worker pool management

• remotionService - Remotion rendering service

• performanceMonitor - Performance tracking

Components

• Editor - Main editor component

• EnhancedVideoPlayer - Advanced video player

• Timeline - Timeline component

• Various panels and controls

Types

• EditorState - Complete editor state

• WorkerTask - Worker task definition

• Clip - Video/audio/text clip

• Track - Timeline track

�📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Eurus Studio for the incredible landing page design

• Three.js community for 3D graphics support

• Next.js team for the amazing framework

• Tailwind CSS for the utility-first approach

• Remotion for React-based video rendering

• Web Workers API for background processing capabilities

� Troubleshooting

Asset Management Issues

Cross-Mode Asset Visibility

• Assets uploaded in Canvas not showing in Project: Check includeNodeAssets: true in useProjectAssets

• Canvas assets missing from Edit mode: Ensure useMediaLibrary(canvasNodes) includes current nodes

• Mode-specific filtering issues: Verify isNodeAsset field is correctly set in Firestore

• Real-time sync delays: Check Firestore listeners are active across all open modes

Upload Context Issues

• Canvas uploads not persisting to node: Verify nodeId parameter in upload options

• Project uploads appearing as node assets: Remove nodeId from upload calls in project mode

• Missing cross-mode metadata: Ensure mode parameter is correctly passed to upload API

Core System Issues

• "Firestore is not initialized" Error: Ensure operations run client-side with proper Firebase config

• Upload fails with "userId required": Add userId to all upload calls: uploadAsset(file, { projectId, userId })

• Assets not appearing: Verify currentProject.id is valid and Firestore permissions allow reads

• Azure Storage connection: Check AZURE_STORAGE_CONNECTION_STRING and container permissions

Performance Issues

• Slow cross-mode asset loading: Enable asset prefetching and check network tab for bottlenecks

• Memory usage in media library: Implement virtual scrolling for large asset collections

• Canvas performance with many assets: Use lazy loading and thumbnail optimization

Migration from Legacy System

• All asset.url references should be changed to asset.azureUrl

• Remove any IndexedDB or localStorage asset code

• Update import paths to use unified system only

�📞 Support

For support, please:

• Create an issue in the repository

• Check the troubleshooting section above

• Review the unified asset system documentation

• Check the video editor architecture docs

📚 Further Reading

• Remotion Documentation

• Web Workers API

• Performance Monitoring

• OffscreenCanvas

• Next.js App Router

• Three.js Documentation

---

Built with ❤️ using Next.js, Remotion, Three.js, and modern web technologies.

This enhanced creative platform provides a robust, scalable foundation for professional AI workflows and video editing applications with seamless Remotion integration and efficient worker thread utilization.

Studio WIP Deployment (stripe-integration)

This branch is connected to an Azure Static Web App (studio-wip) created solely for validating the new Stripe billing flows (subscriptions + pay-as-you-go). Every push to stripe-integration triggers the GitHub Action in .github/workflows/azure-static-web-apps-*.yml and automatically deploys the latest build.

NOTE: This environment points to the Stripe sandbox backend and Firebase staging project. Do not use real production keys.

trigger