---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- domain/ai
- tech/azure-ad
- tech/gemini
- tech/react
- tech/tailwind
- tech/vite
- type/sop
type: sop
---

# Lux Studio Developer Manual

## Architecture Overview

Lux Studio is a Single Page Application (SPA) built with React 19, leveraging Vite for fast development builds and Tailwind CSS for styling. It follows a project-first architecture where all assets (images/videos) are tied to a specific project entity managed via IndexedDB.

- **Frontend**: React 19 + Vite + Tailwind CSS.
- **State Management**: Custom hooks (`useProjects`, `useCustomPresets`) manage local state and IndexedDB interactions.
- **Authentication**: Optional Microsoft Azure AD SSO via `@azure/msal-browser` and `@azure/msal-react`.
- **Backend**: Minimal PHP backend (Apache) handles API proxying and file streaming. No separate backend service is required.
- **AI Integration**: Calls to Google Gemini API for Imagen 3 (images) and Veo 3.1 (video), and potentially Kling APIs via a custom proxy.

## Tech Stack

| Layer | Technology |
|-------|------------|
| Frontend Framework | React 19 |
| Build Tool | Vite |
| Styling | Tailwind CSS |
| State/Storage | IndexedDB (via custom hooks) |
| Auth | MSAL (Azure AD) |
| Backend | PHP 7.4+ (Apache) |
| AI Providers | Google Gemini (Imagen 3, Veo 3.1), Kling (via proxy) |

## Local Setup

### Prerequisites
- Node.js 18+
- PHP 7.4+
- Composer
- Google Gemini API Key (available at https://aistudio.google.com/app/apikey)

### Installation Steps

1. **Clone the Repository**
   ```bash
   git clone <repo-url>
   cd lux-studio
   ```

2. **Install Dependencies**
   ```bash
   npm install
   ```

3. **Configure Environment**
   Create `.env` files in the `frontend/` and `backend/` directories.
   - `frontend/.env.local`:
     ```env
     VITE_API_URL=http://localhost:5015
     VITE_GEMINI_API_KEY=your_gemini_key_here
     VITE_IS_SSO_ENABLED=false
     ```
   - `backend/.env`:
     ```env
     GEMINI_API_KEY=your_gemini_key_here
     ```

4. **Start Development Servers**
   - **Backend**: Ensure Apache is running and configured to serve the `backend/` directory. Point `VITE_API_URL` in frontend env to your Apache host (e.g., `http://localhost:5015`).
   - **Frontend**:
     ```bash
     npm run dev
     ```

5. **Access the App**
   Open http://localhost:5173 in your browser.

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `VITE_API_URL` | Backend URL for proxying API calls | Yes |
| `VITE_GEMINI_API_KEY` | Google Gemini API Key | Yes |
| `VITE_IS_SSO_ENABLED` | Toggle Azure AD SSO (`true`/`false`) | No |

## Key Services & Entry Points

### 1. Authentication (`frontend/src/authConfig.js`)
- Manages MSAL configuration.
- `isSSOEnabled()` checks environment variables.
- Initialization occurs in `main.jsx` before React render.

### 2. Data Persistence (`frontend/src/hooks/useProjects.js`)
- Handles all IndexedDB interactions.
- Exports methods: `createProject`, `deleteProject`, `addItemToProject`, `exportProject`, etc.
- No server-side database; pure client-side storage.

### 3. AI Integration
- **Image Generation**: Uses Google Imagen 3 via Gemini API. Logic resides in components calling the backend proxy.
- **Video Generation**: Uses Veo 3.1 or Kling. The `VideoGenTab` component handles complex state for model selection, prompt optimization, and task polling.

### 4. Video Playback (`frontend/src/components/VideoPlayer.jsx`)
- Custom video player with frame extraction capabilities.
- Handles URL conversion for streaming via `stream_video.php`.
- Uses canvas to extract frames as PNGs.

## API Reference

The backend PHP scripts act as a proxy to AI providers and handle file management.

### Streaming Videos
- **Endpoint**: `/stream_video.php?file=<filename>`
- **Description**: Streams video files from the `generated_videos/` directory.
- **Method**: GET

### Generating Content
- **Endpoint**: `/api/generate_image.php` or `/api/generate_video.php`
- **Description**: Proxies requests to Google/Kling APIs.
- **Method**: POST
- **Payload**: JSON object containing prompt, model type, aspect ratio, and reference images.

### Storyboard Export
- **Endpoint**: `/api/export_storyboard.php`
- **Description**: Generates a PDF from storyboard data.
- **Method**: POST

## Deployment

1. **Production Build**:
   ```bash
   npm run build
   ```
2. **Configure Backend**: Ensure Apache is configured to serve the `backend/` directory and proxy requests to Google APIs securely.
3. **Environment**: Set `VITE_IS_SSO_ENABLED=true` in production `.env` if using Azure AD.
4. **Hosting**: Deploy the `dist/` folder to a static host and the `backend/` folder to an Apache server.

## Known Gotchas

1. **CORS**: In development, use the Vite proxy. In production, ensure the backend handles CORS headers correctly for AI API requests.
2. **IndexedDB Limits**: Browser storage quotas may apply. Large projects with many high-res videos might hit limits. Encourage users to download assets regularly.
3. **MSAL Initialization**: MSAL must be initialized before React renders. The `main.jsx` async wrapper handles this, but errors here will crash the app.
4. **Video Formats**: The `VideoPlayer` component assumes standard MP4/MKV formats. Unsupported codecs may fail to play or extract frames.
5. **AI Latency**: Video generation can take several minutes. Ensure the UI shows clear loading states and does not timeout prematurely.

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