MediaCollectorLibary/README.md

# Media Collector

A modern PHP application to collect and manage media from various sources like Steam, Jellyfin, Stash, and XBVR.

## Features

- **Unified Dashboard**: View all your media in one place with comprehensive statistics
- **Multiple Sources**: Connect to Steam, Jellyfin, Stash, and XBVR
- **Media Types**: Manage games, movies, TV shows, and music with detailed tracking
- **Database-Driven**: Complete database schema with migrations and models
- **Rich Analytics**: Track playtime, watch counts, favorites, and sync status
- **User Authentication**: Secure login system with session management
- **Admin Panel**: Comprehensive admin interface for sync management
- **Real-time Sync**: Live progress tracking and status updates
- **Responsive Design**: Works on desktop and mobile devices
- **Modern Stack**: Built with PHP 8.1+, Slim Framework, Vue.js, and Tailwind CSS

## Authentication & Admin Features

### User Management
- **Secure Authentication**: Session-based login system with CSRF protection
- **Role-based Access**: Admin and user roles with appropriate permissions
- **Session Management**: Automatic session handling and cleanup

### Admin Panel (`/admin`)
- **Source Management**: Configure and manage media sources
- **Sync Control**: Start full or incremental syncs for each source
- **Live Status**: Real-time progress tracking and error reporting
- **Sync History**: View past sync activities and results
- **Error Monitoring**: Comprehensive error logging and debugging

## Database Schema

The application includes a comprehensive database schema supporting:

- **Games**: Steam integration, playtime tracking, completion percentages
- **Movies**: Watch status, ratings, TMDb integration
- **TV Shows & Episodes**: Season/episode tracking, watch progress
- **Music**: Artists, albums, tracks with play counts and favorites
- **Sources**: Integration management for external services
- **Sync Logs**: Synchronization tracking and error reporting
- **Users**: Authentication and role management

## Prerequisites

- PHP 8.1 or higher
- Composer (for PHP dependencies)
- Node.js 16+ and npm/yarn (for frontend assets)
- SQLite (or MySQL/PostgreSQL)

## Docker Installation (Recommended)

For the easiest setup, use Docker Compose:

### Prerequisites
- [Docker](https://docker.com/get-started)
- [Docker Compose](https://docs.docker.com/compose/install/)

### Quick Start
1. **Clone and setup**:
   ```bash
   git clone <your-repo-url>
   cd media-collector
   cp .env.example .env
   # Edit .env with your API keys
   ```

2. **Start the application**:
   ```bash
   # For production
   docker-compose up -d

   # For development (with hot-reload)
   docker-compose --profile dev up
   ```

3. **Access the application**:
   - Main app: http://localhost:8000
   - Admin panel: http://localhost:8000/admin

### Docker Commands
```bash
# View logs
docker-compose logs -f

# Stop containers
docker-compose down

# Rebuild containers
docker-compose up --build

# Access PHP container
docker-compose exec app bash

# Reset database
docker-compose down -v
docker-compose up -d
```

### Docker Architecture
- **App Container**: PHP 8.2-FPM with Composer dependencies
- **Nginx Container**: Web server for static files and reverse proxy
- **Database**: SQLite file stored in persistent volume
- **Networks**: Isolated network for container communication

## Manual Installation (Alternative)

1. Clone the repository:
   ```bash
   git clone [repository-url]
   cd media-collector
   ```

2. Install PHP dependencies:
   ```bash
   composer install
   ```

3. Install frontend dependencies:
   ```bash
   npm install
   ```

4. Copy and configure the environment file:
   ```bash
   cp .env.example .env
   ```

   Edit `.env` and configure your settings:
   ```bash
   APP_NAME="Media Collector"
   APP_ENV=local
   APP_DEBUG=true
   APP_URL=http://localhost:8000

   # Database Configuration
   DB_CONNECTION=sqlite
   DB_DATABASE=database/database.sqlite

   # Admin User Configuration (required for initial setup)
   ADMIN_USERNAME=admin
   ADMIN_EMAIL=admin@example.com
   ADMIN_PASSWORD=admin123

   # Gaming Platform APIs
   STEAM_API_KEY=your_steam_api_key_here
   EXOPHASE_API_KEY=your_exophase_api_key_here
   EXOPHASE_API_URL=https://api.exophase.com

   # Services API Keys
   JELLYFIN_API_KEY=your_jellyfin_api_key_here
   STASH_API_KEY=your_stash_api_key_here
   STASH_URL=http://localhost:9999
   XBVR_URL=http://localhost:9998
   ```

5. Set up the database (runs migrations and creates admin user):
   ```bash
   php setup.php
   ```

6. Build frontend assets:
   ```bash
   npm run dev
   # or for production:
   # npm run build
   ```

7. Start the development server:
   ```bash
   php -S localhost:8000 -t public
   ```

8. **Login to Admin Panel**:
   - Open http://localhost:8000/login
   - Use the admin credentials created during setup
   - Access the admin panel at http://localhost:8000/admin

## Development

- Frontend development (with hot-reload):
  ```bash
  npm run dev
  ```

- Building for production:
  ```bash
  npm run build
  ```

- Running tests:
  ```bash
  composer test
  ```

## Project Structure

```
media-collector/
├── app/                    # Application code
│   ├── Controllers/        # Request handlers
│   │   ├── AuthController.php     # Authentication routes
│   │   ├── AdminController.php    # Admin panel routes
│   │   ├── Controller.php         # Base controller class
│   │   └── DashboardController.php
│   ├── Database/           # Database connection and configuration
│   │   └── Database.php
│   ├── Http/               # HTTP middleware
│   │   └── Middleware/     # Authentication and admin middleware
│   ├── Models/             # Database models and ORM
│   │   ├── Model.php       # Base model class
│   │   ├── Game.php        # Game model with Steam integration
│   │   ├── Movie.php       # Movie model with TMDb integration
│   │   ├── TvShow.php      # TV show model
│   │   ├── TvEpisode.php   # TV episode model
│   │   ├── MusicArtist.php # Music artist model
│   │   ├── MusicAlbum.php  # Music album model
│   │   ├── MusicTrack.php  # Music track model
│   │   ├── Source.php      # Source integration model
│   │   ├── SyncLog.php     # Synchronization log model
│   │   └── User.php        # User authentication model
│   ├── Services/           # Business logic services
│   │   ├── AuthService.php        # Authentication service
│   │   ├── BaseSyncService.php   # Base sync service class
│   │   ├── SteamSyncService.php  # Steam API integration
│   │   ├── JellyfinSyncService.php # Jellyfin API integration
│   │   ├── StashSyncService.php   # Stash API integration
│   │   └── XbvrSyncService.php    # XBVR API integration
├── config/                 # Configuration files
│   └── database.php        # Database configuration
├── database/               # Database migrations and seeds
│   ├── migrations/         # Database migration files (11 total)
│   └── seeds/              # Database seeders
├── public/                 # Web root
│   └── index.php           # Application entry point
├── resources/
│   ├── js/                 # JavaScript files
│   │   └── app.js          # Main Vue.js application
│   ├── scss/               # Stylesheets
│   │   └── app.scss        # Main stylesheet with Tailwind CSS
│   └── views/              # Twig templates
│       ├── layouts/
│       │   └── app.twig    # Base application layout
│       ├── auth/
│       │   └── login.twig  # Login page
│       ├── dashboard/
│       │   └── index.twig  # Dashboard view
│       └── admin/
│           └── index.twig  # Admin dashboard
├── routes/                 # Application routes
│   └── web.php             # Web routes definition
├── storage/                # Logs, cache, etc.
│   └── framework/          # Framework-specific storage
├── .env                    # Environment variables
├── composer.json           # PHP dependencies
├── package.json            # Node.js dependencies
├── setup.php               # Database setup script
└── README.md
```

## API Integration

The application supports integration with:

- **Steam**: Game library, playtime, achievements
- **Jellyfin**: Movies and TV shows with metadata
- **Stash**: Adult content management
- **Exophase Integration**: Cross-platform gaming achievements and playtime tracking

Configure your API keys in the `.env` file to enable these integrations.

## Database Models

Each media type includes rich model functionality:

- **Statistics**: Total counts, averages, favorites
- **Relationships**: Proper foreign key relationships
- **Methods**: CRUD operations, special queries, formatting
- **Type Casting**: Automatic data type conversion
- **Error Handling**: Comprehensive error reporting

## Security Features

- **CSRF Protection**: All forms include CSRF tokens
- **Session Security**: Secure session handling with timeouts
- **Input Validation**: Comprehensive input sanitization
- **Role-based Access**: Admin-only routes and functionality
- **Password Hashing**: Secure password storage

## Admin Panel Usage

1. **Login**: Use admin credentials at `/login`
2. **Access Admin**: Navigate to `/admin` for the admin dashboard
3. **Source Management**: Configure your media sources
4. **Sync Operations**: Start full or incremental syncs
5. **Monitor Progress**: View real-time sync status and results
6. **View History**: Check past sync activities and errors

## License

This project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).