# teampiped/piped-backend architecture

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

- Interactive diagram: https://gitdiagram.com/teampiped/piped-backend
- Repository: https://github.com/teampiped/piped-backend

## Overview

##### Main Components

a. Core Service Components:
- API Server Layer (based on the handlers directory)
- Authentication System (auth handlers)
- Video Processing System (StreamHandlers)
- Database Layer (indicated by hibernate.cfg.xml and db changelog)
- External Service Integrations (NewPipeExtractor)

b. Key Features:
- Channel Management
- Playlist Handling
- Search Functionality
- Trending Content
- PubSub System
- User Management
- Federation Support

**┌─ Client Layer ─────────────────────┐**
- Frontend Clients (Vue.js)          │
- ┬────────────────────┘
- ↓
**┌─ API Gateway Layer ────────────────┐**
- ServerLauncher                     │
- ┬────────────────────┘
- ↓
**┌─ Handler Layer ───────────────────────────────────────┐**
- ┌─────────────┐ ┌──────────┐ ┌────────────┐         │
- Public APIs  │ │Auth APIs │ │Stream APIs │         │
- ┘ └──────────┘ └────────────┘         │
- ┬────────────────────────────────────────┘
- ↓
**┌─ Service Layer ───────────────────────────────────────┐**
- ┌──────────┐ ┌─────────┐ ┌────────────┐ ┌─────────┐ │
- Video     │ │Channel  │ │Playlist    │ │Search   │ │
- Services  │ │Services │ │Services    │ │Services │ │
- ┘ └─────────┘ └────────────┘ └─────────┘ │
- ┬────────────────────────────────────────┘
- ↓
**┌─ Data Layer ─────────────────────────────────────────┐**
- ┌──────────┐ ┌─────────────────┐ ┌───────────────┐  │
- Hibernate │ │Database         │ │Cache          │  │
- ORM      │ │(Multiple DBs)   │ │               │  │
- ┘ └─────────────────┘ └───────────────┘  │
- ┘

##### Important Relationships

- Frontend → API Gateway: REST/HTTP communication
- Handler Layer → Service Layer: Internal method calls
- Service Layer → Data Layer: Database operations
- Service Layer → External Services: NewPipeExtractor integration
- Authentication flow through the layers

##### Additional Elements

- Docker container boundaries (multiple Dockerfile variants exist)
- Database migration flows (shown by changelog directory)
- Federation support components
- External service dependencies

##### Technical Details

- Database support for multiple backends (PostgreSQL, CockroachDB, YugabyteDB)
- Authentication mechanisms
- Cache layers
- Background job processors (Multithreading.java)

##### Specific Implementation Notes

- Handler structure (/server/handlers/)
- Utility services (/utils/)
- Database models (/utils/obj/db/)
- Federation components (/utils/obj/federation/)

This architecture should emphasize the privacy-focused nature of the system and how it interfaces with YouTube's data while maintaining user privacy.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        Frontend[Frontend Clients]
    end

    subgraph APIGateway
        ServerLauncher["Server Launcher"]:::server
    end

    subgraph Handlers
        direction TB
        PublicAPIs["Public APIs"]:::api
        AuthSystem["Authentication System"]:::auth
        StreamAPIs["Stream APIs"]:::api
        
        HandlerGroup["Handler Components"]
        ChannelHandler["Channel Handler"]:::handler
        PlaylistHandler["Playlist Handler"]:::handler
        SearchHandler["Search Handler"]:::handler
        TrendingHandler["Trending Handler"]:::handler
        PubSubHandler["PubSub Handler"]:::handler

        HandlerGroup --> ChannelHandler
        HandlerGroup --> PlaylistHandler
        HandlerGroup --> SearchHandler
        HandlerGroup --> TrendingHandler
        HandlerGroup --> PubSubHandler
    end

    subgraph Services
        direction TB
        UtilityServices["Utility Services"]
        VideoHelper["Video Helper"]:::util
        ChannelHelper["Channel Helper"]:::util
        PlaylistHelper["Playlist Helper"]:::util
        FeedHelper["Feed Helper"]:::util

        UtilityServices --> VideoHelper
        UtilityServices --> ChannelHelper
        UtilityServices --> PlaylistHelper
        UtilityServices --> FeedHelper
    end

    subgraph DataLayer
        direction TB
        DatabaseHelper["Database Helper"]:::db
        HibernateConfig["Hibernate Config"]:::db
        DatabaseModels["Database Models"]:::db
        Migration["Migration Scripts"]:::db
        
        DataModels["Core Data Models"]
        ChannelModel["Channel Model"]:::model
        PlaylistModel["Playlist Model"]:::model
        StreamModel["Stream Model"]:::model
        UserModel["User Model"]:::model

        DataModels --> ChannelModel
        DataModels --> PlaylistModel
        DataModels --> StreamModel
        DataModels --> UserModel
    end

    subgraph Federation
        FederationSystem["Federation System"]:::fed
    end

    Frontend --> ServerLauncher
    ServerLauncher --> PublicAPIs
    ServerLauncher --> AuthSystem
    ServerLauncher --> StreamAPIs
    
    PublicAPIs --> HandlerGroup
    AuthSystem --> HandlerGroup
    StreamAPIs --> HandlerGroup
    
    HandlerGroup --> UtilityServices
    HandlerGroup --> DataModels
    
    UtilityServices --> DatabaseHelper
    DataModels --> DatabaseHelper
    
    DatabaseHelper --> HibernateConfig
    DatabaseHelper --> DatabaseModels
    DatabaseHelper --> Migration
    
    HandlerGroup --> FederationSystem

    %% Click Events
    click ServerLauncher "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/server/ServerLauncher.java"
    click ChannelHandler "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/server/handlers/ChannelHandlers.java"
    click PlaylistHandler "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/server/handlers/PlaylistHandlers.java"
    click SearchHandler "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/server/handlers/SearchHandlers.java"
    click TrendingHandler "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/server/handlers/TrendingHandlers.java"
    click PubSubHandler "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/server/handlers/PubSubHandlers.java"
    click AuthSystem "https://github.com/TeamPiped/Piped-Backend/tree/master/src/main/java/me/kavin/piped/server/handlers/auth"
    click HibernateConfig "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/resources/hibernate.cfg.xml"
    click Migration "https://github.com/TeamPiped/Piped-Backend/tree/master/src/main/resources/changelog"
    click DatabaseModels "https://github.com/TeamPiped/Piped-Backend/tree/master/src/main/java/me/kavin/piped/utils/obj/db"
    click DatabaseHelper "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/utils/DatabaseHelper.java"
    click FederationSystem "https://github.com/TeamPiped/Piped-Backend/tree/master/src/main/java/me/kavin/piped/utils/obj/federation"
    click ChannelModel "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/utils/obj/Channel.java"
    click PlaylistModel "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/utils/obj/Playlist.java"
    click StreamModel "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/utils/obj/Streams.java"
    click UserModel "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/utils/obj/db/User.java"
    click VideoHelper "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/utils/VideoHelpers.java"
    click ChannelHelper "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/utils/ChannelHelpers.java"
    click PlaylistHelper "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/utils/PlaylistHelpers.java"
    click FeedHelper "https://github.com/TeamPiped/Piped-Backend/blob/master/src/main/java/me/kavin/piped/utils/FeedHelpers.java"

    %% Styles
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px
    classDef server fill:#d4e6ff,stroke:#333
    classDef api fill:#b3e0ff,stroke:#333
    classDef auth fill:#ffcccc,stroke:#333
    classDef handler fill:#d9f2d9,stroke:#333
    classDef util fill:#e6e6ff,stroke:#333
    classDef db fill:#fff2cc,stroke:#333
    classDef model fill:#f2e6ff,stroke:#333
    classDef fed fill:#ffd9b3,stroke:#333
```
