# 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
```bash
docker-compose logs -f backend
```

### View frontend console
Open browser DevTools (F12) → Console tab

### Check running containers
```bash
docker-compose ps
```

### Rebuild images
```bash
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