videoscroller/.github/copilot-instructions.md

Ticky Project - Development Guide

Project Overview

Self-hosted TikTok-style infinite video scroller with Python/FastAPI backend and vanilla JavaScript frontend. Runs in Docker Compose.

Key Features

• Infinite scroll with lazy loading
• Mobile swipe navigation (up/down)
• Desktop keyboard and mouse wheel support
• Responsive design (mobile/desktop)
• Automatic video preloading
• REST API for random video selection

Architecture

Backend (Python/FastAPI)

• Port: 3001
• Framework: FastAPI + Uvicorn
• Key File: backend/main.py
• Features:
  • Random video selection from folder
  • Static file serving for videos
  • CORS enabled for frontend access

Frontend (Vanilla JS)

• Port: 3000
• File: frontend/app.js with styles.css
• Features:
  • Swipe gesture detection
  • Keyboard/mouse wheel navigation
  • Lazy loading and preloading
  • Responsive CSS for mobile/desktop

Common Tasks

Add a new backend endpoint

1. Open backend/main.py
2. Add @app.get() or @app.post() decorator
3. Implement endpoint logic
4. Restart backend: docker-compose restart backend

Customize frontend styling

1. Edit frontend/styles.css
2. Modify colors, sizes, animations
3. Changes reflect immediately on page refresh

Change video directory

1. Update docker-compose.yml VIDEOS_DIR variable
2. Or mount different volume path
3. Restart containers: docker-compose restart

Add video metadata

1. Modify backend response in main.py (add duration, thumbnail URL, etc.)
2. Update frontend renderVideo() in app.js to display new fields

Debugging

View backend logs

docker-compose logs -f backend

View frontend console

Open browser DevTools (F12) → Console tab

Check running containers

docker-compose ps

Rebuild images

docker-compose down && docker-compose up --build

Performance Considerations

• Videos should be optimized (compressed MP4s recommended)
• Use landscape orientation videos for best desktop experience
• Preloading limited to next video to save bandwidth
• Only current ± 1 videos rendered in DOM

Browser Support

• Chrome/Edge: Full support
• Firefox: Full support
• Safari: Full support (iOS 12.2+)
• Mobile browsers: Optimized for touch

Future Enhancement Ideas

• Video filtering/search
• User ratings or favorites
• Thumbnail previews
• Video duration display
• Playlist management
• Authentication
• CDN integration