streamflow/README.md

StreamFlow IPTV Application

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

🆕 Desktop Application Available!

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

→ View Desktop App Documentation

Features:

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

Quick start:

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:

cd /home/iulian/projects/tv

2. Set environment variables (optional):

cp .env.example .env
# Edit .env with your preferred settings

3. Build and start the application:

docker-compose up -d
# Or use the convenience script
./scripts/start.sh

4. Access the application:

http://localhost:12345

5. Stop the application:

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

cd backend
npm install
npm run dev

Frontend Development

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 - System design and architecture
• Build & Deployment - Complete build instructions for PWA, APK, AppImage
• Logo Guide - Branding and icon usage
• Project Structure - Detailed file structure
• Quick Reference - Common commands and tips
• Setup Guide - 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.