feat: Add comprehensive documentation suite and reorganize project structure

- Created complete documentation in docs/ directory - Added PROJECT_OVERVIEW.md with feature highlights and getting started guide - Added ARCHITECTURE.md with system design and technical details - Added SECURITY.md with comprehensive security implementation guide - Added DEVELOPMENT.md with development workflows and best practices - Added DEPLOYMENT.md with production deployment instructions - Added API.md with complete REST API documentation - Added CONTRIBUTING.md with contribution guidelines - Added CHANGELOG.md with version history and migration notes - Reorganized all documentation files into docs/ directory for better organization - Updated README.md with proper documentation links and quick navigation - Enhanced project structure with professional documentation standards
2025-10-21 00:39:45 -07:00
commit 0b7e2d0a5b
6080 changed files with 1332936 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,215 @@
+# EasyStream
+
+High‑end YouTube‑style media platform supporting Videos, Shorts, Live Streams, Images, Audio, Documents, and Blogs. It ships with an admin backend, strong security primitives, detailed logging, containerized deployment, and RTMP/HLS live streaming via SRS.
+
+This document helps you understand the codebase, run it locally, and work productively within the project.
+
+## Quick Start (Docker)
+
+**Get started in under 5 minutes!** See [DOCKER_QUICK_START.md](DOCKER_QUICK_START.md) for the complete guide.
+
+Requirements: Docker and Docker Compose.
+
+1) Copy the repo locally and start the stack:
+
+```bash
+docker-compose up -d --build
+```
+
+2) Initialize the database schema (single SQL file):
+
+```bash
+docker exec -i easystream-db mysql -u easystream -peasystream easystream < __install/easystream.sql
+```
+
+3) Access your platform:
+- **Main Site**: http://localhost:8083
+- **Admin Panel**: http://localhost:8083/admin_login.php (admin/admin123)
+- **Settings**: http://localhost:8083/admin_settings.php
+
+4) Configure everything via the admin panel - **no code changes required!**
+
+For detailed installation instructions, see [DOCKER_QUICK_START.md](DOCKER_QUICK_START.md).
+For settings configuration, see [SETTINGS_GUIDE.md](SETTINGS_GUIDE.md).
+
+## What’s Inside
+
+Core entry points
+- `index.php`: main frontend controller (routing, notifications, actions) (index.php:1)
+- `f_core/config.core.php`: bootstraps config, autoload, DB, session, security, logging (f_core/config.core.php:1)
+- `f_core/config.database.php`: DB connector via env vars (f_core/config.database.php:1)
+- `f_core/config.logging.php`: logging and alert configuration (f_core/config.logging.php:1)
+- `api/`: lightweight API utilities (Telegram, auto‑posting) (api/config.php:1)
+
+Key subsystems
+- Security: `VSecurity` helpers and safe wrappers in `f_core/f_functions/functions.security.php` (f_core/f_classes/class.security.php:1, f_core/f_functions/functions.security.php:1)
+- Database: `VDatabase` on top of ADOdb; prepared queries/validation (f_core/f_classes/class.database.php:1)
+- Logging: `VLogger` and `VErrorHandler`, file rotation, alerting, admin log viewer (f_core/f_classes/class.logger.php:1, f_core/f_classes/class.errorhandler.php:1, f_modules/m_backend/log_viewer.php:1)
+- IP + Fingerprint: tracking and ban management (f_core/f_classes/class.iptracker.php:1, f_core/f_classes/class.fingerprint.php:1, f_modules/m_backend/ip_management.php:1, f_modules/m_backend/fingerprint_management.php:1)
+- Templates: Smarty configuration (f_core/config.smarty.php:1)
+- Live Streaming: SRS RTMP/HLS (`deploy/srs.conf`), HLS published to shared volumes
+
+Third‑party vendor libs
+- ADOdb, Smarty, AWS SDK (S3 et al.), Google client, Zend Uri/Validate (see `f_core/f_classes` and vendor‑like trees in repo)
+
+## Directory Structure
+
+- `__install/` – SQL schema, upgrade scripts, install docs
+- `api/` – integration endpoints (Telegram bot and autopost)
+- `deploy/` – infra configs (SRS, cron scripts, SQL seeders)
+- `f_core/` – framework core: configs, autoload, classes, functions
+- `f_modules/` – feature modules; includes backend admin utilities
+- `f_scripts/` – auxiliary scripts and assets
+- `f_data/` – runtime data (logs, cache, sitemaps, user files, sessions)
+- Public root – entrypoints, PWA assets (`index.js`, `sw.js`, favicons)
+
+## Configuration
+
+Application
+- Main URL: set `MAIN_URL` or edit `f_core/config.set.php` (f_core/config.set.php:1)
+- Theme/Smarty: configured in `f_core/config.smarty.php` (f_core/config.smarty.php:1)
+
+Database
+- Configure via env: `DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASS` (f_core/config.database.php:1)
+- ADOdb cache dir is set from configs (f_core/config.core.php:29)
+
+Logging
+- Toggle file/database logging, levels, rotation, alerts (f_core/config.logging.php:1)
+- Files stored under `f_data/logs/`
+- Admin UI for viewing/clearing logs: `f_modules/m_backend/log_viewer.php` (requires backend access)
+
+Security
+- Central API: `VSecurity` for input validation, escaping, CSRF, rate limiting (f_core/f_classes/class.security.php:1)
+- Convenience wrappers: `functions.security.php` (get_param, post_param, csrf_field, validate_csrf, etc.) (f_core/f_functions/functions.security.php:1)
+- Strict autoload maps key classes by name to file (f_core/config.autoload.php:1)
+
+Live Streaming
+- SRS config at `deploy/srs.conf` (HLS fragments to `/srs/hls`; DVR to `/srs/rec`) (deploy/srs.conf:1)
+- Docker volumes expose HLS as read‑only to web tier (docker-compose.yml:1)
+
+API Integrations
+- `api/telegram.php` – Telegram Bot webhook handler (api/telegram.php:1)
+- `api/auto_post.php` – cron‑driven autopost of new videos/streams to Telegram channels (api/auto_post.php:1)
+- `api/config.php` – tokens/channels and rate limits (api/config.php:1)
+
+PWA/Frontend Enhancements
+- `index.js` – service worker registration, Android/iOS install prompts (index.js:1)
+- `sw.js` – simple cache for `index.js`, skip caching uploads/HLS requests (sw.js:1)
+
+## Security Model
+
+- Input validation: Use `VSecurity::getParam/postParam/validateInput` to sanitize all request data. Types supported include `int`, `email`, `url`, `alpha`, `alphanum`, `slug`, `filename`, `boolean`.
+- CSRF protection: Embed `csrf_field('action')` in forms and validate with `validate_csrf('action')`.
+- Output escaping: Use `secure_output` for HTML and `secure_js` for JavaScript contexts.
+- File upload validation: `validate_file_upload($file, $allowedTypes, $maxSize)` inspects MIME and size.
+- Rate limiting: `check_rate_limit($key, $maxAttempts, $windowSeconds)` stores attempt windows in session.
+- IP tracking/bans: `VIPTracker::logActivity`, `VIPTracker::banIP/unbanIP/isBanned` with geo hints and stats.
+- Browser fingerprinting: `VFingerprint::generateFingerprint/trackFingerprint/ban/unban/isBanned` for evasive users.
+
+See examples:
+- `example_secure_form.php` – CSRF, rate limit, validated inputs, and safe upload
+- `example_enhanced_logging.php` – application/security/performance logging
+
+## Logging & Observability
+
+- Central logger: `VLogger` with levels EMERGENCY→DEBUG + global request context and backtraces; file rotation and optional DB sinks (f_core/f_classes/class.logger.php:1)
+- Global error handler: `VErrorHandler` captures PHP errors/exceptions/shutdown fatals and renders user‑friendly responses depending on `debug_mode` (f_core/f_classes/class.errorhandler.php:1)
+- Configurable alerting (email) and retention (f_core/config.logging.php:1)
+- Admin Log Viewer (`f_modules/m_backend/log_viewer.php`) with level/limit filters and clear‑all action
+
+## Admin Utilities
+
+- Fingerprint Management: lookup stats, detect threats, ban/unban (`f_modules/m_backend/fingerprint_management.php`)
+- IP Management: banlist maintenance, activity review (`f_modules/m_backend/ip_management.php`)
+- Log Viewer: browse/clear logs (`f_modules/m_backend/log_viewer.php`)
+
+Backend access control is enforced; ensure you are logged in as an admin before invoking these scripts directly.
+
+## Development Notes
+
+- Autoloading: `spl_autoload_register` resolves class names like `VSecurity`, `VLogger`, `VErrorHandler` to files under `f_core/f_classes/` (f_core/config.autoload.php:1). Avoid namespace collisions with bundled vendor libs (Google, Zend, AWS, etc.).
+- Database: Prefer `VDatabase` methods which validate table/field names and bind parameters. Do not construct ad‑hoc SQL strings without validation.
+- Templates: Smarty is configured with template/cache directories from `cfg` and exposes common URLs to templates (f_core/config.smarty.php:1).
+- Configuration: Read via `$class_database->getConfigurations(...)` and `cfg` array; environment variables override DB where applicable.
+
+## Manual Installation (Non‑Docker)
+
+Summary (see `__install/INSTALL.txt` for full details):
+1) Upload files to your web root.
+2) Create a MariaDB/MySQL database; import `__install/easystream.sql.gz` and the `updatedb_*.sql`/`deploy/init_settings.sql` scripts.
+3) Edit `f_core/config.database.php` and `f_core/config.set.php`.
+4) Set writable permissions on `f_data/` subfolders as noted in `INSTALL.txt`.
+5) Configure your web server (Apache/Nginx/Caddy) to serve the repository root; PHP‑FPM 8.2+ recommended.
+6) Configure cron jobs for conversions, expirations, dashboards, and housekeeping as listed in `INSTALL.txt`.
+
+## Live Streaming
+
+- Push RTMP to `rtmp://<host>:1935/live/<stream_key>` (SRS). HLS is written to the `rtmp_hls` volume and served by Caddy as static content; DVR records to `rtmp_rec`.
+- SRS parameters (HLS fragment/window, DVR layout) in `deploy/srs.conf`.
+- For ABR (multi‑rendition) examples, see `deploy/abr.sh` and the `abr` service.
+
+### HLS Permissions & Health
+
+- Ensure the SRS container can write to the mounted HLS and recordings volumes and Caddy/PHP can read them:
+  - `rtmp_hls` → writable by SRS, readable by Caddy (served at `/hls/*`).
+  - `rtmp_rec` → writable by SRS, readable by PHP/cron for VOD processing.
+- If you bind host directories, align ownership/permissions (commonly UID/GID 0 in SRS image; Caddy runs as `caddy` user). Use `chown`/`chmod` on host paths accordingly.
+- Quick HLS check: once streaming, an HLS playlist should appear at `/hls/<app>/<stream_key>/index.m3u8`.
+
+## API: Telegram
+
+- Configure `api/config.php` with your Telegram `bot_token` and `channel_id`.
+- Webhook handler: `api/telegram.php` supports commands like `/start`, `/videos`, `/search`.
+- Autopost script: `api/auto_post.php` queries recent videos/streams and posts to the configured channel; run via cron or the `cron` service.
+
+## PWA Hints
+
+- `index.js` registers `sw.js` and provides install prompts on mobile; `sw.js` implements minimal caching and avoids caching uploads/HLS.
+
+## Development Notes
+
+- Run full test suite: `composer test`
+- Lint PHP syntax locally (fast): `composer lint`
+- CI runs syntax/style checks and publishes coverage artifacts.
+
+## Documentation
+
+### Essential Guides (Start Here!)
+- **[DOCKER_QUICK_START.md](DOCKER_QUICK_START.md)** - Get started in 5 minutes with Docker
+- **[SETTINGS_GUIDE.md](SETTINGS_GUIDE.md)** - Configure your platform without code changes
+- **[EASYSTREAM_API_DOCUMENTATION.md](EASYSTREAM_API_DOCUMENTATION.md)** - Complete API reference
+- **[CLEANUP_GUIDE.md](CLEANUP_GUIDE.md)** - Clean up workspace for production
+- **[COMPLIANCE.md](COMPLIANCE.md)** - Legal and compliance information
+
+### Installation & Setup
+- **[__install/INSTALL.txt](__install/INSTALL.txt)** - Manual installation instructions
+- **[__install/TECHNOTES.txt](__install/TECHNOTES.txt)** - Technical implementation details
+- **[__install/install_settings_system.sql](__install/install_settings_system.sql)** - Settings system installation
+
+### Advanced Documentation (If Available)
+- **[docs/PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md)** - Complete project overview (if exists)
+- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture (if exists)
+- **[docs/SECURITY.md](docs/SECURITY.md)** - Security implementation (if exists)
+- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development workflows (if exists)
+
+## Troubleshooting
+
+- White screen or 500s: check `f_data/logs/*` and the admin log viewer.
+- DB connection errors: validate env vars and connectivity (f_core/f_classes/class.database.php).
+- Permissions: ensure `f_data/` directories are writable per `__install/INSTALL.txt`.
+- Live not working: verify SRS is running and HLS path mounted to Caddy; inspect `deploy/srs.conf` and container logs.
+- Telegram autopost: ensure valid token/channel and outbound network access from the PHP/cron containers.
+
+For detailed troubleshooting, see the [Deployment Guide](docs/DEPLOYMENT.md#troubleshooting).
+
+## Quick Links
+
+- **🚀 [Get Started in 5 Minutes](DOCKER_QUICK_START.md)** - Docker quick start guide
+- **⚙️ [Configure Your Platform](SETTINGS_GUIDE.md)** - Settings system guide (no code required!)
+- **📡 [API Reference](EASYSTREAM_API_DOCUMENTATION.md)** - Complete API documentation
+- **🧹 [Clean Up Workspace](CLEANUP_GUIDE.md)** - Production-ready workspace cleanup
+- **📖 [Advanced Docs](docs/)** - Complete documentation suite (if available)
+
+## License
+
+This project is distributed under the EasyStream Proprietary License. See `LICENSE.txt`.