Architecture

JellyGlance runs beside Jellyfin. Jellyfin stays the source of truth for media, users, sessions, artwork, and library metadata. JellyGlance adds dashboard state, admin tools, integrations, task history, and repair signals around it.

Workspace

apps/web   React + Vite dashboard
apps/api   Express API, sync jobs, integrations, WebSockets
docs       Original documentation in the application checkout
scripts    Maintenance and translation utilities

This standalone documentation project uses MkDocs Material. Its pages are under docs/, its configuration is mkdocs.yml, and the generated site is written to site/.

Runtime

In development, Vite serves the web app and proxies API calls to Express. In production, Express serves both the API and the built web assets.

The browser talks to JellyGlance. JellyGlance talks to Jellyfin and optional services from the backend, keeping saved credentials server-side.

PostgreSQL stores synced metadata, settings, task logs, integration state, backups, imports, repair summaries, API keys, and newsletter history.

Flow

1. Setup validates the Jellyfin URL and API key.
2. Sync tasks pull Jellyfin users, libraries, media, sessions, artwork, and activity.
3. Optional adapters pull requests, Arr calendars, downloads, and health state.
4. The API normalizes data into PostgreSQL.
5. React pages render dashboards, jobs, logs, settings, users, activity, and repair views.
6. WebSockets and webhooks report task progress and operational events.

Frontend

apps/web contains the React app, routes, setup flow, dashboards, settings pages, and page CSS.

Main surfaces:

• Home dashboard
• Activity, Libraries, Users, Statistics, Calendar
• Requests and Downloads when configured
• admin-only Jellyfin Jobs
• Settings center, Repair, Logs, Health, Imports, Webhooks, Backups

API

apps/api owns auth, database writes, Jellyfin credentials, integration credentials, sync work, filesystem imports, backups, and webhooks.

Area	Purpose
server.js	Express startup, web asset serving, /swagger.json, and /swagger-ui
routes/auth.js	Login, Quick Connect, OIDC login
routes/api.js	Core config, users, libraries, integrations
routes/command-center.js	Item glance, ops digest, storage, compact widget endpoints, widget catalog, audit export
classes/command-center.js	Correlation helpers across Jellyfin, Seerr, Arr, and downloads
routes/sync.js	Jellyfin sync and library scan routes
routes/stats.js	Dashboard and statistics data
routes/webhooks.js	Webhook setup and tests
routes/newsletter.js	SMTP digest previews and sends
routes/tautulli.js	Legacy history import and matching
global/task-list.js	Registered background jobs

Integrations

Integrations are optional. If request or download clients are not configured, JellyGlance hides those pages instead of showing empty screens.

Adapter	Used For
Jellyfin	users, sessions, libraries, activity, jobs, devices, plugins
Jellyseerr / Overseerr	requests, availability, actions
Sonarr / Radarr / Lidarr / Readarr	release calendar and health
Bazarr	subtitle service health
qBittorrent / Transmission / Deluge / rTorrent	torrent queues (add, pause, remove)
SABnzbd / NZBGet	Usenet queues (add, pause, remove)
SickChill	connect and health; not a calendar source
Tautulli	legacy playback imports
SMTP	newsletter digest
Webhooks	task and health notifications

Tasks

JellyGlance tasks run API-side and cover syncs, Playback Reporting imports, stats refreshes, Arr calendar sync, download queue sync, health checks, webhooks, backups, restores, and cleanup.

Jellyfin scheduled jobs are separate. Admins can view and run them from the Jellyfin Jobs page.

Security

Credentials stay on the backend. Admin-only areas include Settings, API keys, backups, restore actions, integrations, logs, Jellyfin Jobs, devices, plugins, and role management.