Video Handoff App

A comprehensive application for creating password-protected video handoff pages where creators can record timestamped events, share project data, and receive final footage uploads from videographers.

Overview

Video Handoff App streamlines the video production workflow by providing a centralized platform where:

• Creators can create handoff pages with timestamped events, project metadata, and recording controls
• Videographers receive password-protected access to handoff pages and can upload final footage
• Observers receive email notifications about page submissions and footage uploads

Features

For Creators

• 📹 Create Handoff Pages - Set up new video handoff projects with StreamYard footage links
• ⏱️ Record Timestamps - Mark important events during recording with timestamps
• 🎮 StreamDeck Integration - Use physical buttons to mark timestamps hands-free
• 📊 Project Metrics - Track lines of code, prompts, and tokens used
• 📧 Email Management - Add videographers and observers to receive notifications
• 💾 Auto-save - Automatic saving of work in progress
• 🔐 Password Protection - Automatically generated passwords for secure access

For Videographers

• 🔑 Secure Access - Password-protected handoff pages
• 📤 File Upload - Upload multiple video files with progress tracking
• 📋 Complete Information - Access to all project details, timestamps, and explanations
• ☁️ Cloud Storage - Files uploaded to AWS S3 for reliable storage

For Observers

• 📬 Email Notifications - Stay informed about submissions and uploads
• 👀 Project Tracking - Monitor handoff progress

Technology Stack

Frontend

• React 18 with TypeScript
• Vite - Fast development and build tool
• React Router - Client-side routing
• Tailwind CSS - Utility-first CSS framework
• shadcn/ui - High-quality UI components
• Axios - HTTP client for API requests

Backend

• Node.js with Express
• TypeScript - Type-safe server code
• MongoDB with Mongoose - Database and ODM
• JWT - Token-based authentication
• Nodemailer - Email notifications via Gmail
• AWS S3 - File storage for video uploads

Development Tools

• ESLint - Code linting
• Concurrently - Run frontend and backend together

Prerequisites

Before setting up the project, ensure you have the following installed:

• Node.js (v18 or higher)
• npm (v9 or higher)
• MongoDB (v6 or higher) - Running locally or MongoDB Atlas account
• Git

Required Third-Party Services

1. AWS Account - For S3 file storage
2. Gmail Account - For sending email notifications
3. Elgato StreamDeck (Optional) - For hands-free timestamp marking

Local Setup

1. Clone the Repository

git clone <repository-url>
cd VideoHandoff

2. Install Dependencies

Install dependencies for all parts of the application:

# Install root dependencies
npm install

# Install server dependencies
cd server
npm install
cd ..

# Install client dependencies
cd client
npm install
cd ..

# Install shared dependencies
cd shared
npm install
cd ..

3. Environment Configuration

Server Environment Variables

Create a .env file in the server/ directory:

cd server
cp .env.example .env  # Or create manually

Configure the following environment variables in server/.env:

# Server Configuration
PORT=3000
NODE_ENV=development

# Database
MONGODB_URI=mongodb://localhost:27017/videohandoff

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_REFRESH_SECRET=your-super-secret-refresh-key-change-this-in-production
ACCESS_TOKEN_EXPIRY=15m
REFRESH_TOKEN_EXPIRY=7d

# AWS S3 Configuration
AWS_ACCESS_KEY_ID=your-aws-access-key
AWS_SECRET_ACCESS_KEY=your-aws-secret-key
AWS_REGION=us-east-1
AWS_S3_BUCKET_NAME=your-bucket-name

# Email Configuration (Gmail)
EMAIL_SERVICE=gmail
EMAIL_USER=[email protected]
EMAIL_PASSWORD=your-app-specific-password
EMAIL_FROM=[email protected]

# Frontend URL
FRONTEND_URL=http://localhost:5173

Client Environment Variables (Optional)

If needed, create a .env file in the client/ directory:

VITE_API_URL=http://localhost:3000

4. Third-Party Service Setup

MongoDB Setup

Option A: Local MongoDB

# Install MongoDB (macOS with Homebrew)
brew tap mongodb/brew
brew install mongodb-community

# Start MongoDB
brew services start mongodb-community

Option B: MongoDB Atlas (Cloud)

1. Create account at mongodb.com/cloud/atlas
2. Create a new cluster
3. Get connection string and update MONGODB_URI in .env

AWS S3 Setup

Follow the detailed guide in S3_CORS_SETUP.md

Quick Steps:

1. Create AWS account
2. Create S3 bucket
3. Configure CORS policy
4. Create IAM user with S3 permissions
5. Generate access keys
6. Update AWS credentials in .env

Gmail Setup

Follow the detailed guide in GMAIL_SETUP.md

Quick Steps:

1. Enable 2-Factor Authentication on your Gmail account
2. Generate App-Specific Password
3. Update EMAIL_USER and EMAIL_PASSWORD in .env

5. Database Seeding (Optional)

To populate the database with test data:

cd server
npm run seed

This creates:

• Test user accounts ([email protected], [email protected])
• Sample handoff records
• Demo data for development

6. Run the Application

Development Mode (Recommended)

From the root directory, run both frontend and backend together:

npm run start

This starts:

• Backend server on http://localhost:3000
• Frontend dev server on http://localhost:5173

Run Separately (Advanced)

Backend only:

cd server
npm run dev

Frontend only:

cd client
npm run dev

7. Access the Application

Open your browser and navigate to:

http://localhost:5173

Default Test Accounts:

• Email: [email protected] / Password: admin123
• Email: [email protected] / Password: user123

Project Structure

VideoHandoff/
├── client/                 # React frontend application
│   ├── src/
│   │   ├── api/           # API client functions
│   │   ├── components/    # React components
│   │   ├── contexts/      # React contexts (Auth, etc.)
│   │   ├── hooks/         # Custom React hooks
│   │   ├── pages/         # Page components
│   │   ├── lib/           # Utility functions
│   │   └── main.tsx       # Application entry point
│   ├── public/            # Static assets
│   └── package.json
│
├── server/                # Express backend application
│   ├── config/            # Configuration files
│   ├── models/            # Mongoose models
│   ├── routes/            # API routes
│   │   └── middlewares/   # Express middlewares
│   ├── services/          # Business logic services
│   ├── utils/             # Utility functions
│   ├── scripts/           # Database scripts
│   └── server.ts          # Server entry point
│
├── shared/                # Shared code between client/server
│   ├── config/            # Shared configurations
│   └── types/             # TypeScript type definitions
│
├── package.json           # Root package configuration
└── README.md             # This file

Available Scripts

Root Directory

• npm run start - Run both frontend and backend concurrently
• npm run lint - Run ESLint on all projects
• npm run lint:fix - Fix ESLint errors automatically

Server (cd server)

• npm run dev - Start backend in development mode with hot reload
• npm run build - Build backend for production
• npm run start - Start backend in production mode
• npm run lint - Run ESLint on server code
• npm run seed - Seed database with test data

Client (cd client)

• npm run dev - Start frontend development server
• npm run build - Build frontend for production
• npm run preview - Preview production build locally
• npm run lint - Run ESLint on client code

StreamDeck Integration (Optional)

For hands-free timestamp marking during recordings, you can integrate an Elgato StreamDeck.

Setup Guides:

• Simple Setup Guide - Recommended for most users
• Advanced Setup Guide - For custom configurations

Quick Overview:

1. Create and start a recording in the app
2. Download the StreamDeck configuration file
3. Import into StreamDeck software
4. Press the button to mark timestamps while recording

Additional Documentation

• Gmail Setup Guide - Detailed email configuration
• S3 CORS Setup Guide - AWS S3 configuration
• StreamDeck Setup - Physical button integration
• Changes Summary - Recent feature updates
• Persistent Recording Implementation - Technical details

Troubleshooting

MongoDB Connection Issues

Error: MongooseServerSelectionError: connect ECONNREFUSED

Solution:

# Check if MongoDB is running
brew services list

# Start MongoDB
brew services start mongodb-community

Port Already in Use

Error: EADDRINUSE: address already in use :::3000

Solution:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

Email Not Sending

Common Issues:

• Gmail App Password not configured correctly
• 2-Factor Authentication not enabled
• Less secure app access blocked

Solution: Follow GMAIL_SETUP.md

S3 Upload Failures

Common Issues:

• CORS policy not configured
• Invalid AWS credentials
• Insufficient S3 permissions

Solution: Follow S3_CORS_SETUP.md

Frontend Cannot Connect to Backend

Solution:

1. Verify backend is running on port 3000
2. Check proxy configuration in client/vite.config.ts
3. Ensure FRONTEND_URL in server .env matches client URL

Development Workflow

Making Changes

1. Frontend Changes:

   • Edit files in client/src/
   • Hot reload automatically updates browser
   • API calls should use functions in client/src/api/

2. Backend Changes:

   • Edit files in server/
   • Server automatically restarts with nodemon
   • Follow MVC pattern: Routes → Services → Models

3. Shared Types:

   • Edit files in shared/
   • Rebuild shared package: cd shared && npm run build

Code Quality

Before committing:

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

Testing Changes

1. Use seeded test data for consistent testing
2. Test with different user roles
3. Verify email notifications in development
4. Test file uploads with various video formats

Production Deployment

Build for Production

# Build all projects
npm run build

Environment Variables

Update .env files with production values:

• Use strong, unique JWT secrets
• Configure production MongoDB instance
• Use production AWS S3 bucket
• Set NODE_ENV=production

Security Considerations

• Never commit .env files
• Use strong passwords for JWT secrets
• Enable AWS S3 bucket encryption
• Configure proper CORS policies
• Use HTTPS in production
• Implement rate limiting for APIs

Contributing

1. Create a feature branch
2. Make your changes
3. Run linting and fix issues
4. Test thoroughly
5. Submit pull request

Support

For issues and questions:

• Check existing documentation in project root
• Review troubleshooting section
• Check server/client logs for errors

License

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

Acknowledgments

• Built with React, Express, and MongoDB
• UI components by shadcn/ui
• Icons by Lucide React