---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- client/oliver
- domain/security
- status/active
- tech/node
- type/sop
type: sop
---

# Ferrero AC Booking Tool - Developer Manual

## Architecture Overview

The application follows a dual-mode architecture:
1. **Client-Side (Standalone):** `index.html` contains all UI and logic required for data entry, row manipulation, and CSV generation. This allows the tool to function without a backend.
2. **Server-Side (Optional):** `server.js` provides HTTP services for authentication and remote file storage (Box folder integration via OMG API). It exposes a REST-like API for login, logout, and file upload.

The server acts as a proxy for authenticated actions but does not store the core booking logic, which resides in the client.

## Tech Stack

- **Backend:** Node.js (Native `http` module).
- **Frontend:** Vanilla HTML5, CSS3, JavaScript (ES6+).
- **Authentication:** Cookie-based session management (in-memory `Map`).
- **Data Format:** CSV generation via client-side JavaScript.

## Local Setup

### Prerequisites
- Node.js installed.
- A modern web browser.

### Installation Steps

1. Clone or navigate to the project directory:
   ```bash
   cd /Users/pauljohns/Documents/Claude_Coding/Ferrero_OMG_Booking
   ```

2. Start the server:
   ```bash
   node server.js
   ```

3. Access the application:
   - For full features: Open **http://localhost:3456**.
   - For CSV download only: Open `index.html` directly.

## Environment Variables

The server respects the following environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `BASE_PATH` | Base URL path for routing (e.g., `/booking`) | `''` |
| `OMG_OUTPUT_DIR` | Directory where CSV files are temporarily stored before upload | `/tmp/omg_output` |
| `CREDENTIALS_EMAIL` | *Note: Currently hardcoded in `server.js` as `PaulJohns@oliver.agency`* | N/A |
| `CREDENTIALS_PASSWORD` | *Note: Currently hardcoded in `server.js` as `PassW0rd123`* | N/A |

> **Security Note:** The current credentials are hardcoded. For production use, move these to environment variables or a secure secrets manager.

## Key Services & Entry Points

### `server.js`

- **Entry Point:** `http.createServer()` listener.
- **Authentication:**
  - `POST /login`: Validates credentials, creates a session ID, sets `fac_session` cookie.
  - `GET /logout`: Invalidates session and clears cookie.
  - `isAuthenticated(req)`: Helper to check for valid session cookies.
- **Session Management:**
  - `sessions`: An in-memory `Map` storing active sessions.
  - `generateSessionId()`: Creates a random hex string using `crypto.randomBytes`.
- **File Handling:**
  - Serves static files (`index.html`, CSS, JS) with correct MIME types.
  - Handles CSV upload for "Send to OMG" feature (implementation details truncated in README but implied).

### `index.html` (Client-Side Logic)

- **AC Generator:** Manages the input table, including row addition, duplication, and deletion.
- **Analyse Engine:** Computes output columns (`Title`, `Status`, `Category`) based on input fields.
- **CSV Generator:** Constructs the CSV string and triggers a browser download.
- **OMG Integrator:** Makes AJAX/fetch requests to the server to upload CSVs.

## API Reference

### Authentication

#### POST /login
- **Content-Type:** `application/x-www-form-urlencoded`
- **Body:** `email=...&password=...`
- **Response:**
  - `200 OK`: Redirect to `/` with `Set-Cookie` header.
  - `302 Found`: Redirect to `/login?error=1` if credentials are invalid.

#### GET /logout
- **Response:**
  - `302 Found`: Redirect to `/login` with cleared `fac_session` cookie.

### File Operations

#### POST /upload (Implied)
- **Function:** Uploads CSV to Box folder.
- **Requires:** Valid `fac_session` cookie.
- **Details:** Specific implementation details are not fully visible in the provided snippet, but it likely writes to `OMG_OUTPUT_DIR` and then interacts with Box SDK/API.

## Deployment

### Production Considerations

1. **Security:**
   - Replace hardcoded credentials with environment variables.
   - Implement HTTPS.
   - Move from in-memory sessions to a persistent store (Redis, Database) to survive server restarts and support load balancing.
   - Add rate limiting to `/login`.

2. **File Storage:**
   - Ensure `OMG_OUTPUT_DIR` is writable and has sufficient disk space.
   - Configure proper Box API integration for the upload step.

3. **Process Management:**
   - Use a process manager like `pm2` or `systemd` to keep the Node.js server running.

### Example PM2 Startup
```bash
pm2 start server.js --name "ferrero-booking"
```

## Known Gotchas

1. **No Backend Validation:** Client-side validation is minimal. Ensure input data integrity before calling "Analyse".
2. **Session Expiry:** In-memory sessions do not expire automatically. Implement a cleanup interval to remove old sessions.
3. **Hardcoded Credentials:** The current `server.js` has hardcoded credentials. This is a critical security risk in any non-local environment.
4. **CSV Format Changes:** The OMG import format is hardcoded in the client. If OMG changes its schema, the client CSV generator must be updated.
5. **Local Path Dependency:** The README example uses an absolute local path (`/Users/pauljohns/...`). Ensure deployment instructions use relative paths or configurable directories.

## Related
- [[01 Projects/ferrero-ac-creator/USER_MANUAL]]
- [[Ferrero Booking Tool]]
- [[OMG API Integration]]
- [[01 Projects/ferrero-ac-creator/USER_MANUAL.md]]