# cedev-1/jellyfin-plugin-getavatar architecture

> Architecture diagram of the GitHub repository cedev-1/jellyfin-plugin-getavatar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cedev-1/jellyfin-plugin-getavatar
- Repository: https://github.com/cedev-1/jellyfin-plugin-getavatar

## Overview

GetAvatar is a Jellyfin server plugin for browsing and assigning gallery avatars. Users select an image through the injected profile UI or client API; the controller delegates assignment to avatar services that persist gallery files and Jellyfin profile images. Administrators manage the gallery and settings, with separate import branches for online packs, Gravatar, and Immich album/user-picture synchronization. The graph follows documented capabilities and sampled calls; unsampled UI/API wiring is shown only where README or source-index evidence supports it.

Main entry points: [`Jellyfin.Plugin.GetAvatar/Services/AvatarService.cs`](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/AvatarService.cs) (Gallery and assignment), [`Jellyfin.Plugin.GetAvatar/Controllers/AvatarController.cs`](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Controllers/AvatarController.cs) (Avatar API), [`Jellyfin.Plugin.GetAvatar/Configuration/Web`](https://github.com/cedev-1/jellyfin-plugin-getavatar/tree/main/Jellyfin.Plugin.GetAvatar/Configuration/Web) (Profile and admin UI), [`Jellyfin.Plugin.GetAvatar/Services/ImmichService.cs`](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/ImmichService.cs) (Immich API service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Jellyfin entry points"]
  node_controller["Avatar API"]
  node_webui["Profile and admin UI<br/>[Web]"]
  node_injector["Script injection"]
end

subgraph group_gallery["Avatar gallery"]
  node_avatar["Gallery and assignment<br/>[AvatarService.cs]"]
  node_gallerydata[("Avatar files and mappings<br/>[AvatarInfo.cs]")]
  node_validation["Startup repair"]
end

subgraph group_imports["Avatar sources"]
  node_online["Online pack import"]
  node_gravatar["Gravatar download<br/>[GravatarService.cs]"]
  node_gravatarsvc["Gravatar service<br/>[GravatarService.cs]"]
end

subgraph group_immich["Immich integration"]
  node_immich["Immich API service<br/>[ImmichService.cs]"]
  node_immichserver["Immich server"]
end

subgraph group_runtime["Configuration and lifecycle"]
  node_config[("Plugin configuration")]
  node_plugin["Plugin registration<br/>[Plugin.cs]"]
  node_created["New-user assignment"]
end

node_user(("Jellyfin users"))
node_admin(("Jellyfin admins"))
node_clients(("Jellyfin clients"))
node_jellyfin["Jellyfin server"]

node_user -->|"opens picker"| node_webui
node_clients -->|"calls API"| node_controller
node_admin -->|"manages gallery"| node_webui
node_webui -.->|"requests actions"| node_controller
node_jellyfin -->|"runs middleware"| node_injector
node_injector -->|"injects picker"| node_webui
node_controller -->|"delegates avatar work"| node_avatar
node_controller -->|"imports packs"| node_online
node_controller -->|"requests download"| node_gravatar
node_controller -->|"routes sync actions"| node_immich
node_online -->|"saves imported images"| node_avatar
node_gravatarsvc -->|"downloads image"| node_gravatar
node_immich -->|"fetches albums and pictures"| node_immichserver
node_immich -->|"imports and sets pictures"| node_avatar
node_avatar -->|"stores gallery metadata"| node_gallerydata
node_avatar -->|"updates user profiles"| node_jellyfin
node_avatar -->|"reads and saves mappings"| node_config
node_validation -->|"repairs profile images"| node_avatar
node_controller -.->|"updates settings"| node_config
node_plugin -->|"owns configuration"| node_config
node_created -->|"assigns new-user avatar"| node_avatar
node_plugin -->|"registers pages"| node_webui

click node_controller "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Controllers/AvatarController.cs"
click node_webui "https://github.com/cedev-1/jellyfin-plugin-getavatar/tree/main/Jellyfin.Plugin.GetAvatar/Configuration/Web"
click node_injector "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/ScriptInjectorMiddleware.cs"
click node_avatar "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/AvatarService.cs"
click node_gallerydata "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Configuration/AvatarInfo.cs"
click node_validation "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/AvatarValidationService.cs"
click node_online "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/OnlinePackService.cs"
click node_gravatar "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/GravatarService.cs"
click node_gravatarsvc "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/GravatarService.cs"
click node_immich "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/ImmichService.cs"
click node_config "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Configuration/PluginConfiguration.cs"
click node_plugin "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Plugin.cs"
click node_created "https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/UserCreatedAvatarConsumer.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_controller,node_webui,node_injector,node_user,node_clients toneBlue
class node_avatar,node_gallerydata,node_validation toneAmber
class node_online,node_gravatar,node_gravatarsvc,node_jellyfin toneMint
class node_immich,node_immichserver toneRose
class node_config,node_plugin,node_created,node_admin toneIndigo
```

## Components

### Jellyfin entry points

- [Avatar API](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Controllers/AvatarController.cs): `Jellyfin.Plugin.GetAvatar/Controllers/AvatarController.cs`
- [Profile and admin UI](https://github.com/cedev-1/jellyfin-plugin-getavatar/tree/main/Jellyfin.Plugin.GetAvatar/Configuration/Web): `Jellyfin.Plugin.GetAvatar/Configuration/Web`
- [Script injection](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/ScriptInjectorMiddleware.cs): `Jellyfin.Plugin.GetAvatar/ScriptInjectorMiddleware.cs`

### Avatar gallery

- [Gallery and assignment](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/AvatarService.cs): `Jellyfin.Plugin.GetAvatar/Services/AvatarService.cs`
- [Avatar files and mappings](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Configuration/AvatarInfo.cs): `Jellyfin.Plugin.GetAvatar/Configuration/AvatarInfo.cs`
- [Startup repair](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/AvatarValidationService.cs): `Jellyfin.Plugin.GetAvatar/AvatarValidationService.cs`

### Avatar sources

- [Online pack import](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/OnlinePackService.cs): `Jellyfin.Plugin.GetAvatar/Services/OnlinePackService.cs`
- [Gravatar download](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/GravatarService.cs): `Jellyfin.Plugin.GetAvatar/Services/GravatarService.cs`
- [Gravatar service](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/GravatarService.cs): `Jellyfin.Plugin.GetAvatar/Services/GravatarService.cs`

### Immich integration

- [Immich API service](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/ImmichService.cs): `Jellyfin.Plugin.GetAvatar/Services/ImmichService.cs`
- **Immich server**

### Configuration and lifecycle

- [Plugin configuration](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Configuration/PluginConfiguration.cs): `Jellyfin.Plugin.GetAvatar/Configuration/PluginConfiguration.cs`
- [Plugin registration](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Plugin.cs): `Jellyfin.Plugin.GetAvatar/Plugin.cs`
- [New-user assignment](https://github.com/cedev-1/jellyfin-plugin-getavatar/blob/main/Jellyfin.Plugin.GetAvatar/Services/UserCreatedAvatarConsumer.cs): `Jellyfin.Plugin.GetAvatar/Services/UserCreatedAvatarConsumer.cs`

### Other components

- **Jellyfin users**
- **Jellyfin admins**
- **Jellyfin clients**
- **Jellyfin server**

## Connections

- Jellyfin users → Profile and admin UI: opens picker (evidence: `README.md`)
- Jellyfin clients → Avatar API: calls API (evidence: `README.md`)
- Jellyfin admins → Profile and admin UI: manages gallery (evidence: `README.md`)
- Profile and admin UI → Avatar API: requests actions
- Jellyfin server → Script injection: runs middleware
- Script injection → Profile and admin UI: injects picker (evidence: `Jellyfin.Plugin.GetAvatar/ScriptInjectorMiddleware.cs`)
- Avatar API → Gallery and assignment: delegates avatar work (evidence: `Jellyfin.Plugin.GetAvatar/Controllers/AvatarController.cs`)
- Avatar API → Online pack import: imports packs (evidence: `Jellyfin.Plugin.GetAvatar/Controllers/AvatarController.cs`)
- Avatar API → Gravatar download: requests download (evidence: `Jellyfin.Plugin.GetAvatar/Controllers/AvatarController.cs`)
- Avatar API → Immich API service: routes sync actions (evidence: `Jellyfin.Plugin.GetAvatar/Controllers/AvatarController.cs`)
- Online pack import → Gallery and assignment: saves imported images (evidence: `Jellyfin.Plugin.GetAvatar/Services/OnlinePackService.cs`)
- Gravatar service → Gravatar download: downloads image (evidence: `Jellyfin.Plugin.GetAvatar/Services/GravatarService.cs`)
- Immich API service → Immich server: fetches albums and pictures (evidence: `Jellyfin.Plugin.GetAvatar/Services/ImmichService.cs`)
- Immich API service → Gallery and assignment: imports and sets pictures (evidence: `Jellyfin.Plugin.GetAvatar/Services/ImmichService.cs`)
- Gallery and assignment → Avatar files and mappings: stores gallery metadata (evidence: `Jellyfin.Plugin.GetAvatar/Services/AvatarService.cs`)
- Gallery and assignment → Jellyfin server: updates user profiles (evidence: `Jellyfin.Plugin.GetAvatar/Services/AvatarService.cs`)
- Gallery and assignment → Plugin configuration: reads and saves mappings (evidence: `Jellyfin.Plugin.GetAvatar/Services/AvatarService.cs`)
- Startup repair → Gallery and assignment: repairs profile images (evidence: `Jellyfin.Plugin.GetAvatar/AvatarValidationService.cs`)
- Avatar API → Plugin configuration: updates settings
- Plugin registration → Plugin configuration: owns configuration (evidence: `Jellyfin.Plugin.GetAvatar/Plugin.cs`)
- New-user assignment → Gallery and assignment: assigns new-user avatar (evidence: `Jellyfin.Plugin.GetAvatar/Services/UserCreatedAvatarConsumer.cs`)
- Plugin registration → Profile and admin UI: registers pages (evidence: `Jellyfin.Plugin.GetAvatar/Plugin.cs`)
