---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: Developer_Manual
status: active
tags:
- client/dowjones
- tech/gemini
- tech/javascript
- type/reference
type: reference
---

# Developer Manual: Dow Jones Job Naming Tool

## Architecture Overview

The application is a client-side heavy web application using `jspreadsheet` for the UI grid and vanilla JavaScript for logic. It interacts with a backend PHP API (`api.php`) for data persistence and an external AI service (Google Gemini) for natural language processing. The architecture follows a simple MVC-like pattern where:

- **Model**: `spreadsheet` object (jspreadsheet instance) and `api.php`.
- **View**: DOM elements rendered via HTML/CSS (not shown) and `jspreadsheet` components.
- **Controller**: `script.js` handles initialization, event listeners, data fetching, and business logic.

## Tech Stack

- **Frontend**: Vanilla JavaScript, HTML, CSS.
- **Library**: `jspreadsheet` (for the interactive grid).
- **Backend**: PHP (`api.php`).
- **AI Integration**: Google Gemini API (client-side or proxied).

## Local Setup

1. **Prerequisites**:
   - A web server with PHP support (e.g., XAMPP, MAMP, or Apache/Nginx with PHP-FPM).
   - Node.js (if building dependencies, though this appears to be vanilla JS).
   - Access to the Google Gemini API key (if used client-side).

2. **Installation**:
   - Clone the repository.
   - Ensure `api.php` is present in the root directory.
   - Ensure `script.js` is included in the main HTML file.
   - Ensure `jspreadsheet` and `jsuites` libraries are referenced in the HTML.

3. **Environment Variables**:
   - Although not explicitly shown in the code, `api.php` likely requires:
     - `GEMINI_API_KEY`: For AI command processing.
     - Database credentials (MySQL/MariaDB) for `load` and `save` actions.

## Key Services & Entry Points

### 1. Initialization (`DOMContentLoaded`)

- **Entry Point**: `script.js` executes immediately upon DOM load.
- **Actions**:
  - Initializes `jspreadsheet` instance (`spreadsheet`).
  - Fetches initial data via `fetch('api.php?action=load&t=' + Date.now())`.
  - Checks URL parameters for `builder=1` mode to pre-populate a new row.

### 2. Data Loading (`loadData`)

- **Function**: `async function loadData()`
- **Flow**:
  - Shows loading overlay.
  - Fetches JSON data from backend.
  - Calls `initSpreadsheet(rawData)`.
  - If `?builder=1` is in URL, extracts params (`OMGID`, `Domain`, etc.), creates a new row at index 0, and updates the filename.
  - Updates all filenames if data exists.

### 3. Spreadsheet Initialization (`initSpreadsheet`)

- **Function**: `function initSpreadsheet(data)`
- **Flow**:
  - Destroys existing `spreadsheet` instance if it exists.
  - Initializes new `jspreadsheet` with `data`.
  - (Note: The snippet cuts off here, but likely sets up column types, dropdowns, and event listeners for cell changes).

### 4. Filename Generation

- **Logic**: When a row is updated, `updateFilenameForRow(row)` is called.
- **Rules**:
  - If `Domain === 'EVNT'`: `[OMGID] - EVNT-[Event]-[YY]-[Seq]_[Asset]_v[Ver]`
  - Else: `[OMGID] - [Domain]-[Subteam]-[Brand]-[Initiative]-[YY]-[Seq]_[Asset]_v[Ver]`

## API Reference

### `api.php`

- **Action: `load`**
  - **Method**: GET/POST
  - **Description**: Retrieves all job records.
  - **Params**: `t` (timestamp to prevent caching).
  - **Response**: JSON array of objects.

- **Action: `save`** (Implied by `saveData()`)
  - **Method**: POST
  - **Description**: Saves spreadsheet data to the database.
  - **Body**: JSON string of the spreadsheet data.

## Deployment

1. **Backend**: Deploy `api.php` and database schema to a PHP-supported server.
2. **Frontend**: Deploy static files (`index.html`, `script.js`, CSS, libraries) to a web server.
3. **CORS**: If frontend and backend are on different domains, configure CORS headers in `api.php`.
4. **Security**: Ensure `api.php` validates inputs and uses prepared statements to prevent SQL injection. Restrict Gemini API access via server-side proxy if possible to hide API keys.

## Known Gotchas

1. **jspreadsheet Dependency**: The code relies heavily on `jspreadsheet` global variable. Ensure the library is loaded before `script.js`.
2. **URL Builder Mode**: The tool supports `?builder=1&OMGID=...` for creating jobs from external links. Ensure URL encoding is handled correctly for special characters in `AssetName` or `Initiative`.
3. **Event Domain Logic**: The naming convention changes significantly for `EVNT`. The UI must correctly hide/show `Subteam` and `Brand` dropdowns based on the `Domain` selection to prevent invalid filenames.
4. **AI Context**: The `conversationHistory` array is defined but not shown how it interacts with the Gemini API in the snippet. Ensure the AI prompt includes the current spreadsheet state if the tool supports contextual edits.
5. **Data Persistence**: `saveData()` is called implicitly. Ensure the backend API is robust enough to handle concurrent edits if multiple users are editing the same spreadsheet.
6. **Dropdown Arrays**: The constants `DOMAINS`, `SUBTEAMS`, `BRANDS`, and `EVENTS` in `script.js` should be kept in sync with the `README.md` reference tables. Consider fetching these from the backend to ensure consistency.