Arhitectura Tehnică a Platformei Jellyseerr

1. Arhitectura Serverului Jellyseerr

1.1 Componentele de Bază ale Serverului

Jellyseerr este o aplicație web construită pentru gestionarea cererilor media, cu următoarele straturi principale:

• Frontend React - Interfața utilizatorului scrisă în React
• Backend Node.js - Serverul API construit cu Express.js
• Database - Baza de date pentru stocarea cererilor și setărilor
• External APIs - Integrări cu servicii externe

1.2 Tehnologii și Limbaje de Programare

Jellyseerr este dezvoltat în:

• Node.js pentru backend
• React pentru frontend
• TypeScript pentru ambele părți
• PostgreSQL/SQLite pentru baze de date
• CSS/SASS pentru styling

2. Sistemul de Baze de Date

2.1 Structura Bazelor de Date

Jellyseerr folosește o bază de date relațională cu tabele specializate:

settings.db - Setările aplicației și configurația

requests.db - Cererile utilizatorilor și istoricul

users.db - Datele utilizatorilor și permisiunile

2.2 Schemele de Tabele Principale

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. Serverul Web și API-ul

3.1 Arhitectura Backend

Jellyseerr rulează pe un server Node.js cu Express.js care:

• Gestionează cereri HTTP REST
• Servește aplicația React
• Comunică cu baza de date
• Integrează cu API-uri externe

3.2 Endpoint-uri API Principale

/api/v1/auth - Autentificare și management utilizatori

/api/v1/request - Operațiuni pe cererile media

/api/v1/movie - Operațiuni specifice filmelor

/api/v1/tv - Operațiuni specifice serialelor

/api/v1/settings - Management setări

3.3 Sistemul de Autentificare

Jellyseerr folosește JWT (JSON Web Tokens) pentru:

• Autentificare stateless
• Securitate îmbunătățită
• Expirare controlată a sesiunilor
• Revocare token-uri

4. Integrări cu Servicii Externe

4.1 Conexiunea cu Jellyfin/Emby

Jellyseerr se conectează la serverul media prin:

• API-ul nativ Jellyfin/Emby
• Autentificare cu token
• Sincronizare utilizatori
• Verificare disponibilitate conținut (pe Emby)

4.2 The Movie Database (TMDb)

Integrare cu TMDb pentru:

• Căutare filme și seriale
• Metadata detaliată
• Imagini și poster-e
• Informații despre echipa de producție

4.3 Servicii de Notificări

Suport pentru multiple platforme:

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

5. Sistemul de Cereri Media

5.1 Fluxul unei Cereri

Procesul complet al unei cereri:

1. Utilizatorul caută media pe TMDb
2. Sistemul verifică disponibilitatea pe serverul media
3. Dacă nu este disponibil, se creează cererea
4. Administratorii aprobă/resping cererea
5. La aprobare, se notifică utilizatorii
6. Sistemul monitorizează adăugarea automată

5.2 Managementul Cererilor

Jellyseerr gestionează:

• Cereri noi în așteptare
• Cereri aprobate
• Cereri respinse
• Cereri completate automat
• Limitări de cereri per utilizator

6. Sistemul de Permisiuni

6.1 Roluri și Drepturi

Jellyseerr suportă multiple niveluri de acces:

• Administrator - Acces complet
• Moderator - Poate aproba cereri
• User - Poate face cereri
• Guest - Doar vizualizare

6.2 Controlul Accesului

Sistemul implementează:

• Autentificare obligatorie
• Verificare permisiuni pe endpoint-uri
• Limitări bazate pe rol
• Logging al acțiunilor

7. Sistemul de Notificări

7.1 Tipuri de Notificări

Jellyseerr trimite notificări pentru:

• Cereri noi
• Aprobări/respingeri
• Media adăugată
• Erori în sistem
• Actualizări aplicație

7.2 Configurarea Notificărilor

Administratorii pot configura:

• Platforme de notificări
• Șabloane de mesaje
• Frecvența notificărilor
• Tipurile de evenimente

8. Procesul de Inițializare

8.1 Secvența de Pornire

La start, Jellyseerr execută:

1. Încărcare variabile de mediu
2. Conexiune la baza de date
3. Verificare configurație
4. Testare conexiuni API externe
5. Pornire server web
6. Inițializare cache-uri

9. Sistemul de Securitate

9.1 Măsuri de Securitate

Jellyseerr implementează:

• Validare input
• Sanitizare date
• Rate limiting
• CORS configuration
• HTTPS enforcement
• Secure headers