---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- tech/azure-ad
- tech/docker
- tech/google-gemini
- tech/indexeddb
- tech/php
- tech/react
- tech/tailwind
- tech/vite
- type/project
type: project
---

# Developer Manual: Lux Studio (Cinema Studio Pro)

## Architecture Overview

Lux Studio is a single-page application (SPA) with a hybrid backend for file management and API proxying.

- **Frontend:** React 19 app built with Vite, styled with Tailwind CSS. Handles all UI state, IndexedDB storage, and AI API interactions.
- **Backend:** Lightweight PHP 7.4+ Apache application. Handles authentication proxying, file uploads/downloads, video streaming, and session management.
- **Storage:** 
  - **Client-side:** IndexedDB for project metadata and asset data (base64/images).
  - **Server-side:** Session files for temporary uploads and large video storage, auto-cleaned every 24 hours.

## Tech Stack

| Layer | Technology |
|-------|------------|
| **Frontend** | React 19, Vite, Tailwind CSS, Lucide-React (Icons), MSAL React (Auth) |
| **Backend** | PHP 7.4+, Apache, Composer |
| **AI** | Google Gemini API (Imagen 3 for images, Veo 3.1 for videos) |
| **Auth** | @azure/msal-browser + @azure/msal-react (Optional Azure AD SSO) |
| **Database** | IndexedDB (Dexie.js or native API) |
| **Containerization** | Docker/Docker Compose |

## Local Setup

### Prerequisites
- Node.js 18+
- PHP 7.4+
- Composer
- Google Gemini API Key

### Step 1: Backend Setup
1. Install PHP dependencies:
   ```bash
   cd backend
   composer install
   ```
2. Create `.env` file in `backend/` with your Google API key:
   ```env
   GEMINI_API_KEY=your_google_api_key_here
   ```
3. Start the PHP built-in server:
   ```bash
   php -S localhost:5015 -t api/
   ```

### Step 2: Frontend Setup
1. Install dependencies:
   ```bash
   cd frontend
   npm install
   ```
2. Create `.env` file in `frontend/`:
   ```env
   VITE_API_URL=http://localhost:5015
   # Optional: Azure AD Config if SSO is enabled
   # VITE_MSA_CLIENT_ID=...
   # VITE_MSA_TENANT_ID=...
   ```
3. Start the Vite dev server:
   ```bash
   npm run dev
   ```
   The frontend will proxy API requests to `localhost:5015` automatically.

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `GEMINI_API_KEY` | Google AI Studio API Key for Imagen/Veo access | Yes (Backend) |
| `VITE_API_URL` | Backend API URL for production | Yes (Frontend) |
| `VITE_MSA_CLIENT_ID` | Azure AD Client ID for SSO | No |
| `VITE_MSA_TENANT_ID` | Azure AD Tenant ID for SSO | No |

## Key Services & Entry Points

### Frontend Components
- **`frontend/src/main.jsx`**: Entry point. Initializes MSAL instance before mounting the React tree. Handles SSO configuration.
- **`frontend/src/App.jsx`**: Root component wrapper. Delegates to `AppContent`.
- **`frontend/src/components/ProjectsTab.jsx`**: Core workspace UI. Manages project lifecycle (create, delete, rename) and asset display.
- **`frontend/src/components/VideoGenTab.jsx`**: UI for video generation settings and status. Handles Kling/Veo engine selection.
- **`frontend/src/components/VideoPlayer.jsx`**: Custom video player with frame extraction capabilities. Handles URL conversion for streaming videos via backend.
- **`frontend/src/components/AdminSettings.jsx`**: Admin panel for managing Kling API keys and testing connectivity.

### Backend API Endpoints
- **`admin_api.php?action=status`**: Returns current Kling service status.
- **`admin_api.php?action=test_kling`**: Tests Kling API keys (POST with `access_key` and `secret_key`).
- **`admin_api.php?action=update_kling`**: Saves Kling API credentials.
- **`stream_video.php?file=<filename>`**: Streams video files from the uploads directory.
- **`/api/imagen/generate`**: (Proxy) Sends image generation requests to Google Imagen 3.
- **`/api/veo/generate`**: (Proxy) Sends video generation requests to Google Veo 3.1.

## Deployment

### Docker Production Build
Use `docker-compose.prod.yml` to deploy:
1. Ensure `backend/.env.optical` contains valid environment variables.
2. Run:
   ```bash
   docker-compose -f docker-compose.prod.yml up -d
   ```
3. The app will be available at `http://127.0.0.1:8085`.

### CI/CD Notes
- Frontend build outputs to `dist/`.
- Backend PHP files are served directly.
- Ensure `uploads` volume is persisted if long-term video storage is needed (currently auto-cleaned).

## Known Gotchas

1. **MSAL Initialization:** MSAL v3 must be fully initialized (`await msalInstance.initialize()`) before rendering components that use `useMsal()`. This is handled in `main.jsx`.
2. **Video Streaming:** The frontend converts `/generated_videos/` paths to backend stream URLs. Ensure the backend `uploads` directory is writable and the filename encoding matches.
3. **CORS:** During local development, use the Vite proxy (`/api/*` -> `localhost:5015`) to avoid CORS issues with the PHP backend.
4. **IndexedDB Limits:** Storing large base64 images/videos in IndexedDB can exceed quota limits. The app should implement chunking or offloading to the backend for large assets in production.
5. **Kling Integration:** The Kling workflow is optional. Ensure `klingWorkflow` state in `VideoGenTab.jsx` defaults correctly if Kling is not configured in `AdminSettings`.

## Related
- [[01 Projects/cinema-studio-pro/DEVELOPER_MANUAL]]
- [[01 Projects/cinema-studio-pro/DEVELOPER_MANUAL.md]]
- [[01 Projects/cinema-studio-pro-kling/DEVELOPER_MANUAL.md]]
- [[01 Projects/cinema-studio-pro-kling/USER_MANUAL.md]]