'use client' import { useEffect, useState } from 'react' import { useRouter } from 'next/navigation' import AdminShell from '../../ui/AdminShell' import { authFetch, clearToken, getApiBase, getToken } from '../../lib/auth' type FlowStage = { title: string input: string action: string output: string } const REQUEST_FLOW: FlowStage[] = [ { title: 'Identity + access', input: 'Jellyfin/local login', action: 'Magent validates credentials and role', output: 'JWT token + user scope', }, { title: 'Request intake', input: 'Seerr request ID', action: 'Magent snapshots request + media metadata', output: 'Unified request state', }, { title: 'Queue orchestration', input: 'Approved request', action: 'Sonarr/Radarr add/search operations', output: 'Grab decision', }, { title: 'Download execution', input: 'Selected release', action: 'qBittorrent downloads + reports progress', output: 'Import-ready payload', }, { title: 'Library import', input: 'Completed download', action: 'Sonarr/Radarr import and finalize', output: 'Available media object', }, { title: 'Playback availability', input: 'Imported media', action: 'Jellyfin refresh + link resolution', output: 'Ready-to-watch state', }, ] export default function AdminSystemGuidePage() { const router = useRouter() const [loading, setLoading] = useState(true) const [authorized, setAuthorized] = useState(false) useEffect(() => { let active = true const load = async () => { if (!getToken()) { router.push('/login') return } try { const baseUrl = getApiBase() const response = await authFetch(`${baseUrl}/auth/me`) if (!response.ok) { if (response.status === 401) { clearToken() router.push('/login') return } router.push('/') return } const me = await response.json() if (!active) return if (me?.role !== 'admin') { router.push('/') return } setAuthorized(true) } catch (error) { console.error(error) router.push('/') } finally { if (active) setLoading(false) } } void load() return () => { active = false } }, [router]) if (loading) { return
Loading system guide...
} if (!authorized) { return null } const rail = (
How it works

Admin flow map

Identity → Request intake → Queue orchestration → Download → Import → Playback.

Admin only
) return ( router.push('/admin')}> Back to settings } >

End-to-end system flow

This is the runtime path the platform follows from authentication through to playback availability.

{REQUEST_FLOW.map((stage, index) => (
{index + 1}. {stage.title}
Input {stage.input}
Action {stage.action}
Output {stage.output}
{index < REQUEST_FLOW.length - 1 && }
))}

What each service is responsible for

Magent

Handles authentication, request pages, live event updates, invite workflows, diagnostics, notifications, and admin operations.

Seerr

Stores the request itself and remains the request-state source for approval and media request metadata.

Jellyfin

Provides user sign-in identity and the final playback destination once content is available.

Sonarr / Radarr

Control queue placement, quality-profile decisions, import handling, and release monitoring.

Prowlarr

Provides search/indexer coverage for Arr-side release searches.

qBittorrent

Executes the download and exposes live progress, paused states, and queue visibility.

Operational controls by area

General

Application URL, API URL, ports, bind host, proxy base URL, and manual SSL settings.

Notifications

Email, Discord, Telegram, push/mobile, and generic webhook delivery channels.

Users

Role/profile/expiry, auto-search access, invite access, and cross-system ban/remove actions.

Invite management

Master template, profile assignment, invite access policy, invite emails, and trace map lineage.

Requests + cache

All-requests view, sync controls, cached request records, and maintenance operations.

Maintenance + diagnostics

Connectivity checks, live diagnostics, database repair, cleanup, log review, and nuclear flush/resync operations.

User and invite model

  1. Jellyfin is used for sign-in identity and user presence across the platform.
  2. Seerr provides request ownership and request-state data for Magent request pages.
  3. Invite links, invite profiles, blanket rules, and invite-access controls are managed inside Magent.
  4. If invite tracing is enabled, the lineage view shows who invited whom and how the chain branches.
  5. Cross-system removal and ban flows are initiated from Magent admin controls.

Stall recovery path (decision flow)

  1. Request approved but not in Arr queue run Re-add to Arr.
  2. In queue but no release found run Search releases and inspect options.
  3. Release exists and user should not pick manually run Search + auto-download.
  4. Download paused/stalled in qBittorrent run Resume download.
  5. Imported but not visible to user validate Jellyfin visibility/link from request page.

Live update surfaces

Landing page

Recent requests and service summaries refresh live for signed-in users.

Request pages

Timeline state, queue activity, and torrent progress are pushed live without refresh.

Admin views

Diagnostics, logs, sync state, and maintenance surfaces stream live operational data.

) }