first commit

API_INTEGRATION.md

@@ -0,0 +1,126 @@
+# API Integration Guide
+
+This document explains how the React frontend integrates with the PHP backend API.
+
+## API Configuration
+
+### Environment Setup
+
+1. Copy `.env.example` to `.env`:
+```bash
+cp .env.example .env
+```
+
+2. Configure your API URL in `.env`:
+```env
+VITE_API_URL=http://localhost:8080/api
+```
+
+### Available API Endpoints
+
+Based on your backend routes, the following endpoints are available:
+
+#### Authentication
+- `POST /api/auth/login` - User login
+- `POST /api/auth/register` - User registration  
+- `POST /api/auth/refresh` - Refresh JWT token
+- `GET /api/auth/me` - Get current user (protected)
+
+#### Media
+- `GET /api/movies` - List movies with pagination
+- `GET /api/movies/{id}` - Get single movie
+- `GET /api/tvshows` - List TV shows with pagination
+- `GET /api/tvshows/{id}` - Get single TV show
+- `GET /api/games` - List games with pagination
+- `GET /api/games/{id}` - Get single game
+
+#### Search
+- `GET /api/search?q={query}&type={type}` - Search across media types
+
+#### System
+- `GET /api/status` - API health check
+
+### API Service Structure
+
+The frontend is organized with:
+
+1. **API Service** (`src/services/api.ts`)
+   - Axios configuration with interceptors
+   - Authentication handling
+   - Endpoint methods
+
+2. **React Hooks** (`src/hooks/useApi.ts`)
+   - React Query integration
+   - Custom hooks for each endpoint
+   - Caching and error handling
+
+3. **Updated Components**
+   - Movies page now uses `useMovies()` hook
+   - Dashboard uses `useDashboardStats()` and `useRecentActivity()`
+   - Search page uses `useSearch()` hook
+
+### Authentication Flow
+
+1. Login via `/api/auth/login`
+2. Store JWT token in localStorage
+3. Token automatically added to all requests
+4. Auto-logout on 401 responses
+
+### Pagination
+
+All list endpoints support:
+- `page` - Page number (default: 1)
+- `per_page` - Items per page (default: 20)
+- `search` - Search term
+- `genre` - Filter by genre
+- `year` - Filter by year
+
+### Error Handling
+
+- 401: Auto-redirect to login
+- 404: Show "not found" message
+- 500: Show generic error message
+- Network: Show connection error
+
+### Next Steps
+
+1. **Complete Backend Endpoints**: Your MediaController needs implementations for:
+   - `listMovies()` method
+   - `getMovie()` method  
+   - Dashboard stats endpoint
+   - Recent activity endpoint
+
+2. **Add Missing Features**:
+   - Music API endpoints
+   - Adult content API endpoints
+   - Actors/performers API endpoints
+   - CRUD operations (create, update, delete)
+
+3. **Testing**:
+   - Test API connectivity
+   - Test authentication flow
+   - Test error handling
+
+### Example API Response Format
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [...],
+    "pagination": {
+      "total": 100,
+      "per_page": 20,
+      "current_page": 1,
+      "last_page": 5
+    }
+  }
+}
+```
+
+### Development Notes
+
+- The frontend includes fallback mock data
+- API calls are made through React Query for caching
+- All requests include JWT authentication headers
+- CORS is configured for development