Technical Architecture of the Jellyseerr Platform

1. Jellyseerr Server Architecture

1.1 Core Server Components

Jellyseerr is a web application built for managing media requests, with the following main layers:

• React Frontend - The user interface written in React
• Node.js Backend - The API server built with Express.js
• Database - Database for storing requests and settings
• External APIs - Integrations with external services

1.2 Technologies and Programming Languages

Jellyseerr is developed using:

• Node.js for backend
• React for frontend
• TypeScript for both sides
• PostgreSQL/SQLite for databases
• CSS/SASS for styling

2. Database System

2.1 Database Structure

Jellyseerr uses a relational database with specialized tables:

settings.db - Application settings and configuration

requests.db - User requests and history

users.db - User data and permissions

2.2 Main Table Schemas

CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email VARCHAR(255) UNIQUE NOT NULL,
    username VARCHAR(255),
    password VARCHAR(255),
    permissions INTEGER DEFAULT 0,
    avatar VARCHAR(255),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE media_requests (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    type VARCHAR(50) NOT NULL,
    tmdb_id INTEGER NOT NULL,
    tvdb_id INTEGER,
    status INTEGER DEFAULT 1,
    requested_by INTEGER NOT NULL,
    modified_by INTEGER,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (requested_by) REFERENCES users(id),
    FOREIGN KEY (modified_by) REFERENCES users(id)
);

CREATE TABLE settings (
    key VARCHAR(255) PRIMARY KEY,
    value TEXT,
    type VARCHAR(50) DEFAULT 'string',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE notification_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    type VARCHAR(100) NOT NULL,
    subject TEXT,
    message TEXT,
    sent_to INTEGER,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (sent_to) REFERENCES users(id)
);

3. Web Server and API

3.1 Backend Architecture

Jellyseerr runs on a Node.js server with Express.js that:

• Handles REST HTTP requests
• Serves the React application
• Communicates with the database
• Integrates with external APIs

3.2 Main API Endpoints

/api/v1/auth - Authentication and user management

/api/v1/request - Media request operations

/api/v1/movie - Movie-specific operations

/api/v1/tv - TV show-specific operations

/api/v1/settings - Settings management

3.3 Authentication System

Jellyseerr uses JWT (JSON Web Tokens) for:

• Stateless authentication
• Enhanced security
• Controlled session expiration
• Token revocation

4. External Service Integrations

4.1 Connection with Jellyfin/Emby

Jellyseerr connects to the media server through:

• Native Jellyfin/Emby API
• Token authentication
• User synchronization
• Content availability check (on Emby)

4.2 The Movie Database (TMDb)

Integration with TMDb for:

• Movie and TV show search
• Detailed metadata
• Images and posters
• Production team information

4.3 Notification Services

Support for multiple platforms:

• Discord webhooks
• Email (SMTP)
• Pushbullet
• Telegram
• Slack

5. Media Request System

5.1 Request Flow

Complete request process:

1. User searches media on TMDb
2. System checks availability on the media server
3. If not available, request is created
4. Administrators approve/deny request
5. Upon approval, users are notified
6. System monitors automatic addition

5.2 Request Management

Jellyseerr manages:

• New pending requests
• Approved requests
• Denied requests
• Automatically completed requests
• Request limits per user

6. Permission System

6.1 Roles and Rights

Jellyseerr supports multiple access levels:

• Administrator - Full access
• Moderator - Can approve requests
• User - Can make requests
• Guest - View only

6.2 Access Control

The system implements:

• Mandatory authentication
• Permission verification on endpoints
• Role-based limitations
• Action logging

7. Notification System

7.1 Notification Types

Jellyseerr sends notifications for:

• New requests
• Approvals/denials
• Media added
• System errors
• Application updates

7.2 Notification Configuration

Administrators can configure:

• Notification platforms
• Message templates
• Notification frequency
• Event types

8. Initialization Process

8.1 Startup Sequence

On startup, Jellyseerr executes:

1. Loading environment variables
2. Database connection
3. Configuration check
4. External API connection testing
5. Web server start
6. Cache initialization

9. Security System

9.1 Security Measures

Jellyseerr implements:

• Input validation
• Data sanitization
• Rate limiting
• CORS configuration
• HTTPS enforcement
• Secure headers