97 lines
2.4 KiB
Markdown
97 lines
2.4 KiB
Markdown
# 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
|