# jellyfin/jellyfin-server-windows architecture

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

- Interactive diagram: https://gitdiagram.com/jellyfin/jellyfin-server-windows
- Repository: https://github.com/jellyfin/jellyfin-server-windows

## Overview

##### Project Type and Purpose
- This is not a typical web or mobile app but a Windows-specific utility package for Jellyfin. It comprises two primary deliverables:
- A .NET-based Windows Tray application (Jellyfin.Windows.Tray) that manages a Jellyfin Server installation at runtime.
- An NSIS-based installer (nsis/…) that bundles the tray app, Jellyfin Server, branding assets, and support utilities into a Windows installer, deploying registry keys and optionally configuring the service.

##### File Structure Analysis
- Top-level solution (Jellyfin.Windows.Tray.sln) containing the C# project folder Jellyfin.Windows.Tray/ with:
- Program.cs, TrayApplicationContext.cs, RunType.cs, StringExtensions.cs
- app.manifest
- Support Files/ – third-party C code for nsProcess utility (used by NSIS scripts).
- nsis/ – installer scripts, dialogs, helpers, and the main jellyfin.nsi script.
- build-jellyfin.ps1, GitHub Actions workflows (.github/workflows), and project config (renovate.json, jellyfin.ruleset) for CI/CD and code quality.
- README.md and LICENSE at the root.

##### README Insights
- The Tray App’s responsibilities at runtime:
- Start/stop Jellyfin (service or executable)
- Open the Web UI in a browser
- Launch the log folder in Explorer
- Registry keys under HKLM\SOFTWARE\WOW6432Node\Jellyfin\Server control dataFolder, installFolder, serviceAccountType.
- The installer bundles:
- Jellyfin Server binaries (jellyfin.exe, ffmpeg, etc.)
- Tray app binaries
- NSIS UI assets from jellyfin-ux
- GPLv2 LICENSE file
- Build steps for both components are described.

##### Components
a. Runtime Components
1. User (Windows desktop)
2. Jellyfin.Windows.Tray.exe (Tray App)
3. Windows Service Control Manager
4. Windows Service "JellyfinServer" (if installed)
5. Registry (HKLM\…\Jellyfin\Server)
6. Jellyfin Server executable (jellyfin.exe)
7. Data Folder (config, database, logs)
8. Default Browser (for Web UI)
9. Windows Explorer (for Log Folder)
b. Build/Install Components
1. NSIS Compiler (makensis)
3. Support Files (nsProcess plugin)
4. Combined Server & Tray Binaries
5. Registry – Install scripts that write keys

##### Relationships and Interactions
- At install time:
- User runs the NSIS installer → NSIS script reads InstallLocation + UXPATH → Bundles and copies server, tray app, assets → Writes registry keys → Optionally registers the Windows service.
- At runtime:
- Tray App reads registry → If service exists: interacts with SCM to Start/Stop → Else: launches jellyfin.exe with command-line dataFolder arg.
- Tray App reads Data Folder network config → Opens default browser at Web UI URL.
- Tray App launches Explorer on Data Folder\Log.

##### Architectural Patterns and Key Technologies
- Patterns:
- Thin desktop “front-end” (Tray App) controlling a headless service/executable (“back-end”).
- Installer layer (NSIS) orchestrating deployment, registry configuration, service registration.
- Technologies:
- .NET 6.0 (net472) for Tray App
- Windows Service Control Manager API (via .NET ServiceController)
- Windows Registry API
- NSIS scripting (jellyfin.nsi + .nsddef/.nsinc dialogs + .nsh helpers)
- nsProcess C plugin for advanced NSIS functionality

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build/Install Lane
    subgraph "Build/Install" 
        direction TB
        NSISCompiler["NSIS Compiler (makensis)"]:::installer
        NSISScripts["NSIS Installer Scripts"]:::installer
        SupportPlugin["NSIS Plugin (nsProcess)"]:::installer
        InstallerAssets["Installer Assets"]:::installer
        CombinedBinaries["Combined Server & Tray Binaries"]:::executable
        RegistryTemplate["Registry Template (.reg)"]:::storage
        ServiceReg["Service Registration (SCM)"]:::external
        WindowsInstaller["Windows Installer .exe"]:::executable
        Solution["Solution File (Jellyfin.Windows.Tray.sln)"]:::code
        BuildScript["PowerShell build-jellyfin.ps1"]:::code
        Workflows["GitHub Actions Workflows"]:::code
        Ruleset["Code Quality Ruleset (jellyfin.ruleset)"]:::code
        Docs["Project Documentation (README.md, LICENSE)"]:::code

        NSISCompiler -->|compiles| NSISScripts
        NSISScripts -->|uses| SupportPlugin
        NSISScripts -->|bundles| InstallerAssets
        NSISScripts -->|packages| CombinedBinaries
        NSISScripts -->|writes| RegistryTemplate
        NSISScripts -->|registers| ServiceReg
        NSISScripts -->|generates| WindowsInstaller

        Solution -->|includes| NSISScripts
        Solution -->|builds| CombinedBinaries
        Solution -->|references| SupportPlugin

        BuildScript -->|invokes| Solution
        BuildScript -->|calls| NSISCompiler

        Workflows -->|run| BuildScript
        Workflows -->|deploy| WindowsInstaller

        Ruleset -->|applies to| Solution
        Docs -->|describes| NSISScripts
    end

    %% Runtime Lane
    subgraph "Runtime Operation"
        direction TB
        User["User (Windows Desktop)"]:::external
        TrayApp["Tray App (Jellyfin.Windows.Tray.exe)"]:::executable
        Registry["Registry (HKLM\\SOFTWARE\\WOW6432Node\\Jellyfin\\Server)"]:::storage
        SCM["Service Control Manager"]:::external
        WindowsService["Windows Service 'JellyfinServer'"]:::executable
        JellyfinExe["Jellyfin Server Executable (jellyfin.exe)"]:::executable
        DataFolder["Data Folder (config, db, logs)"]:::storage
        Browser["Default Browser"]:::external
        Explorer["Windows Explorer"]:::external

        User -->|launches| TrayApp
        TrayApp -->|reads| Registry
        TrayApp -->|uses| SCM
        SCM -->|manages| WindowsService
        TrayApp -->|starts/stops| WindowsService
        TrayApp -->|launches| JellyfinExe
        JellyfinExe -->|reads/writes| DataFolder
        TrayApp -->|opens| Browser
        TrayApp -->|opens| Explorer
    end

    %% Click Events
    click TrayApp "https://github.com/jellyfin/jellyfin-server-windows/tree/master/Jellyfin.Windows.Tray/"
    click NSISScripts "https://github.com/jellyfin/jellyfin-server-windows/tree/master/nsis/"
    click SupportPlugin "https://github.com/jellyfin/jellyfin-server-windows/tree/master/Support Files/nsProcess/"
    click RegistryTemplate "https://github.com/jellyfin/jellyfin-server-windows/blob/master/Support Files/Jellyfin Registry.reg"
    click BuildScript "https://github.com/jellyfin/jellyfin-server-windows/blob/master/build-jellyfin.ps1"
    click Workflows "https://github.com/jellyfin/jellyfin-server-windows/blob/master/.github/workflows/build.yaml"
    click Workflows "https://github.com/jellyfin/jellyfin-server-windows/blob/master/.github/workflows/publish-stable.yaml"
    click Workflows "https://github.com/jellyfin/jellyfin-server-windows/blob/master/.github/workflows/publish-unstable.yaml"
    click Workflows "https://github.com/jellyfin/jellyfin-server-windows/blob/master/.github/workflows/_meta-publish.yaml"
    click Solution "https://github.com/jellyfin/jellyfin-server-windows/blob/master/Jellyfin.Windows.Tray.sln"
    click Ruleset "https://github.com/jellyfin/jellyfin-server-windows/blob/master/jellyfin.ruleset"
    click Docs "https://github.com/jellyfin/jellyfin-server-windows/blob/master/README.md"
    click Docs "https://github.com/jellyfin/jellyfin-server-windows/tree/master/LICENSE"

    %% Styles
    classDef installer fill:#ffa500,stroke:#333,stroke-width:1px
    classDef executable fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef storage fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef code fill:#dda0dd,stroke:#333,stroke-width:1px
```
