# fallenbagel/jellyseerr architecture

> Architecture diagram of the GitHub repository fallenbagel/jellyseerr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fallenbagel/jellyseerr
- Repository: https://github.com/fallenbagel/jellyseerr

## Overview

Based on our analysis, Jellyseerr is a full‐stack, open–source media request management application that integrates with several media servers (Jellyfin, Plex, Emby) and external services like Sonarr and Radarr. Its purpose is to offer a unified, user–friendly interface for requesting media (movies, TV shows, etc.) with robust backend API support, a web–based front end (built in Next.js with a well–structured “src” directory), and a set of deployment assets (Dockerfiles, Helm charts, Kubernetes manifests) ensuring containerized and cloud–compatible deployments.

##### Main Components
- Frontend: Represented by the “src” directory; it contains pages, components, contexts, hooks, styles, and i18n resources. This layer handles user interface (views, routing, internationalization) and interacts with the backend API.
- Backend/API Server: The “server” directory includes API routes, business logic (controllers, interfaces, and various libraries such as scanning, email, notifications, and settings). It handles authentication, request management, and integrations with external services.
- Database Layer: Support for PostgreSQL and SQLite is apparent in the migration scripts (under server/migration). This component is responsible for persisting users, media requests, settings, and logs.
- Deployment and DevOps: Note the Dockerfiles (Dockerfile, Dockerfile.local), Helm charts (under charts), and GitHub workflows (under .github/workflows) that indicate CI/CD, testing (e.g., Cypress tests in the “cypress” folder) and deployment strategies, which interact with both the code and the production environment.

##### Relationships & Interactions
- The Frontend makes HTTP calls (via RESTful API endpoints) to the Backend, retrieving data, sending requests, and handling user sessions.
- The Backend orchestrates business logic, processes requests, communicates with one or more databases (PostgreSQL or SQLite), and integrates with external services (media servers and notification agents).
- Data flows from the user to the frontend, which in turn communicates with the server; the server then reads/writes to the database and calls out to external media APIs.
- CI/CD pipelines (GitHub workflows, Docker, Helm) manage builds, tests, and deployments, ensuring that each component is reliably packaged and released to production.

##### Architectural Patterns & Design Principles
- Separation of concerns: Clear division between frontend “view” (Next.js pages and components), backend routing and business logic, and database persistence.
- Modular design: The “server” directory is organized by domain (e.g., routes, entity, library, notifications, migrations) suggesting a modular approach—with each integration (Plex, Jellyfin, Sonarr, etc.) encapsulated in its own module.
- Extensibility: The structured components in both frontend and backend allow for additional integrations or features.
- Container–based deployment: The presence of Dockerfiles, Helm charts, and Kubernetes configurations implies that containers play a central role in deployment architecture.

##### Relevant Technologies & Frameworks
- Frontend: Next.js, React, TypeScript, along with state management via React contexts and hooks.
- Backend: Node.js with TypeScript, Express (assumed from “server/middleware”, “server/routes”), and various libraries handling database migrations, API interactions, and email/notification templating.
- Database: PostgreSQL and SQLite.
- Deployment: Docker, Docker Compose, Kubernetes (Helm charts) and CI pipelines via GitHub Actions.
- Testing: Cypress for end–to–end testing as seen in the “cypress” directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        Browser["User Browser"]:::user
        FE["Frontend (Next.js/React UI)"]:::frontend
    end

    %% Server Side
    subgraph "Server Side"
        API["API Server (Node.js/Express)"]:::backend
        DB["Database (PostgreSQL/SQLite)"]:::database
        subgraph "External Services"
            subgraph "Media Servers"
                Jellyfin["Jellyfin"]:::external
                PlexAPI["PlexAPI"]:::external
                PlexTV["PlexTV"]:::external
                Servarr["Servarr"]:::external
                Tautulli["Tautulli"]:::external
                TMDB["TheMovieDB"]:::external
            end
            Notify["Notification Agents"]:::external
        end
    end

    %% Deployment and DevOps
    subgraph "Deployment / DevOps"
        CICD["CI/CD Pipelines"]:::deployment
        Docker["Dockerfile"]:::deployment
        DockerLocal["Dockerfile.local"]:::deployment
        Helm["Helm Charts"]:::deployment
        Cypress["Cypress End-to-End Tests"]:::deployment
    end

    %% Connections
    Browser -->|"HTTP"| FE
    FE -->|"REST_API"| API
    API -->|"SQL"| DB
    API -->|"Integration"| Jellyfin
    API -->|"Integration"| PlexAPI
    API -->|"Integration"| PlexTV
    API -->|"Integration"| Servarr
    API -->|"Integration"| Tautulli
    API -->|"Integration"| TMDB
    API -->|"Notifications"| Notify
    CICD --->|"Deploys"| API
    CICD --->|"Deploys"| FE
    Docker ---|"Containerized"| API
    DockerLocal ---|"Containerized"| FE
    Helm ---|"Orchestrates"| API
    Cypress ---|"Tests"| FE

    %% Click Events
    click FE "https://github.com/fallenbagel/jellyseerr/tree/develop/src"
    click API "https://github.com/fallenbagel/jellyseerr/tree/develop/server"
    click DB "https://github.com/fallenbagel/jellyseerr/tree/develop/server/migration"
    click Jellyfin "https://github.com/fallenbagel/jellyseerr/tree/develop/server/api/jellyfin"
    click PlexAPI "https://github.com/fallenbagel/jellyseerr/tree/develop/server/api/plexapi"
    click PlexTV "https://github.com/fallenbagel/jellyseerr/tree/develop/server/api/plextv"
    click Servarr "https://github.com/fallenbagel/jellyseerr/tree/develop/server/api/servarr"
    click Tautulli "https://github.com/fallenbagel/jellyseerr/tree/develop/server/api/tautulli"
    click TMDB "https://github.com/fallenbagel/jellyseerr/tree/develop/server/api/themoviedb"
    click Notify "https://github.com/fallenbagel/jellyseerr/tree/develop/server/lib/notifications/agents"
    click Docker "https://github.com/fallenbagel/jellyseerr/tree/develop/Dockerfile"
    click DockerLocal "https://github.com/fallenbagel/jellyseerr/blob/develop/Dockerfile.local"
    click Helm "https://github.com/fallenbagel/jellyseerr/tree/develop/charts/jellyseerr-chart"
    click CICD "https://github.com/fallenbagel/jellyseerr/tree/develop/.github/workflows"
    click Cypress "https://github.com/fallenbagel/jellyseerr/tree/develop/cypress"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef database fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef deployment fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef user fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
