---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: Developer_Manual
status: active
tags:
- domain/devops
- tech/azure-ad
- tech/react
- tech/typescript
type: reference
---

# LUSA Back Planner - Developer Manual

## 1. Architecture Overview
This is a client-side React SPA built with Vite. It does **not** have a backend API. All logic (SLA calculation, holiday mapping, PDF generation) runs in the browser.

*   **Entry Point:** `src/main.tsx` (implied, via Vite)
*   **State Management:** React Context (for Toasts) and Local State (for form inputs).
*   **Data Layer:** Static JSON/TS files (`src/lib/sla-data.ts`).

## 2. Tech Stack
*   **Framework:** React 18+ with TypeScript
*   **Build Tool:** Vite
*   **Styling:** Tailwind CSS + shadcn/ui components
*   **PDF Parsing:** `pdfjs-dist` (for reading uploaded briefs)
*   **PDF Export:** `jsPDF` + `html2canvas`
*   **Testing:** Vitest + React Testing Library
*   **Linting:** ESLint with `@typescript-eslint` and `react-refresh`

## 3. Local Setup

### Prerequisites
*   Node.js 18+
*   npm or pnpm

### Installation
```bash
npm install
```

### Running Development Server
```bash
npm run dev
```
*   Server runs at `http://localhost:3000` (configured in `vite.config.ts`).
*   Note: The `vite.config.ts` sets `base` to `/lusa-Back-Planner/` in production mode, but `/` in dev. Ensure your proxy/Apache config aligns if testing production builds locally.

### Running Tests
```bash
npm run test
```
*   Tests are located in `src/**/*.test.ts`.
*   Environment is `jsdom`.
*   Setup file: `src/test/setup.ts` (mocks `matchMedia` and includes `@testing-library/jest-dom`).

## 4. Environment Variables
All environment variables must use the `VITE_` prefix to be exposed to the browser.

Create a `.env` file based on `.env.example`:

| Variable | Description | Example |
| :--- | :--- | :--- |
| `VITE_AZURE_TENANT_ID` | Azure AD Tenant for Auth | `e519c2e6-bc6d-4fdf-8d9c-923c2f002385` |
| `VITE_AZURE_CLIENT_ID` | Azure AD Application Client ID | `9079054c-9620-4757-a256-23413042f1ef` |
| `VITE_AZURE_REDIRECT_URI` | OAuth Callback URL | `https://ai-sandbox.oliver.solutions/lusa-Back-Planner` |

**Note:** For local dev, you may need different Azure credentials (`15c0c4e2-bac0-4564-a3a6-c2717f00a6d9`) and a redirect URI pointing to `http://localhost:8888/lusa-Back-Planner`.

## 5. Key Services & Entry Points

### `src/lib/sla-data.ts`
Contains the core business logic data:
*   `SlaEntry`: Interface defining the SLA structure.
*   `slaData`: Array of objects mapping Complexity + Category + AssetType to Workday ranges.
*   `getContentCategoriesForComplexity()`: Helper to filter categories dynamically.

### `src/lib/workdays.ts`
Contains holiday and date calculation logic:
*   `nthWeekday()`: Helper for finding specific weekdays.
*   `lastMonday()`: Helper for week boundaries.
*   `observed()`: Handles holiday observation rules.
*   *Note: The file was truncated in the codebase. Ensure full holiday lists are defined.*

### `src/hooks/use-toast.ts`
Custom toast notification hook based on Radix UI patterns:
*   Manages a stack of toasts (`TOAST_LIMIT = 1`).
*   Uses a reducer pattern (`addToRemoveQueue`, `reducer`, `dispatch`).

### `src/components/ui/`
Contains shadcn/ui components. Import via `@/components/ui/...` (mapped via `vite.config.ts` alias `@`).

## 6. API Reference (Internal)

### `SlaEntry` Interface
```typescript
interface SlaEntry {
  complexity: string;
  contentCategory: string;
  assetType: string;
  workdaysMin: number;
  workdaysMax: number;
  roundsOfAmends: number;
  steps: {
    copyCreation: string;
    translation: string;
    claimValidation: string;
    marketValidation: string;
    visual1stDraft: string;
    productionRevisions: string;
    uploadToOpera: string;
  };
}
```

## 7. Deployment

### Build
```bash
npm run build
```
Produces static files in `dist/`.

### Apache Deployment (Ubuntu)
1.  Copy `dist/` to `/var/www/backplanner`.
2.  Configure VirtualHost (`/etc/apache2/sites-available/backplanner.conf`):
    ```apache
    <VirtualHost *:80>
        ServerName your-domain.com
        DocumentRoot /var/www/backplanner
        <Directory /var/www/backplanner>
            Options -Indexes
            AllowOverride None
            Require all granted
            FallbackResource /index.html
        </Directory>
        <FilesMatch "\.(js|css|png|jpg|ico|svg|woff2?)$">
            Header set Cache-Control "public, max-age=31536000, immutable"
        </FilesMatch>
    </VirtualHost>
    ```
3.  Enable modules and site:
    ```bash
    sudo a2enmod headers
    sudo a2ensite backplanner.conf
    sudo systemctl reload apache2
    ```
4.  (Optional) HTTPS via Certbot:
    ```bash
    sudo certbot --apache -d your-domain.com
    ```

### Subdirectory Deployment
If deploying under `your-server.com/backplanner/`:
1.  Update `vite.config.ts`:
    ```typescript
    export default defineConfig({
      base: "/backplanner/",
      // ... rest of config
    });
    ```
2.  Use Apache Alias instead of VirtualHost.

## 8. Known Gotchas
1.  **Azure Auth:** Ensure `VITE_AZURE_REDIRECT_URI` matches exactly the configured redirect in Azure Portal, including trailing slashes.
2.  **Date Calculations:** The `workdays.ts` logic assumes European/local holiday calendars. Hardcode holidays for specific regions if international support is needed.
3.  **PDF Export:** Client-side PDF generation can be memory-intensive for large DOM trees. Test with complex timelines.
4.  **Vite Base Path:** Changing `base` in `vite.config.ts` requires a full rebuild (`npm run build`) before deployment. It does not update dynamically in dev without restarting.
5.  **Shadcn UI:** Ensure `tailwind.config.ts` extends are correctly mapped to CSS variables in `src/index.css` (not shown but implied by Tailwind config).