Copy page

Frontend

Modules & Templates Management

Modules & Templates Management

Relevant source files

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

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

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

Code
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

Code
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

---