streamflow/docs/QUICK_REFERENCE.md

# StreamFlow IPTV - Quick Reference

## 🚀 Quick Start Commands

```bash
# Start the application
./start.sh
# or
docker-compose up -d

# Stop the application
./stop.sh
# or
docker-compose down

# View logs
docker-compose logs -f

# Restart
docker-compose restart

# Rebuild
docker-compose build --no-cache
```

## 🌐 URLs

- **Application**: http://localhost:12345
- **Health Check**: http://localhost:12345/api/health
- **API Base**: http://localhost:12345/api

## 🔑 Default Configuration

| Setting | Value |
|---------|-------|
| Port | 12345 |
| Database | SQLite (/app/data/streamflow.db) |
| User | appuser (UID 1001) |
| Max Upload | 50MB |
| JWT Expiry | 7 days |

## 📡 API Endpoints

### Authentication
```
POST   /api/auth/register      # Register new user
POST   /api/auth/login         # Login
GET    /api/auth/verify        # Verify token
```

### Playlists
```
GET    /api/playlists          # List playlists
POST   /api/playlists/url      # Add from URL
POST   /api/playlists/upload   # Upload M3U
DELETE /api/playlists/:id      # Delete
PATCH  /api/playlists/:id      # Rename
POST   /api/playlists/bulk-delete  # Bulk delete
```

### Channels
```
GET    /api/channels           # List channels
GET    /api/channels/groups    # List groups
```

## 🔧 Environment Variables

```bash
# Required
PORT=12345
JWT_SECRET=your_secret_here
SESSION_SECRET=your_secret_here

# Optional
NODE_ENV=production
MAX_RECORDING_SIZE=10GB
EPG_UPDATE_INTERVAL=3600000
LOG_LEVEL=info
```

## 🐳 Docker Commands

```bash
# Build
docker-compose build

# Start (detached)
docker-compose up -d

# Start (foreground)
docker-compose up

# Stop
docker-compose down

# Stop and remove volumes
docker-compose down -v

# View logs
docker-compose logs -f streamflow

# Execute command in container
docker-compose exec streamflow sh

# List running containers
docker-compose ps

# Restart specific service
docker-compose restart streamflow
```

## 📦 NPM Scripts

```bash
# Root scripts
npm start                    # Start application
npm run install:all          # Install all dependencies
npm run docker:build         # Build Docker image
npm run docker:up            # Start containers
npm run docker:down          # Stop containers
npm run docker:logs          # View logs

# Backend scripts (cd backend)
npm install                  # Install dependencies
npm start                    # Start server
npm run dev                  # Start with nodemon

# Frontend scripts (cd frontend)
npm install                  # Install dependencies
npm run dev                  # Start dev server (port 3000)
npm run build                # Build for production
npm run preview              # Preview production build
```

## 🗃️ Database Tables

- `users` - User accounts
- `profiles` - User profiles
- `playlists` - M3U playlists
- `channels` - TV channels
- `custom_groups` - User groups
- `group_channels` - Group assignments
- `epg_data` - EPG information
- `epg_sources` - EPG sources
- `recordings` - Recording data
- `watch_history` - View history
- `favorites` - Favorite channels
- `settings` - User settings
- `api_tokens` - API tokens
- `logo_cache` - Logo cache

## 🌍 Languages

| Code | Language | Flag |
|------|----------|------|
| en   | English  | 🇬🇧 |
| ro   | Română   | 🇷🇴 |

## 🎨 Theme

- **Light Theme**: Default
- **Dark Theme**: Toggle in Settings
- **Auto-save**: Theme preference persisted

## 📁 File Locations

```
/app/data/                  # Persistent data
  ├── streamflow.db        # Database
  ├── playlists/           # Uploaded playlists
  ├── recordings/          # Recorded content
  ├── logos/               # Channel logos
  ├── epg/                 # EPG cache
  └── uploads/             # User uploads

/app/logs/                 # Application logs
  ├── error.log           # Error logs
  └── combined.log        # All logs
```

## 🔒 Security Features

- ✅ Non-root container user (UID 1001)
- ✅ JWT authentication (7-day expiry)
- ✅ Bcrypt password hashing (10 rounds)
- ✅ Rate limiting (5 login attempts/15min)
- ✅ Helmet security headers
- ✅ Input validation
- ✅ CORS protection
- ✅ No privilege escalation
- ✅ Capability dropping
- ✅ Health checks

## 🐛 Troubleshooting

### Container won't start
```bash
docker-compose logs
```

### Port already in use
```bash
# Edit docker-compose.yml, change:
ports:
  - "8080:12345"  # Change 8080 to free port
```

### Permission denied
```bash
# Fix permissions
sudo chown -R 1001:1001 ./data ./logs
```

### Reset database
```bash
# WARNING: Deletes all data
docker-compose down -v
docker-compose up -d
```

### Can't connect
```bash
# Check if running
docker-compose ps

# Check logs
docker-compose logs -f

# Test health
curl http://localhost:12345/api/health
```

## 📊 Monitoring

```bash
# View container stats
docker stats streamflow-app

# Check health status
docker inspect --format='{{.State.Health.Status}}' streamflow-app

# View recent logs
docker-compose logs --tail=100 streamflow
```

## 🔄 Backup & Restore

### Backup
```bash
# Backup data volume
docker run --rm \
  -v streamflow-data:/data \
  -v $(pwd)/backup:/backup \
  alpine tar czf /backup/backup-$(date +%Y%m%d).tar.gz /data
```

### Restore
```bash
# Restore data volume
docker run --rm \
  -v streamflow-data:/data \
  -v $(pwd)/backup:/backup \
  alpine tar xzf /backup/backup-YYYYMMDD.tar.gz -C /
```

## 🎯 Features Quick Access

| Feature | Page/Location |
|---------|---------------|
| Watch Live TV | Dashboard → Live TV |
| Listen Radio | Dashboard → Radio |
| Add Playlist | Settings or Sidebar |
| Schedule Recording | Channel → Record button |
| Change Theme | Settings → Theme toggle |
| Change Language | Settings → Language dropdown |
| View Favorites | Dashboard → Favorites |
| Manage Profiles | Settings → Profiles |

## 📱 Supported Features

- ✅ Live TV streaming
- ✅ Radio streaming
- ✅ EPG (Electronic Program Guide)
- ✅ Recording (scheduled & manual)
- ✅ Picture-in-Picture (PiP)
- ✅ Multi-device sync
- ✅ User profiles
- ✅ Favorites
- ✅ Custom groups
- ✅ Watch history
- ✅ Multi-language (EN/RO)
- ✅ Light/Dark themes
- ✅ Responsive design

## 🔗 Useful Links

- Project root: `/home/iulian/projects/tv`
- Documentation: `README.md`, `SETUP.md`, `ARCHITECTURE.md`
- Issue tracker: Contact development team
- Health check: http://localhost:12345/api/health

---

**Version**: 1.0.0  
**Last Updated**: December 2025