# zigl3ur/jellyhub architecture

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

- Interactive diagram: https://gitdiagram.com/zigl3ur/jellyhub
- Repository: https://github.com/zigl3ur/jellyhub

## Overview

Based on our analysis of the file tree and README, JellyHub is a web application built with Next.js and React that aggregates media data from multiple Jellyfin servers into a single searchable interface. It’s structured as a full-stack Next.js application that uses Prisma as an ORM for Postgres along with Docker containerization and GitHub Actions for CI/CD.

##### Project Type and Purpose
- This is a full-stack web application that “indexes” media from various Jellyfin servers.
- Its primary function is to fetch media data from external Jellyfin server APIs and present a consolidated interface for searching and managing media.
- Docker is used for deployment, and the project utilizes a Postgres database (accessed via Prisma) to store configuration and possibly media indexing data.

##### Key Components
a. Frontend (Client-side):
- Next.js UI – Located in the “src/app” and “src/components” directories. It uses React to render pages (such as login, home, details, settings) and various UI components.
- User Interaction – The browser/client accesses the Next.js app; include labels such as “User Browser” or “Client”.

b. Backend / Server-side (Next.js App):
- API Routes and Server Components – Many files in “src/lib” (for authentication, API integrations to Jellyfin, prisma connection, etc.) indicate that parts of the Next.js app serve API endpoints.
- Middleware and Routing – There is a “src/middleware.ts” and structured directories under “src/app” that indicate server-side logic.

c. Database:
- Postgres – The Docker Compose file and Prisma schema (located in the “prisma” directory) show that Postgres is used as the underlying database.
- Prisma ORM – Represent this intermediate layer that handles database interactions.

d. External Jellyfin Servers:

e. Deployment / Containerization:
- Docker Containers – One container for the JellyHub application itself and another for the Postgres database. Docker Compose handles orchestration as defined in “docker-compose.yml”.

##### Relationships and Interactions
– The Next.js server reads/writes data (like indexing details, configurations) from/to Postgres.
– It also makes network calls to external Jellyfin APIs to fetch media data.
- Data flow such as login flows (authentication via JWT tokens) where the “auth” components mediate secure access. Highlight perhaps the “JWT_SECRET” configuration passing in environment variables.

##### Architectural Patterns and Design Principles
- Modular Architecting: The directory structure (with “src/components”, “src/hooks”, and “src/lib”) indicates a separation of concerns: UI, business logic (API calls, authentication), and configuration.
- Server-Side Rendering (SSR) and API routes: Emphasize Next.js’s hybrid rendering capabilities where pages are pre-rendered or rendered on demand.
- Containerization and Microservice Orientation: Even though this is a single application, it’s deployed in containers, supporting future scaling as separate services if needed.

##### Additional Details
- Mention that configuration and environment specifics (like JWT secrets, API endpoints, and DB connection strings) are set via environment variables as visible in both the Docker Compose file and the Docker CLI instructions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    browser["User Browser"]:::user

    %% Frontend Subgraph
    subgraph "Frontend"
        f_ui["Next.js UI"]:::frontend
        f_app["App Directory"]:::frontend
        f_comp["Components Directory"]:::frontend
        f_layout["Layout File"]:::frontend
        f_globals["Globals File"]:::frontend
    end

    %% Backend Subgraph
    subgraph "Backend"
        b_api["API & Server Components"]:::backend
        b_lib["Lib Directory"]:::backend
        b_mw["Middleware"]:::backend
    end

    %% Database Subgraph
    subgraph "Database Layer"
        d_db["Postgres Database (via Prisma)"]:::database
        d_prisma["Prisma Directory"]:::database
        d_dcompose["Docker Compose (DB)"]:::database
    end

    %% Deployment Subgraph
    subgraph "Deployment"
        dep_dockerfile["Dockerfile"]:::deployment
        dep_dcompose["Docker Compose"]:::deployment
    end

    %% CI/CD Subgraph
    subgraph "CI/CD Pipeline"
        cicd["GitHub Actions"]:::cicd
    end

    %% External Services Subgraph
    subgraph "External Services"
        ex_api["Jellyfin API"]:::external
    end

    %% Connections between Layers
    browser -->|"HTTP_Request"| f_ui
    f_ui -->|"API_Calls"| b_api
    b_api -->|"DB_Read_Write"| d_db
    b_api -->|"Fetch_Media_Data"| ex_api

    %% Internal Frontend Structure
    f_ui --> f_app
    f_ui --> f_comp
    f_ui --> f_layout
    f_ui --> f_globals

    %% Internal Backend Structure
    b_api --> b_lib
    b_api --> b_mw

    %% Internal Database Structure
    d_db --> d_prisma
    d_db --> d_dcompose

    %% Deployment Relationships
    f_ui --- dep_dockerfile
    b_api --- dep_dockerfile
    d_db --- dep_dcompose

    cicd --> dep_dockerfile
    cicd --> dep_dcompose

    %% Styling
    classDef user fill:#fffacd,stroke:#333,stroke-width:2px;
    classDef frontend fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef backend fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef database fill:#ffdead,stroke:#333,stroke-width:2px;
    classDef external fill:#f08080,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef deployment fill:#dda0dd,stroke:#333,stroke-width:2px,stroke-dasharray: 2 2;
    classDef cicd fill:#ffb6c1,stroke:#333,stroke-width:2px,stroke-dasharray: 2 2;

    %% Click Events for Frontend Components
    click f_app "https://github.com/zigl3ur/jellyhub/tree/main/src/app"
    click f_comp "https://github.com/zigl3ur/jellyhub/tree/main/src/components"
    click f_layout "https://github.com/zigl3ur/jellyhub/blob/main/src/app/layout.tsx"
    click f_globals "https://github.com/zigl3ur/jellyhub/blob/main/src/app/globals.css"

    %% Click Events for Backend Components
    click b_lib "https://github.com/zigl3ur/jellyhub/tree/main/src/lib"
    click b_mw "https://github.com/zigl3ur/jellyhub/blob/main/src/middleware.ts"

    %% Click Events for Database Components
    click d_prisma "https://github.com/zigl3ur/jellyhub/tree/main/prisma"
    click d_dcompose "https://github.com/zigl3ur/jellyhub/blob/main/docker-compose.yml"

    %% Click Event for External Jellyfin API
    click ex_api "https://github.com/zigl3ur/jellyhub/blob/main/src/lib/api.jellyfin.ts"

    %% Click Events for Deployment Components
    click dep_dockerfile "https://github.com/zigl3ur/jellyhub/tree/main/Dockerfile"
    click dep_dcompose "https://github.com/zigl3ur/jellyhub/blob/main/docker-compose.yml"

    %% Click Event for CI/CD Pipeline
    click cicd "https://github.com/zigl3ur/jellyhub/tree/main/.github/workflows"
```
