# Contributing to EasyStream

Thank you for your interest in contributing to EasyStream! This document provides guidelines and information for contributors.

## Development Setup

### Prerequisites
- Docker and Docker Compose
- PHP 8.2+ (for local development)
- Node.js (for frontend assets)
- Git

### Quick Start
1. Clone the repository
2. Copy `.env.example` to `.env` and configure
3. Run `docker-compose up -d --build`
4. Access the application at `http://localhost:8083`

## Project Structure

### Core Directories
- `f_core/` - Framework core (classes, functions, configs)
- `f_modules/` - Feature modules (frontend/backend)
- `f_templates/` - Smarty templates
- `f_data/` - Runtime data (logs, cache, uploads)
- `f_jobs/` - Background job classes
- `api/` - API endpoints
- `tests/` - Test suites

### Key Files
- `index.php` - Main application entry point
- `docker-compose.yml` - Container orchestration
- `Caddyfile` - Web server configuration
- `deploy/srs.conf` - Live streaming server config

## Development Guidelines

### Code Standards
- Follow PSR-12 coding standards for PHP
- Use meaningful variable and function names
- Add PHPDoc comments for all classes and methods
- Validate all user inputs using `VSecurity` class
- Use prepared statements for database queries

### Security Best Practices
- Always use `VSecurity::getParam()` and `VSecurity::postParam()` for input
- Implement CSRF protection with `csrf_field()` and `validate_csrf()`
- Escape output with `secure_output()` and `secure_js()`
- Use rate limiting for sensitive operations
- Log security events with `VLogger`

### Database Guidelines
- Use `VDatabase` class for all database operations
- Validate table and field names
- Use parameter binding for queries
- Follow the existing schema patterns

### Testing
- Write unit tests for new functionality
- Use PHPUnit for testing
- Run tests with `./run-tests.sh`
- Ensure all tests pass before submitting PRs

## Feature Development

### Adding New Features
1. Create a spec in `.kiro/specs/feature-name/`
2. Write requirements, design, and tasks
3. Implement following the task list
4. Add appropriate tests
5. Update documentation

### Live Streaming Features
- Use SRS for RTMP/HLS streaming
- HLS files are served from `/hls/` endpoint
- DVR recordings stored in `/srs/rec/`
- Test streaming with OBS or similar tools

### API Development
- Follow RESTful principles
- Use proper HTTP status codes
- Implement rate limiting
- Add comprehensive error handling
- Document all endpoints

## Deployment

### Production Checklist
- Review `DEPLOYMENT-CHECKLIST.md`
- Configure environment variables
- Set up SSL certificates
- Configure backup procedures
- Monitor logs and performance

### Docker Deployment
- Use provided `docker-compose.yml`
- Configure volumes for persistent data
- Set up reverse proxy (Caddy included)
- Configure SRS for live streaming

## Troubleshooting

### Common Issues
- Check `f_data/logs/` for error logs
- Verify database connectivity
- Ensure proper file permissions
- Check Docker container logs

### Debug Mode
- Enable debug mode in configuration
- Use `VLogger` for detailed logging
- Check admin log viewer for issues

## Getting Help

### Documentation
- Read the main `README.md`
- Check `docs/API.md` for API details
- Review deployment guides in `docs/`

### Support
- Create GitHub issues for bugs
- Use discussions for questions
- Follow the issue templates

## Code Review Process

### Pull Request Guidelines
1. Create feature branch from `main`
2. Make focused, atomic commits
3. Write clear commit messages
4. Add tests for new functionality
5. Update documentation as needed
6. Ensure CI passes

### Review Criteria
- Code follows project standards
- Security best practices implemented
- Tests cover new functionality
- Documentation is updated
- No breaking changes without discussion

## License

By contributing to EasyStream, you agree that your contributions will be licensed under the same license as the project.