---
auto_generated: true
created: 2026-05-19
manual_updated_at: 2026-05-19
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- client/loreal
- domain/security
- tech/azure-ad
- tech/nextjs
- tech/python
- type/sop
type: sop
---

# L'Oréal OMG Assistant Global - Developer Manual

## Architecture Overview

The application is a PHP-based web interface interacting with external APIs (Box, Make.com, OMG, Mailgun) and local storage for logs. It uses a multi-page or SPA-like structure driven by JavaScript for asynchronous operations.

- **Backend**: PHP (implied by `validate-box.php` and standard web practices).
- **Frontend**: Vanilla JavaScript (`js/app.js`, `js/global-to-local.js`) and HTML/CSS.
- **Authentication**: Azure AD SSO (handled at the infrastructure/Nginx/PHP level).
- **Storage**: Local JSON file for activity logs; Temporary storage for uploaded CSVs and generated ZIPs.

## Tech Stack

- **Language**: PHP (Server-side logic), JavaScript (Client-side interactivity).
- **APIs**: 
  - Box API (Folder validation, metadata extraction).
  - Make.com Webhooks (Data submission).
  - OMG API (Business unit lookup).
  - Mailgun (Email notifications).
- **Frontend**: DOM manipulation, Fetch API, Drag & Drop API.

## Local Setup

1. **Prerequisites**:
   - PHP 7.4+ or PHP 8.x with `curl`, `json`, and `zip` extensions enabled.
   - Web Server (Apache/Nginx) with PHP module.
   - Microsoft Azure AD Tenant with Registered App (for SSO).
   - Box Developer Account (for API keys).
   - Make.com Account (for webhook URLs).
   - Mailgun Account (for SMTP/API keys).

2. **Clone and Configure**:
   ```bash
   git clone <repository-url>
   cd loreal-omg-assistant
   composer install # If dependencies are managed via Composer
   ```

3. **Environment Variables**:
   Create a `.env` file in the root directory:
   ```env
   # Azure AD
   AZURE_CLIENT_ID=your_client_id
   AZURE_CLIENT_SECRET=your_client_secret
   AZURE_TENANT_ID=your_tenant_id

   # Box
   BOX_CLIENT_ID=your_box_client_id
   BOX_CLIENT_SECRET=your_box_client_secret
   BOX_ENTERPRISE_ID=your_enterprise_id

   # Make.com
   MAKE_WEBHOOK_URL=https://hook.make.com/your_endpoint

   # OMG API
   OMG_API_ENDPOINT=https://api.example.com/omg
   OMG_API_KEY=your_omg_key

   # Mailgun
   MAILGUN_DOMAIN=your_domain
   MAILGUN_API_KEY=your_mailgun_key

   # Application
   LOG_FILE_PATH=/path/to/logs/activity.json
   DEBUG_MODE=true/false
   ```

4. **Permissions**:
   - Ensure the web server user has write access to the `logs/` directory for JSON log files.
   - Ensure the upload directory is writable for CSV processing.

## Key Services & Entry Points

### 1. Box Asset Submission (`js/app.js`)
- **Entry Point**: `handleLookupClick()`
- **Flow**: 
  1. User enters Box ID.
  2. `validate-box.php` is called via `fetch`.
  3. Backend validates folder structure (`SUPPLIED_ASSETS` exists).
  4. Returns metadata (Campaign Number, Folder Tree).
  5. Frontend renders preview and enables submit.
- **Submission**: Form submit triggers webhook to Make.com.

### 2. CSV Transformation (`js/global-to-local.js`)
- **Entry Point**: `handleFormSubmit()`
- **Flow**:
  1. File uploaded via Drag/Drop or Input.
  2. `fetch` to backend processing endpoint.
  3. Backend parses CSV, validates schema, runs 6-stage process:
     - Stage 1: File Validation
     - Stage 2: Date Parsing (+1 Month)
     - Stage 3: OMG API Lookup (Business Unit)
     - Stage 4: Regional Formatting
     - Stage 5: CSV Generation (16 ISO codes)
     - Stage 6: Zip Creation
  4. Response includes file URLs for preview/download.

### 3. Activity Logging
- **Service**: Centralized logger class/function.
- **Data Stored**: Timestamp, User (Azure AD ID), IP, User Agent, Action Type, Status, Input Data (sanitized).
- **Storage**: JSON file. Append-only mode recommended for performance.

## API Reference

### Backend Endpoints (Implied)

#### POST `/validate-box.php`
- **Purpose**: Validate Box Folder ID and extract metadata.
- **Input**: `{ "boxId": "string" }`
- **Output**: 
  ```json
  {
    "success": true,
    "data": {
      "folderName": "string",
      "campaignNumber": "string",
      "structure": "array",
      "isValid": true
    }
  }
  ```

#### POST `/process-csv.php` (Implied)
- **Purpose**: Handle CSV upload and transformation.
- **Input**: Multipart form data (CSV File).
- **Output**: 
  ```json
  {
    "success": true,
    "files": [
      { "code": "en-GB", "url": "/tmp/en-GB.csv" },
      { "code": "es-ES", "url": "/tmp/es-ES.csv" }
    ],
    "zipUrl": "/tmp/all_markets.zip"
  }
  ```

#### GET `/logs.php`
- **Purpose**: Retrieve activity logs.
- **Parameters**: `?filter=action&value=submit&start=2023-01-01&end=2023-12-31`
- **Output**: JSON array of log entries.

## Deployment

1. **Server Requirements**:
   - Linux/Windows Server with PHP 8+
   - HTTPS enabled (required for Azure AD SSO and secure API calls).
   - Cron job for log rotation (optional but recommended).

2. **Steps**:
   - Deploy codebase to web root.
   - Set `APP_ENV=production` in `.env`.
   - Disable debug mode.
   - Configure Azure AD Redirect URIs to match the production domain.
   - Test Box API credentials in production environment.
   - Verify Mailgun webhook endpoints.

3. **CI/CD**:
   - Recommended to run PHP linting (`php -l`) and JavaScript validation (`eslint`) in pre-commit hooks.

## Known Gotchas

1. **Box API Rate Limits**: 
   - Box API has strict rate limits. If validation fails intermittently, implement retry logic or cache valid folder metadata.

2. **CSV Encoding**: 
   - Ensure source CSVs are UTF-8 encoded. Non-UTF-8 files will cause parsing errors in Stage 3.

3. **Date Timezones**: 
   - The "add 1 month" logic relies on server timezone. Ensure server timezone is set to UTC or the business’s primary timezone to avoid offset errors.

4. **Azure AD Session**: 
   - SSO tokens expire. Ensure the backend handles session renewal gracefully or redirects to login if the token is invalid.

5. **Large Files**: 
   - PHP `max_execution_time` and `upload_max_filesize` may need tuning for large global CSVs. Adjust in `php.ini` if necessary.

6. **Make.com Webhooks**: 
   - Make.com webhooks may have a timeout. Ensure the submission endpoint returns a 200 OK quickly and processes asynchronously if the payload is large.

## Related
- [[01 Projects/baic_dashboard/DEVELOPER_MANUAL.md]]