# 4o66/jellyfin-plugin-additional-material architecture

> Architecture diagram of the GitHub repository 4o66/jellyfin-plugin-additional-material, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/4o66/jellyfin-plugin-additional-material
- Repository: https://github.com/4o66/jellyfin-plugin-additional-material
- Video tour (about a minute): https://gitdiagram.com/4o66/jellyfin-plugin-additional-material/video

## Overview

Additional Material is a Jellyfin plugin that exposes matching ZIP archives as downloadable course, section, and lesson material. The main workflow runs from the web client through the plugin API, which locates an archive and serves its contents or a short-lived signed download. Separately, optional archive building plans and writes archives from library files; an external helper script offers a similar workflow. The graph includes README-documented web and configuration capabilities, but source excerpts are partial, so some internal links are omitted where call ownership is not shown.

Main entry points: [`src/Jellyfin.Plugin.AdditionalMaterial/Api/AdditionalMaterialController.cs`](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Api/AdditionalMaterialController.cs) (Material API), [`src/Jellyfin.Plugin.AdditionalMaterial/Services/MaterialIndex.cs`](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/MaterialIndex.cs) (Folder index), [`src/Jellyfin.Plugin.AdditionalMaterial/Planning/ArchiveWriter.cs`](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Planning/ArchiveWriter.cs) (Archive writer), [`src/Jellyfin.Plugin.AdditionalMaterial/Services/Building.cs`](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/Building.cs) (Archive builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Web client script"]
end

subgraph group_runtime["Plugin API"]
  node_api["Material API"]
  node_contents["Archive contents<br/>[ArchiveContents.cs]"]
  node_signer["Signed links<br/>[LinkSigner.cs]"]
end

subgraph group_discovery["Material discovery"]
  node_locator["Material locator<br/>[MaterialLocator.cs]"]
  node_index["Folder index<br/>[MaterialIndex.cs]"]
  node_refresh["Index refresh task"]
  node_startup["Startup indexing"]
  node_watcher["Course watcher"]
end

subgraph group_building["Archive building"]
  node_builder["Archive builder<br/>[Building.cs]"]
  node_planner["Archive planner<br/>[Planner.cs]"]
  node_active["Active content scan<br/>[ActiveContent.cs]"]
  node_writer["Archive writer<br/>[ArchiveWriter.cs]"]
  node_rules["Packaging rules<br/>[Rules.cs]"]
  node_python["Archive helper"]
end

subgraph group_admin["Configuration and integration"]
  node_config["Plugin settings"]
  node_plugin["Plugin registration<br/>[Plugin.cs]"]
  node_injection["Web injection task"]
end

node_user(("Jellyfin user"))

node_user -->|"uses"| node_web
node_web -->|"requests material"| node_api
node_api -->|"locates archive"| node_locator
node_api -->|"lists files"| node_contents
node_api -->|"signs downloads"| node_signer
node_api -->|"refreshes status"| node_index
node_api -->|"rebuilds archives"| node_writer
node_contents -->|"uses index"| node_index
node_locator -->|"checks folders"| node_index
node_builder -->|"plans archives"| node_planner
node_builder -->|"writes archives"| node_writer
node_builder -->|"updates index"| node_index
node_planner -->|"scans files"| node_active
node_writer -->|"checks content"| node_active
node_writer -->|"applies rules"| node_rules
node_watcher -->|"refreshes folders"| node_index
node_startup -.->|"initializes index"| node_index
node_refresh -.->|"refreshes index"| node_index
node_python -.->|"uses rule files"| node_rules
node_config -->|"configures plugin"| node_plugin
node_plugin -.->|"registers web task"| node_injection
node_injection -.->|"injects button"| node_web

click node_web "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Web/additional-material.js"
click node_api "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Api/AdditionalMaterialController.cs"
click node_contents "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/ArchiveContents.cs"
click node_signer "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/LinkSigner.cs"
click node_locator "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/MaterialLocator.cs"
click node_index "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/MaterialIndex.cs"
click node_refresh "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/IndexRefreshTask.cs"
click node_startup "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/FreshIndexStartupFilter.cs"
click node_watcher "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/NewCourseWatcher.cs"
click node_builder "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/Building.cs"
click node_planner "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Planning/Planner.cs"
click node_active "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Planning/ActiveContent.cs"
click node_writer "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Planning/ArchiveWriter.cs"
click node_rules "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Planning/Rules.cs"
click node_python "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/tools/make_additional_material.py"
click node_config "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Configuration/PluginConfiguration.cs"
click node_plugin "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Plugin.cs"
click node_injection "https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/WebInjectionTask.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_user toneBlue
class node_api,node_contents,node_signer toneAmber
class node_locator,node_index,node_refresh,node_startup,node_watcher toneMint
class node_builder,node_planner,node_active,node_writer,node_rules,node_python toneRose
class node_config,node_plugin,node_injection toneIndigo
```

## Components

### Web client

- [Web client script](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Web/additional-material.js): `src/Jellyfin.Plugin.AdditionalMaterial/Web/additional-material.js`

### Plugin API

- [Material API](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Api/AdditionalMaterialController.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Api/AdditionalMaterialController.cs`
- [Archive contents](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/ArchiveContents.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Services/ArchiveContents.cs`
- [Signed links](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/LinkSigner.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Services/LinkSigner.cs`

### Material discovery

- [Material locator](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/MaterialLocator.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Services/MaterialLocator.cs`
- [Folder index](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/MaterialIndex.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Services/MaterialIndex.cs`
- [Index refresh task](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/IndexRefreshTask.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Services/IndexRefreshTask.cs`
- [Startup indexing](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/FreshIndexStartupFilter.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Services/FreshIndexStartupFilter.cs`
- [Course watcher](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/NewCourseWatcher.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Services/NewCourseWatcher.cs`

### Archive building

- [Archive builder](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/Building.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Services/Building.cs`
- [Archive planner](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Planning/Planner.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Planning/Planner.cs`
- [Active content scan](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Planning/ActiveContent.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Planning/ActiveContent.cs`
- [Archive writer](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Planning/ArchiveWriter.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Planning/ArchiveWriter.cs`
- [Packaging rules](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Planning/Rules.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Planning/Rules.cs`
- [Archive helper](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/tools/make_additional_material.py): `tools/make_additional_material.py`

### Configuration and integration

- [Plugin settings](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Configuration/PluginConfiguration.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Configuration/PluginConfiguration.cs`
- [Plugin registration](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Plugin.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Plugin.cs`
- [Web injection task](https://github.com/4o66/jellyfin-plugin-additional-material/blob/main/src/Jellyfin.Plugin.AdditionalMaterial/Services/WebInjectionTask.cs): `src/Jellyfin.Plugin.AdditionalMaterial/Services/WebInjectionTask.cs`

### Other components

- **Jellyfin user**

## Connections

- Jellyfin user → Web client script: uses (evidence: `README.md`)
- Web client script → Material API: requests material (evidence: `README.md`)
- Material API → Material locator: locates archive (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Api/AdditionalMaterialController.cs`)
- Material API → Archive contents: lists files (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Api/AdditionalMaterialController.cs`)
- Material API → Signed links: signs downloads (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Api/AdditionalMaterialController.cs`)
- Material API → Folder index: refreshes status (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Api/AdditionalMaterialController.cs`)
- Material API → Archive writer: rebuilds archives (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Api/AdditionalMaterialController.cs`)
- Archive contents → Folder index: uses index (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Services/ArchiveContents.cs`)
- Material locator → Folder index: checks folders (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Services/MaterialLocator.cs`)
- Archive builder → Archive planner: plans archives (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Services/Building.cs`)
- Archive builder → Archive writer: writes archives (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Services/Building.cs`)
- Archive builder → Folder index: updates index (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Services/Building.cs`)
- Archive planner → Active content scan: scans files (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Planning/Planner.cs`)
- Archive writer → Active content scan: checks content (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Planning/ArchiveWriter.cs`)
- Archive writer → Packaging rules: applies rules (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Planning/ArchiveWriter.cs`)
- Course watcher → Folder index: refreshes folders (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Services/NewCourseWatcher.cs`)
- Startup indexing → Folder index: initializes index
- Index refresh task → Folder index: refreshes index
- Archive helper → Packaging rules: uses rule files
- Plugin settings → Plugin registration: configures plugin (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Configuration/PluginConfiguration.cs`)
- Plugin registration → Web injection task: registers web task (evidence: `src/Jellyfin.Plugin.AdditionalMaterial/Services/WebInjectionTask.cs`)
- Web injection task → Web client script: injects button
