streamflow/README.md

# StreamFlow IPTV Application

[![Docker Hub](https://img.shields.io/docker/v/aiulian25/streamflow?label=Docker%20Hub&logo=docker)](https://hub.docker.com/r/aiulian25/streamflow)
[![Docker Pulls](https://img.shields.io/docker/pulls/aiulian25/streamflow)](https://hub.docker.com/r/aiulian25/streamflow)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A modern, feature-rich IPTV streaming application with secure Docker deployment.

## 🚀 Quick Start (3 Commands)

```bash
# 1. Download docker-compose.yml
wget https://raw.githubusercontent.com/aiulian25/streamflow/main/docker-compose.yml

# 2. Start the application
docker compose up -d

# 3. Access at http://localhost:12345
# Login: admin / admin (change on first login!)
```

**That's it!** See [DOCKER_INSTALLATION.md](DOCKER_INSTALLATION.md) for detailed setup.

## 🆕 Desktop Application Available!

StreamFlow now includes a **native Linux desktop application** (AppImage) with full feature parity!

**[→ View Desktop App Documentation](desktop-app/README.md)**

Features:
- ✅ Server connection management
- ✅ Encrypted credential storage
- ✅ 2FA support (TOTP & backup codes)
- ✅ Multi-language (EN, RO)
- ✅ Hardware acceleration
- ✅ All web app features

Quick start:
```bash
cd desktop-app
npm install
./build.sh
# AppImage created in dist/
```

---

## Features

- **Multi-Device Compatibility** - Works on all major platforms
- **Desktop App** - Native Linux application (AppImage) 🆕
- **Live TV & Radio** - Stream live channels and radio stations
- **Recording System** - Schedule and manage recordings
- **Multi-Language Support** - English and Romanian
- **Two-Factor Authentication** - Enhanced security with 2FA support
- **Light/Dark Theme** - Modern, glossy UI with transparent effects
- **User Profiles** - Multiple user support with individual settings
- **Security First** - Non-root containers, proper permissions, JWT authentication

## Technology Stack

### Backend
- Node.js with Express
- SQLite database
- JWT authentication
- FFmpeg & Streamlink for media processing
- Bcrypt for password hashing

### Frontend
- React 18 with Vite
- Material-UI (MUI) components
- React Router for navigation
- Zustand for state management
- i18next for internationalization

## Quick Start

### Prerequisites
- Docker and Docker Compose
- Git

### Installation

1. Clone the repository:
```bash
cd /home/iulian/projects/tv
```

2. Set environment variables (optional):
```bash
cp .env.example .env
# Edit .env with your preferred settings
```

3. Build and start the application:
```bash
docker-compose up -d
# Or use the convenience script
./scripts/start.sh
```

4. Access the application:
```
http://localhost:12345
```

5. Stop the application:
```bash
docker-compose down
# Or use the convenience script
./scripts/stop.sh
```

### Default Login
First user registration will create an account. No default credentials are provided for security.

## Development Setup

### Backend Development
```bash
cd backend
npm install
npm run dev
```

### Frontend Development
```bash
cd frontend
npm install
npm run dev
```

Frontend dev server runs on port 3000 with proxy to backend on 12345.

## Docker Security Features

- Non-root user execution (UID 1001)
- Minimal Alpine Linux base
- Security-opt: no-new-privileges
- Capability dropping (cap_drop: ALL)
- Read-only file system where possible
- Health checks enabled
- Proper file permissions (755/644, no 777)

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| PORT | 12345 | Application port |
| NODE_ENV | production | Environment mode |
| JWT_SECRET | (required) | JWT signing secret |
| SESSION_SECRET | (required) | Session secret |
| MAX_RECORDING_SIZE | 10GB | Maximum recording size |

## Project Structure

```
tv/
├── backend/
│   ├── database/          # Database models and schema
│   ├── jobs/              # Background cron jobs
│   ├── middleware/        # Express middleware
│   ├── routes/            # API routes
│   ├── utils/             # Utility functions
│   └── server.js          # Main server file
├── frontend/
│   ├── src/
│   │   ├── components/    # React components
│   │   ├── pages/         # Page components
│   │   ├── store/         # Zustand stores
│   │   ├── locales/       # Translation files (EN, RO)
│   │   └── theme.js       # MUI theme config
│   └── vite.config.js     # Vite configuration
├── desktop-app/           # 🆕 Linux Desktop Application (Electron)
│   ├── src/
│   │   ├── main/          # Electron main process
│   │   ├── preload/       # IPC bridge
│   │   └── renderer/      # Connection UI
│   ├── build/             # Build resources
│   ├── package.json       # Desktop app dependencies
│   ├── build.sh           # Build script
│   ├── README.md          # Desktop app documentation
│   ├── INSTALLATION.md    # Installation guide
│   ├── DEVELOPER_GUIDE.md # Developer documentation
│   ├── SECURITY_AUDIT.md  # Security review
│   └── CHANGELOG.md       # Version history
├── docs/                  # Documentation files
│   ├── ARCHITECTURE.md    # System architecture
│   ├── BUILD.md           # Build & deployment guide
│   ├── LOGO_GUIDE.md      # Logo & branding guide
│   ├── PROJECT_STRUCTURE.md # Detailed structure
│   ├── QUICK_REFERENCE.md # Quick reference guide
│   └── SETUP.md           # Setup instructions
├── scripts/               # Utility scripts
│   ├── start.sh           # Start application
│   └── stop.sh            # Stop application
├── data/                  # Persistent data (Docker volume)
├── logs/                  # Application logs (Docker volume)
├── uploads/               # User uploads (Docker volume)
├── Dockerfile             # Multi-stage Docker build
├── docker-compose.yml     # Docker Compose configuration
└── README.md              # This file
```

## Documentation

- **[Architecture Guide](docs/ARCHITECTURE.md)** - System design and architecture
- **[Build & Deployment](docs/BUILD.md)** - Complete build instructions for PWA, APK, AppImage
- **[Logo Guide](docs/LOGO_GUIDE.md)** - Branding and icon usage
- **[Project Structure](docs/PROJECT_STRUCTURE.md)** - Detailed file structure
- **[Quick Reference](docs/QUICK_REFERENCE.md)** - Common commands and tips
- **[Setup Guide](docs/SETUP.md)** - Detailed setup instructions

## API Endpoints

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

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

### Channels
- `GET /api/channels` - Get channels with filters
- `GET /api/channels/groups` - Get channel groups

### Additional Endpoints
- Recordings, Profiles, Radio, Groups, Settings, Stream, Stats

## Languages Supported

- **English (en)** - Default
- **Romanian (ro)** - Full translation

Change language in Settings page or it auto-detects browser language.

## Theme System

The application includes light and dark themes with:
- Glossy, transparent UI elements
- Material Design 3 principles
- Smooth animations and transitions
- Backdrop blur effects
- Responsive design

Toggle theme in Settings page. Theme preference is persisted.

## Contributing

This is a private project. For issues or feature requests, please contact the repository owner.

## License

Proprietary - All rights reserved

## Support

For support and questions, please refer to the project documentation or contact the development team.