# daudk3/jellycli architecture

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

- Interactive diagram: https://gitdiagram.com/daudk3/jellycli
- Repository: https://github.com/daudk3/jellycli

## Overview

##### Project Type and Purpose
- This is a standalone, terminal-based (TUI) client for a Jellyfin media server.
- It provides a keyboard-focused interface (built with Textual) that lets users browse libraries, search, play media via mpv, and synchronize playback progress via Jellyfin’s REST API and OIDC SSO.

##### High-Level Architecture
┌──────────────────┐      HTTP/API      ┌────────────────────┐
│                  │ ────────────────> │                    │
│    UI Layer      │                   │  Jellyfin Server   │
│  (Textual TUI)   │ <───────────────  │  (Media + SSO)     │
│                  │      Webhooks     │   + OIDC Provider  │
└──────────────────┘                    └────────────────────┘
│
│ mpv CLI invocation
▼
┌───────────┐
│  mpv      │
│  Player   │
└───────────┘

##### Main Internal Components
- UI (ui/):
- app.py – starts the Textual application.
- css.py – styling.
- screens/ – library, login, media detail, server setup, modals.
- API Client (api/jellyfin.py):
- Wraps HTTP calls (requests) to fetch libraries, items, resume/progress endpoints.
- Handles authentication flows (password vs. OIDC SSO via browser redirect).
- Models (models/media.py):
- Domain objects (MediaItem, Series, Episode, etc.) used by UI and persistence.
- Playback (playback/tracker.py):
- Launches mpv as a detached process with appropriate URL/headers.
- Polls or listens for progress, posts updates back to server.
- Configuration (config.py + config.json at runtime):
- Reads/writes user preferences, server URL, credentials, oidc provider name, greeting toggle.
- Utilities (utils/):
- time.py – formatting timestamps and durations.
- generic helpers for JSON I/O, error handling, etc.

##### Component Relationships & Data Flow
- UI triggers user actions (e.g., “Enter” to play item) → calls API client to get playback URL → hands URL to Playback module → mpv process starts.
- Playback module reports resume position requests to API client, which issues HTTP PATCH/POST for progress sync.
- On startup, UI calls API client to authenticate:
- Password flow → direct HTTP POST.
- OIDC flow → API client opens browser, listens for callback, exchanges code for tokens.
- UI uses Models to represent API responses; Models are passed to screens for rendering.
- Config loader populates UI login screen or server URL screen if config missing.

##### Architectural Patterns & Principles
- Layered architecture:
- Presentation (UI)
- Application/API client
- Domain models
- Infrastructure (playback, config, utils)
- Single-process, modular design: separate Python packages by responsibility.
- Clear separation of concerns: UI code does not deal with HTTP or OS calls directly.
- External dependencies injected or wrapped (e.g., mpv binary on PATH, requests library).

##### Technologies & Frameworks
- Python 3.10+
- Textual (rich + curses-style TUI)
- Requests (HTTP client)
- mpv (media playback CLI)
- OIDC SSO plugin on Jellyfin
- JSON file for config persistence

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Packages
    subgraph "UI Layer"
        direction TB
        UIApp["app.py"]:::ui
        UICSS["css.py"]:::ui
        UIScreenLib["library.py"]:::ui
        UIScreenLogin["login.py"]:::ui
        UIScreenMedia["media.py"]:::ui
        UIScreenModals["modals.py"]:::ui
        UIScreenServer["server.py"]:::ui
    end

    subgraph "API Client"
        direction TB
        API["jellyfin.py"]:::api
    end

    subgraph "Models"
        direction TB
        Models["media.py"]:::model
    end

    subgraph "Playback"
        direction TB
        Tracker["tracker.py"]:::infra
    end

    subgraph "Configuration"
        direction TB
        Config["config.py"]:::infra
    end

    subgraph "Utilities"
        direction TB
        UtilsDir["utils"]:::infra
        TimeUtil["time.py"]:::infra
    end

    %% External Systems
    JellyfinServer["Jellyfin Server\n(REST API + OIDC)"]:::external
    Browser["Web Browser"]:::external
    MPV["mpv Player"]:::external

    %% Relationships
    UIApp -->|"HTTP GET/POST,\nJSON"| API
    API -->|"GET /Users/.../Items"| JellyfinServer
    JellyfinServer -->|"JSON"| API
    API -->|"Open browser to /sso/OIDC"| Browser
    Browser -->|"OIDC callback (code)"| API
    API -->|"PATCH resume position"| JellyfinServer
    UIApp -->|"Obtain playback URL"| Tracker
    Tracker -->|"mpv --player-operation-mode=... "| MPV
    Tracker -->|"POST resume position"| API
    API -->|"Maps to"| Models
    UIApp -->|"Uses domain objects"| Models
    Config -->|"Loads on startup"| UIApp
    UtilsDir -->|"Helpers"| UIApp
    UtilsDir -->|"Helpers"| API
    TimeUtil -->|"Formats timestamps"| UIScreenLib
    TimeUtil -->|"Formats timestamps"| UIScreenLogin
    TimeUtil -->|"Formats timestamps"| UIScreenMedia
    TimeUtil -->|"Formats timestamps"| UIScreenModals
    TimeUtil -->|"Formats timestamps"| UIScreenServer

    %% Click Events
    click UIApp "https://github.com/daudk3/jellycli/blob/master/ui/app.py"
    click UICSS "https://github.com/daudk3/jellycli/blob/master/ui/css.py"
    click UIScreenLib "https://github.com/daudk3/jellycli/blob/master/ui/screens/library.py"
    click UIScreenLogin "https://github.com/daudk3/jellycli/blob/master/ui/screens/login.py"
    click UIScreenMedia "https://github.com/daudk3/jellycli/blob/master/ui/screens/media.py"
    click UIScreenModals "https://github.com/daudk3/jellycli/blob/master/ui/screens/modals.py"
    click UIScreenServer "https://github.com/daudk3/jellycli/blob/master/ui/screens/server.py"
    click API "https://github.com/daudk3/jellycli/blob/master/api/jellyfin.py"
    click Models "https://github.com/daudk3/jellycli/blob/master/models/media.py"
    click Tracker "https://github.com/daudk3/jellycli/blob/master/playback/tracker.py"
    click Config "https://github.com/daudk3/jellycli/blob/master/config.py"
    click UtilsDir "https://github.com/daudk3/jellycli/tree/master/utils/"
    click TimeUtil "https://github.com/daudk3/jellycli/blob/master/utils/time.py"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef api fill:#C8E6C9,stroke:#43A047,color:#1B5E20
    classDef model fill:#FFF9C4,stroke:#FBC02D,color:#F57F17
    classDef infra fill:#E0E0E0,stroke:#9E9E9E,color:#424242
    classDef external fill:#FFE0B2,stroke:#FB8C00,color:#E65100
```
