# Modules & Templates Management

# Modules & Templates Management

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [.env](.env)
- [.windsurfrules](.windsurfrules)
- [pnpm-lock.yaml](pnpm-lock.yaml)
- [src/hooks.server.ts](src/hooks.server.ts)
- [src/routes/(app)/system/settings/modules/+page.svelte](src/routes/(app)/system/settings/modules/+page.svelte)
- [src/routes/(app)/system/settings/templates/+page.svelte](src/routes/(app)/system/settings/templates/+page.svelte)

</details>



The Modules and Templates management pages provide administrative interfaces for extending system functionality and managing document/communication assets. These pages are located within the system settings route group and utilize Svelte 5 runes for reactive state management.

## 1. Modules Management

The Modules page allows administrators to upload new feature packages (in `.zip` or `.tar.gz` formats) and manage the lifecycle of installed extensions.

### 1.1 Implementation Details
The module management interface is implemented in `src/routes/(app)/system/settings/modules/+page.svelte`. It uses a local `$state` array to track installed modules and their current statuses (e.g., `active`, `inactive`).

**Key State Variables:**
- `uploadedFile`: A `$state<File | null>` representing the file currently selected in the input [src/routes/(app)/system/settings/modules/+page.svelte:11-11]().
- `installedModules`: A `$state` array containing objects with `id`, `name`, `version`, and `status` properties [src/routes/(app)/system/settings/modules/+page.svelte:13-17]().

### 1.2 Module Lifecycle Actions
The current implementation contains logic for UI interactions, with backend integration marked as TODO stubs:

| Action | Function | Logic |
| :--- | :--- | :--- |
| **Selection** | `handleFileUpload` | Captures the `File` object from the `HTMLInputElement` [src/routes/(app)/system/settings/modules/+page.svelte:19-24](). |
| **Installation** | `handleInstall` | Placeholder for sending the binary data to the backend API [src/routes/(app)/system/settings/modules/+page.svelte:26-32](). |
| **Deletion** | `handleDeleteModule` | Placeholder for the `DELETE` request to remove a module by ID [src/routes/(app)/system/settings/modules/+page.svelte:34-37](). |

### 1.3 Data Flow: Module Upload
This diagram illustrates the transition from the UI file input to the (planned) API interaction.

**Module Upload Flow**
```mermaid
graph TD
    UI["Input[type=file]"] -- "onchange" --> HFU["handleFileUpload()"]
    HFU -- "Update $state" --> UF["uploadedFile"]
    UF -- "Render" --> UB["Install Button"]
    UB -- "onclick" --> HI["handleInstall()"]
    HI -- "TODO: POST /api/v1/modules" --> BE["Backend API"]
```

**Sources:**
- [src/routes/(app)/system/settings/modules/+page.svelte:1-95]()
- [src/hooks.server.ts:37-57]() (API proxying logic)

---

## 2. Templates Management

The Templates page provides a centralized repository for managing various document formats, including PDF, Email (HTML), Excel, and raw HTML templates.

### 2.1 Template Types
The system categorizes templates into four primary types, each associated with a specific Lucide icon and file extension [src/routes/(app)/system/settings/templates/+page.svelte:25-30]():

| Type | Icon | Extensions |
| :--- | :--- | :--- |
| **PDF** | `FileText` | `.pdf` |
| **Email** | `Mail` | `.html` |
| **Excel** | `FileSpreadsheet` | `.xlsx`, `.xls` |
| **HTML** | `Code2` | `.html` |

### 2.2 Reactive Filtering
The interface utilizes Svelte 5's `$derived` rune to filter the list of templates based on the currently selected category. This ensures that only relevant templates are displayed to the user at one time [src/routes/(app)/system/settings/templates/+page.svelte:57-57]().

### 2.3 Management Functions
The page includes the following management capabilities [src/routes/(app)/system/settings/templates/+page.svelte:39-55]():
- **Upload**: `handleUpload()` processes the selected template file.
- **Download**: `handleDownloadTemplate()` triggers a fetch for the template binary.
- **Delete**: `handleDeleteTemplate()` removes the template entry.
- **Create**: A placeholder "Create Template" button exists for manual template definition [src/routes/(app)/system/settings/templates/+page.svelte:108-109]().

### 2.4 Code Entity Mapping
The following diagram maps UI interactions to the reactive state and component logic.

**Template Management Architecture**
```mermaid
graph LR
    subgraph "State Management"
        ST["selectedType ($state)"]
        T["templates ($state)"]
        FT["filteredTemplates ($derived)"]
    end

    subgraph "Components"
        TYP["Template Type Selector"]
        LST["Templates List"]
        UP["Upload Section"]
    end

    TYP -- "sets" --> ST
    ST -- "triggers" --> FT
    T -- "source for" --> FT
    FT -- "renders in" --> LST
    UP -- "updates" --> T
```

**Sources:**
- [src/routes/(app)/system/settings/templates/+page.svelte:1-135]()

---

## 3. Integration & Backend Connectivity

### 3.1 API Proxying
Requests from the frontend to the backend are handled via the SvelteKit `handle` hook in `src/hooks.server.ts`. This hook intercepts any request starting with `/api` and forwards it to the `PUBLIC_API_ORIGIN` defined in the environment [src/hooks.server.ts:37-57]().

### 3.2 Planned Backend Integration (TODOs)
Both the modules and templates pages currently utilize mock data and console logging for actions. The planned integration involves:
1.  **Module API**: Implementation of endpoints for multipart/form-data uploads of zip files and status toggle commands.
2.  **Template API**: Integration with a template engine on the backend to handle PDF generation and email rendering.
3.  **Error Handling**: Utilization of the global error system (RFC 7807) to display upload or deletion failures.

**Sources:**
- [src/hooks.server.ts:27-57]()
- [.env:1-1]()
- [src/routes/(app)/system/settings/modules/+page.svelte:28-28]()
- [src/routes/(app)/system/settings/templates/+page.svelte:41-41]()

---