Skip to content

IMPLEMENTATION_GUIDE.md

Latest commit

 

History

History
468 lines (382 loc) · 13.3 KB

IMPLEMENTATION_GUIDE.md

File metadata and controls

468 lines (382 loc) · 13.3 KB
Raw

IvyLevel Video Streaming Platform - Implementation Guide

Overview

This document provides a comprehensive guide to the Netflix-style video streaming platform built for IvyLevel's coaching sessions. The system integrates with AWS S3 for video storage, implements intelligent video playback features, and provides a modern, responsive UI for both students and coaches to access their coaching sessions.

Latest Updates (November 2024)

  • Added Netflix-style video sessions view for coaches
  • Coaches can now view all their students' sessions in one place
  • Student name filtering instead of coach filtering for coach view
  • Smart start time detection for all videos
  • 3-tier caching system for optimal performance

Table of Contents

  1. System Architecture
  2. Technology Stack
  3. Setup Guide
  4. Core Features
  5. Implementation Details
  6. API Documentation
  7. Known Limitations
  8. Future Enhancements

System Architecture

Frontend Architecture

frontend/apps/unified-app/
├── src/
│   ├── components/
│   │   ├── student/
│   │   │   ├── SessionsViewOptimal.tsx  # Netflix-style video grid for students
│   │   │   ├── VideoPlayer.tsx         # Modal video player
│   │   │   └── StudentDashboard.tsx    # Student portal
│   │   ├── coach/
│   │   │   ├── CoachSessionsView.tsx   # Netflix-style video grid for coaches
│   │   │   ├── EnhancedCoachDashboard.tsx # Coach dashboard with Sessions tab
│   │   │   └── [Other coach components]
│   │   └── auth/
│   │       └── [Authentication components]
│   ├── services/
│   │   ├── videoPreloadService.ts      # Video caching & preloading
│   │   └── metadataCacheService.ts     # Session metadata caching
│   └── config/
│       └── api.ts                       # API endpoints configuration

Backend Architecture

backend/api/
├── main_s3_simple.py                    # Main API with S3 integration
├── main_simple.py                       # Simple API without S3
└── main_production_ready.py             # Full production API

Technology Stack

Frontend

  • React 18.2 with TypeScript
  • Vite 5.4 for build tooling
  • Styled Components for styling
  • React Router v6 for navigation
  • React Query for data fetching
  • Intersection Observer API for lazy loading

Backend

  • FastAPI (Python) for REST API
  • Boto3 for AWS S3 integration
  • Uvicorn as ASGI server
  • Pydantic for data validation

Infrastructure

  • AWS S3 for video storage
  • Presigned URLs for secure video access
  • PostgreSQL (optional, for production)

Setup Guide

Prerequisites

  • Node.js v22+
  • Python 3.9+
  • AWS account with S3 access
  • Git

Backend Setup

  1. Clone the repository:
git clone [repository-url]
cd ivylevel_one/backend/api
  1. Create virtual environment:
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies:
pip install -r requirements.txt
  1. Set AWS credentials:
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"
  1. Start the backend:
python main_s3_simple.py

The API will be available at http://localhost:8000

Frontend Setup

  1. Navigate to frontend:
cd frontend/apps/unified-app
  1. Install dependencies:
npm install
  1. Start development server:
npm run dev

The app will be available at http://localhost:5173

Default Credentials

Students:

  • Email: hudasir4j@gmail.com, Password: Welcome123!
  • Email: kavyamridula@gmail.com, Password: Welcome123!

Coaches:

  • Email: jennyduan@ivymentors.co, Password: Welcome123!
  • Email: janice@ivymentors.co, Password: Welcome123!

Core Features

1. Netflix-Style Video Grid

  • Responsive Layout: Adapts from 2-6 columns based on screen size
  • Hover Preview: Videos auto-play on hover with smart start time
  • Lazy Loading: Uses Intersection Observer for performance
  • Skeleton Loading: Smooth loading states
  • CSS Containment: Prevents layout shifts

2. Smart Start Time Detection

  • Automatic Blank Screen Skip: Analyzes transcript files to find when conversation starts
  • Multiple Format Support: Handles various transcript JSON formats
  • Intelligent Fallbacks:
    • Regular sessions: 15 seconds
    • Game plans: 30 seconds
    • Check-ins: 60 seconds
  • Caching: Start times are cached for performance

3. YouTube-Style Video Player

  • Full-Screen Mode: Immersive viewing experience
  • Sidebar Navigation: Browse other sessions while watching
  • Video Controls: Native HTML5 controls
  • Smart Resume: Videos start from smart start time

4. Advanced Filtering

For Students:

  • Coach Filter: Filter by Jenny, Erin, Rishi, Marissa, Steven, Janice
  • Category Filter: Essays, Test Prep, College Planning, etc.
  • Search: Real-time search across titles
  • Week Sorting: Sessions sorted by week number

For Coaches:

  • Student Filter: Filter by student name (e.g., Huda, Anoushka, Arshiya, Minseo)
  • Category Filter: Same categories as student view
  • Multi-Student View: See all students' sessions in one place
  • Search: Search across all students' sessions

5. S3 Integration

  • Secure Access: Presigned URLs with 1-hour expiration
  • Folder Structure: Students/{StudentName}/ organization
  • Auxiliary Files: Reads transcript.json, metadata.json, aiinsights.md
  • Performance: 5-minute metadata cache, 55-minute URL cache

6. Video Caching System

  • Three-Tier Cache:
    1. Metadata cache (LocalStorage)
    2. Preview URL cache
    3. Full video URL cache
  • Smart Prefetching: Adjacent videos are prefetched
  • Offline Support: Blob caching for watched videos

Implementation Details

Video Preview on Hover

// SessionsViewOptimal.tsx
const handleVideoHover = useCallback((sessionId: string) => {
  setHoveredVideo(sessionId);
  
  // Debounced preview loading
  if (hoverTimeoutRef.current) {
    clearTimeout(hoverTimeoutRef.current);
  }
  
  hoverTimeoutRef.current = setTimeout(async () => {
    // Load video preview after 500ms hover
    const session = sessions.find(s => s.id === sessionId);
    if (session && session.video_url) {
      // Video auto-plays from smart_start_time
    }
  }, 500);
}, [sessions]);

Smart Start Time Extraction

# main_s3_simple.py
def extract_smart_start_time(bucket_name: str, video_key: str, s3_client) -> int:
    # 1. Check for transcript.json in same S3 folder
    # 2. Parse transcript for first meaningful speech
    # 3. Skip entries with "otterpilot", "notetaker", etc.
    # 4. Look for conversation starters like "hi", "hello", "how are you"
    # 5. Return timestamp with 2-second buffer
    # 6. Fall back to intelligent defaults if no transcript

Presigned URL Generation

video_url = s3_client.generate_presigned_url(
    'get_object',
    Params={'Bucket': bucket_name, 'Key': file_key},
    ExpiresIn=3600  # 1 hour
)

API Documentation

Authentication

POST /api/auth/login

{
  "email": "hudasir4j@gmail.com",
  "password": "Welcome123!"
}

Response:

{
  "success": true,
  "user": {
    "id": "student_007",
    "email": "hudasir4j@gmail.com",
    "name": "Huda",
    "role": "student"
  },
  "access_token": "demo_token_12345",
  "expires_in": 3600
}

Get Student Sessions

GET /api/student/sessions?page=1&limit=20&coach=Jenny&category=Essays

Response:

{
  "sessions": [
    {
      "id": "session_abc123",
      "title": "Week 99 - Essay Review with Jenny",
      "description": "Essay Review session with Jenny",
      "duration": "45:00",
      "coach": "Jenny",
      "category": "Essays",
      "thumbnail": "https://...",
      "video_url": "https://s3-presigned-url...",
      "date": "2025-07-07",
      "week": 99,
      "smart_start_time": 95,  // seconds
      "student": "Huda"
    }
  ],
  "coaches": ["Jenny", "Erin", "Rishi"],
  "categories": ["Essays", "Test Prep"],
  "total": 150,
  "page": 1,
  "totalPages": 8
}

Get Coach Sessions

GET /api/coach/sessions?page=1&limit=20&student=Huda&category=Essays

Response:

{
  "sessions": [
    {
      "id": "session_abc123",
      "title": "Week 99 - Huda - Essay Review",
      "description": "Essay Review session with Huda",
      "duration": "45:00",
      "student": "Huda",  // Note: student name instead of coach
      "category": "Essays",
      "thumbnail": "https://...",
      "video_url": "https://s3-presigned-url...",
      "date": "2025-07-07",
      "week": 99,
      "smart_start_time": 95,
      "file_name": "Week99_Huda_Essays_Jenny.mp4",
      "watched": false,
      "progress": 0
    }
  ],
  "students": ["Huda", "Anoushka", "Arshiya", "Minseo"],  // Note: students instead of coaches
  "categories": ["Essays", "Test Prep", "College Planning"],
  "total": 275,
  "page": 1,
  "totalPages": 14
}

Known Limitations

1. Smart Start Time Accuracy

  • Issue: Some videos start at conservative fallback times (15s) instead of actual speaking time
  • Cause:
    • Transcript files may not be present for all videos
    • Some transcript formats may not be fully supported
    • Early detection algorithm may miss nuanced conversation starts
  • Example: Week 98 starts at 0:15 but actual conversation begins at 1:35
  • Workaround: Manual adjustment of fallback times in code

2. Thumbnail Generation

  • Current: Using placeholder images from picsum.photos
  • Limitation: No actual video thumbnails extracted
  • Future: Implement video frame extraction at smart start time

3. Video Duration

  • Current: Hardcoded to "45:00" for all videos
  • Limitation: No actual duration extraction from video files
  • Future: Use FFprobe or video metadata API

4. Offline Limitations

  • Blob Storage: Limited to 500MB total cache
  • No Background Sync: Cached videos don't update automatically

5. Search Limitations

  • Current: Only searches titles, not transcript content
  • No Fuzzy Search: Exact substring matching only

Future Enhancements

Phase 1 - Short Term

  1. Improved Smart Start Detection

    • ML-based speech detection
    • Visual frame analysis to detect when people appear
    • Multiple transcript format support

  2. Real Thumbnails

    • Extract frame at smart_start_time + 5 seconds
    • Generate and cache in S3

  3. Video Analytics

    • Track watch time and completion rates
    • Generate heatmaps of most-watched sections

Phase 2 - Medium Term

  1. Transcript Search

    • Full-text search across all transcripts
    • Jump to specific moments in videos

  2. AI Insights Integration

    • Display key takeaways from aiinsights.md
    • Auto-generate session summaries

  3. Mobile App

    • React Native implementation
    • Offline video download

  4. Live Streaming

    • WebRTC integration for live sessions
    • Real-time chat and Q&A

Phase 3 - Long Term

  1. Personalized Recommendations

    • ML-based content recommendations
    • Learning path suggestions

  2. Interactive Features

    • In-video quizzes and assignments
    • Collaborative note-taking

  3. Advanced Analytics

    • Coach performance metrics
    • Student engagement tracking
    • ROI measurement

Performance Optimizations

  1. Lazy Loading: Videos load only when visible
  2. Debounced Hover: 500ms delay prevents excessive preview loads
  3. Caching Strategy:
    • S3 metadata: 5 minutes
    • Presigned URLs: 55 minutes
    • LocalStorage: 30 minutes
  4. CSS Containment: Prevents layout recalculations
  5. Virtual Scrolling: (Future) For 1000+ videos

Security Considerations

  1. Presigned URLs: Expire after 1 hour
  2. CORS: Restricted to specific origins
  3. Authentication: JWT tokens (in production)
  4. S3 Bucket Policies: Least privilege access

Troubleshooting

Videos Not Playing

  1. Check browser console for CORS errors
  2. Verify S3 presigned URL hasn't expired
  3. Ensure AWS credentials are valid

Hover Preview Not Working

  1. Check if video_url is present in session data
  2. Verify smart_start_time is reasonable (not 0 or > duration)
  3. Check browser autoplay policies

Slow Loading

  1. Check S3 bucket region (should be close to users)
  2. Verify caching is working (check DevTools Network tab)
  3. Consider implementing CDN for videos

Development Workflow

  1. Feature Branch: Create feature/your-feature-name
  2. Local Testing: Test with both S3 and mock data
  3. Code Review: Ensure TypeScript types are correct
  4. Performance: Check with Chrome DevTools Performance tab
  5. Accessibility: Test with screen readers

Deployment

Production Checklist

  • Set production AWS credentials
  • Configure CORS for production domain
  • Enable HTTPS
  • Set up monitoring (Sentry, etc.)
  • Configure CDN for videos
  • Set up database backups
  • Load test with expected traffic

For questions or issues, please contact the development team or create an issue in the repository.