# QDR Temporary Shared Storage - Plugin Structure

## Directory Structure

```
qdr-temporary-shared-storage/
├── qdr-temporary-shared-storage.php       # Main plugin file (bootstrap)
├── uninstall.php                          # Clean uninstallation
│
├── includes/                              # Core functionality
│   ├── class-qdr-tss.php                  # Core plugin class
│   ├── class-qdr-tss-activator.php        # Plugin activation
│   ├── class-qdr-tss-deactivator.php      # Plugin deactivation
│   ├── class-qdr-tss-db-manager.php       # Database operations
│   ├── class-qdr-tss-file-manager.php     # File operations
│   ├── class-qdr-tss-settings.php         # Settings management
│   ├── class-qdr-tss-cron-manager.php     # Scheduled tasks
│   ├── class-qdr-tss-loader.php           # Hook loader (registers all hooks)
│   ├── class-qdr-tss-i18n.php             # Internationalization
│   └── functions.php                      # Helper functions
│
├── admin/                                 # Admin-related functionality
│   ├── class-qdr-tss-admin.php            # Admin controller
│   ├── class-qdr-tss-media-page.php       # Media page UI and AJAX handlers
│   ├── class-qdr-tss-settings-page.php    # Settings page UI and AJAX handlers
│   ├── partials/                          # Admin UI templates
│   │   ├── media-page.php                 # Media listing page template
│   │   └── settings-page.php              # Settings page template
│   ├── js/
│   │   └── admin.js                       # Admin JavaScript (pagination, sorting, modals)
│   └── css/
│       └── admin.css                      # Admin styles (table, modals, buttons)
│
├── public/                                # Public-facing functionality
│   ├── class-qdr-tss-public.php           # Public controller
│   ├── class-qdr-tss-shortcode.php        # Shortcode functionality
│   ├── class-qdr-tss-download.php         # Download functionality
│   ├── js/
│   │   └── public.js                      # Public JavaScript
│   └── css/
│       └── public.css                     # Public styles
│
├── rest-api/                              # REST API functionality
│   ├── class-qdr-tss-rest-controller.php  # REST API base controller
│   ├── class-qdr-tss-media-controller.php # Media endpoints
│   └── class-qdr-tss-upload-controller.php# Upload endpoints
│
├── languages/                             # Translation files
│   ├── qdr-temporary-shared-storage.pot   # Translation template
│   └── qdr-temporary-shared-storage-cs_CZ.po # Czech translation
│
└── docs/                                  # Documentation
    ├── integration-guide.md               # Integration guide
    ├── plugin-structure.md                # Plugin structure documentation
    ├── rest-api-docs.md                   # REST API documentation
    ├── testing-guide.md                   # Testing guide
    └── readme.md                          # Complete plugin documentation
```

## Class Responsibilities

### Core Classes

#### QDR_TSS (Main Plugin Class)
- Initialize the plugin
- Load dependencies
- Register hooks for admin, public, REST API, and cron functionality
- Define plugin-wide constants
- Load translations

#### QDR_TSS_Activator
- Handle plugin activation
- Create database tables with proper schema
- Create file system directories and security files
- Set default options including API key generation
- Create download page with shortcode
- Schedule cron job for cleanup
- Add rewrite rules for pretty URLs

#### QDR_TSS_Deactivator
- Handle plugin deactivation
- Clear scheduled cron jobs
- Flush rewrite rules

#### QDR_TSS_Loader
- Register actions and filters
- Orchestrate all hooks for the plugin

#### QDR_TSS_i18n
- Load text domain
- Enable internationalization

#### QDR_TSS_DB_Manager (Singleton)
- Create/update custom tables with proper indexes
- Database queries for media items with pagination and filtering
- CRUD operations for media items
- Storage size calculations and limit checks
- Handle expired items cleanup
- Support for fileid-based operations

#### QDR_TSS_File_Manager (Singleton)
- Handle file operations and chunked uploads
- Generate unique file IDs
- Create dated directory structures
- Manage chunked upload process (init, store chunks, finalize)
- Delete files and cleanup empty directories
- File system initialization with security

#### QDR_TSS_Settings (Singleton)
- Get/set plugin settings
- Settings validation
- Default settings management
- API key generation and validation
- Storage management settings

#### QDR_TSS_Cron_Manager
- Register and manage cron schedules
- Handle expired files cleanup (both files and database records)
- Manual purge functionality
- Automatic cleanup of empty directories

### Admin Classes

#### QDR_TSS_Admin
- Register admin menu items in Media and Settings
- Enqueue admin scripts/styles with proper dependencies
- Handle localization for JavaScript
- Initialize admin hooks

#### QDR_TSS_Media_Page
- Handle AJAX requests for media operations:
  - Get items with pagination, sorting, and filtering
  - Edit item properties
  - Delete items
  - Get item details for modals
  - **NEW: Force activate functionality** - Reset active period starting from current time
- Pagination and search functionality
- File management operations

#### QDR_TSS_Settings_Page
- Handle AJAX requests for settings operations:
  - Save plugin settings
  - Manual purge of expired files
- Settings validation and management

### Public Classes

#### QDR_TSS_Public
- Register public scripts/styles
- Handle rewrite rules for pretty download URLs
- Create download page if missing
- Manage query variables for file downloads

#### QDR_TSS_Shortcode
- Register and handle `[qdr_tss_download]` shortcode
- Support for both specific file ID and generic download form

#### QDR_TSS_Download
- Handle download requests with password and reference verification
- Verify file accessibility (active dates)
- Process file downloads with proper headers
- Update download statistics (count and last download time)
- Support for both URL parameter and shortcode-based downloads

### REST API Classes

#### QDR_TSS_REST_Controller
- Base REST API functionality and authentication
- API key validation via X-Api-Key header
- Permissions management for all endpoints

#### QDR_TSS_Media_Controller
- REST endpoints for media management:
  - `GET /media` - List media with pagination and filtering
  - `GET /media/{fileid}` - Get specific media details
  - `PUT /media/{fileid}` - Update media properties
  - `DELETE /media/{fileid}` - Delete media
- Proper error handling and response formatting
- Security: passwords are excluded from API responses

#### QDR_TSS_Upload_Controller
- REST endpoints for chunked file uploads:
  - `POST /upload/init` - Initialize chunked upload
  - `POST /upload/chunk` - Upload individual chunks
  - `POST /upload/finalize` - Combine chunks and create media record
- File validation and storage limit checks
- Proper cleanup of temporary files

## Key Features and Changes

### Database Schema Updates
- **fileid**: Changed from `media_id` to `fileid` for better clarity
- Proper indexes on commonly queried fields
- Support for tracking download statistics

### Admin Interface Enhancements
- **New Action Buttons**: 
  - Copy Permalink button with direct clipboard functionality
  - Force Activate button to reset active period
- **Improved UI**: Better responsive design and modern styling
- **Enhanced Search**: Filter by filename and reference
- **Better Modals**: Improved modal system for viewing and editing

### File Management Improvements
- **Unique File ID Generation**: Improved algorithm using timestamp and random data
- **Chunked Upload Support**: Complete implementation for large files
- **Storage Management**: Automatic cleanup and size tracking
- **Security**: Protected file storage with .htaccess rules

### REST API Enhancements
- **Consistent Naming**: Uses `fileid` instead of `media_id` throughout
- **Better Error Handling**: Standardized error responses
- **Security**: API key authentication for all endpoints
- **File Operations**: Complete CRUD operations via REST API

### Cron and Cleanup
- **Automatic Cleanup**: Hourly cron job to remove expired files
- **Manual Purge**: Admin interface button for immediate cleanup
- **Directory Cleanup**: Removes empty directories after file deletion

### Internationalization
- **Complete Translation Support**: All user-facing strings are translatable
- **Czech Translation**: Included as example
- **Proper Text Domains**: Consistent use throughout the plugin

## File Dependencies

Here's the updated dependency tree:

1. **qdr-temporary-shared-storage.php** - Loads:
   - class-qdr-tss-activator.php
   - class-qdr-tss-deactivator.php
   - class-qdr-tss.php

2. **class-qdr-tss.php** - Loads all core components:
   - class-qdr-tss-loader.php
   - class-qdr-tss-i18n.php
   - class-qdr-tss-db-manager.php
   - class-qdr-tss-file-manager.php
   - class-qdr-tss-settings.php
   - class-qdr-tss-cron-manager.php
   - functions.php
   - Admin classes (admin.php, media-page.php, settings-page.php)
   - Public classes (public.php, shortcode.php, download.php)
   - REST API classes (rest-controller.php, media-controller.php, upload-controller.php)

3. **class-qdr-tss-admin.php** - Enqueues:
   - admin/css/admin.css
   - admin/js/admin.js (with jQuery UI datepicker)
   - Localized JavaScript with translations

4. **class-qdr-tss-public.php** - Enqueues:
   - public/css/public.css
   - public/js/public.js

## Security Considerations

### File Storage Security
- Files stored in protected directory with .htaccess rules
- No direct file access - all downloads go through WordPress
- Automatic cleanup of expired files

### API Security
- API key authentication required for all REST endpoints
- Proper nonce verification for admin AJAX requests
- Input sanitization and validation throughout

### Download Security
- Password protection for all downloads
- Optional reference codes for additional security
- Time-based access control (active from/to dates)
- Download tracking for audit purposes

## Performance Optimizations

### Database
- Proper indexing on frequently queried columns
- Pagination for large datasets
- Efficient queries for file listing and search

### File Operations
- Chunked uploads for large files
- Temporary file cleanup
- Efficient storage usage tracking

### Admin Interface
- AJAX-based operations for better user experience
- Client-side pagination and sorting
- Lazy loading of file details

This structure provides a robust, secure, and user-friendly system for temporary file sharing with complete WordPress integration and comprehensive REST API support.