# billos/broadcastarr architecture

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

- Interactive diagram: https://gitdiagram.com/billos/broadcastarr
- Repository: https://github.com/billos/broadcastarr

## Overview

##### And Represent the Main Components
- Frontend Interface (Client/Discord Bot Interface): Although the project does not have a traditional web frontend, the Discord bot is a major interactive component. Represent it separately as it handles user interactions, commands (like addcategory, removecategory, etc.), and uses Discord’s API.
- AgendaTS (for scheduling tasks like publishing categories, indexing, grabbing streams, releasing broadcasts, etc.)
- Auth, Broadcast, Category, Config, Group, Indexer, Indexers, Publishers, Releasers, Role, Scrapper, Templater, UUID – each representing different functions in the broadcast cycle.
- Bootstrappers & Config Managers: Under “src/bootstrappers” and “src/config”, these components perform initial configuration and setup at startup. They ensure the environment is properly loaded.
- Database (MongoDB as per runtime env variables like MONGO_URL, MONGO_DB, etc.)
- External broadcasting or notification services (Discord’s webhook/bot, Jellyfin as a releaser, Gotify, and (soon) Matrix)
- VPN/Wireguard: Represent the networking component that checks connectivity via the “gateway.sh” script in Docker.
- Infrastructure & Deployment Containers: Include Docker and docker-compose as encompassing the service’s server, workers, and bootstrap containers. This will show that the entire architecture is containerized and scalable.

##### Relationships and Interactions
- The Discord bot interacts with the API layer and feeds commands into the various modules.
- The API endpoints communicate with the underlying modules (e.g., broadcast, category, indexer) and schedule tasks via AgendaTS.
- The scheduler (AgendaTS) triggers tasks that interact with the scrappers, indexers, publishers, and releasers.
- Bootstrappers initiate the configuration at startup, ensuring that modules and services like the database and external APIs are correctly configured.
- Docker orchestration: Represent the overall container environment and networking (for example, linking the Broadcastarr container with MongoDB and the Wireguard VPN container).

##### Important Architectural Patterns/Principles
- Modular Design: The clean separation into modules (organized under “src/modules”), each encapsulating a specific business domain (e.g., AgendaTS, scrapper, publishers, indexers) is key.
- Task Scheduling: The system leverages scheduled tasks (AgendaTS) to manage asynchronous workflows. Show the scheduler as an orchestration engine.
- Containerization and Scalability: Indicate that a Docker compose setup is used to deploy multiple instances (workers and server) and that the service is designed for horizontal scaling.

##### Relevant Technologies and Frameworks
- Node.js as the runtime environment (implied by the file structure and .ts files).
- Docker/Docker Compose (multiple YAML configurations and the Dockerfile).
- Environment variables (.env files) used for runtime and bootstrap configurations.
- Potential use of Express or similar frameworks for the HTTP API routes (as per "src/routes" structure).
- Messaging/notification integrations like Discord, Jellyfin, Gotify, Matrix.
- MongoDB for data persistence (as seen from runtime configuration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client & API Layer
    subgraph "Client & API Layer"
        DBOT["Discord Bot (Client Interface)"]:::client
        API["API Gateway / HTTP Routes"]:::api
    end

    %% Core Business Logic Modules
    subgraph "Core Modules"
        BST["Bootstrappers & Config Managers"]:::module
        AT["AgendaTS Scheduler"]:::module
        AUTH["Auth Module"]:::module
        BROAD["Broadcast Module"]:::module
        CAT["Category Module"]:::module
        CONF["Config Module"]:::module
        GROUP["Group Module"]:::module
        INDEX["Indexer Module"]:::module
        INDEXERS["Indexers Module"]:::module
        PUB["Publishers Module"]:::module
        REL["Releasers Module"]:::module
        ROLE["Role Module"]:::module
        SCRAP["Scrapper Module"]:::module
        TEMP["Templater Module"]:::module
        UUID["UUID Module"]:::module
    end

    %% External Integrations
    subgraph "External Integrations"
        DISAPI["Discord API"]:::external
        JELLY["Jellyfin Integration"]:::external
        GOTIFY["Gotify Integration"]:::external
        MONGO["MongoDB"]:::db
        VPN["VPN/Wireguard Gateway"]:::external
    end

    %% Infrastructure & Deployment
    subgraph "Deployment Infrastructure"
        DOCKER["Docker Containers (Server/Worker/Bootstrap)"]:::infra
    end

    %% Relationships - Client & API to Core Modules
    DBOT -->|"commands"| API
    API -->|"init_config"| BST
    BST -->|"loads"| AT
    BST -->|"loads"| AUTH
    BST -->|"loads"| BROAD
    BST -->|"loads"| CAT
    BST -->|"loads"| CONF
    BST -->|"loads"| GROUP
    BST -->|"loads"| INDEX
    BST -->|"loads"| INDEXERS
    BST -->|"loads"| PUB
    BST -->|"loads"| REL
    BST -->|"loads"| ROLE
    BST -->|"loads"| SCRAP
    BST -->|"loads"| TEMP
    BST -->|"loads"| UUID

    %% Relationships - Task Scheduling
    AT -->|"triggers_scrape"| SCRAP
    AT -->|"triggers_index"| INDEX
    AT -->|"triggers_publish"| PUB
    AT -->|"triggers_release"| REL

    %% Relationships - API & Modules to External Integrations
    API -->|"db_request"| MONGO
    API -->|"notify"| GOTIFY
    BROAD -->|"publish_to"| DISAPI
    CAT -->|"sync_with"| JELLY

    %% Relationships - Infrastructure orchestration
    DOCKER -->|"orchestrates"| DBOT
    DOCKER -->|"orchestrates"| API
    DOCKER -->|"orchestrates"| BST
    DOCKER -->|"orchestrates"| MONGO
    DOCKER -->|"orchestrates"| VPN

    %% Click Events
    click DBOT "https://github.com/billos/broadcastarr/blob/main/src/bot/discord.ts"
    click DBOT "https://github.com/billos/broadcastarr/tree/main/src/bot/commands/"
    click API "https://github.com/billos/broadcastarr/tree/main/src/routes"
    click AT "https://github.com/billos/broadcastarr/tree/main/src/modules/agenda"
    click AUTH "https://github.com/billos/broadcastarr/tree/main/src/modules/auth"
    click BROAD "https://github.com/billos/broadcastarr/tree/main/src/modules/broadcast"
    click CAT "https://github.com/billos/broadcastarr/tree/main/src/modules/category"
    click CONF "https://github.com/billos/broadcastarr/tree/main/src/modules/config"
    click CONF "https://github.com/billos/broadcastarr/tree/main/src/config"
    click GROUP "https://github.com/billos/broadcastarr/tree/main/src/modules/group"
    click INDEX "https://github.com/billos/broadcastarr/tree/main/src/modules/indexer"
    click INDEXERS "https://github.com/billos/broadcastarr/tree/main/src/modules/indexers"
    click PUB "https://github.com/billos/broadcastarr/tree/main/src/modules/publishers"
    click REL "https://github.com/billos/broadcastarr/tree/main/src/modules/releasers"
    click ROLE "https://github.com/billos/broadcastarr/tree/main/src/modules/role"
    click SCRAP "https://github.com/billos/broadcastarr/tree/main/src/modules/scrapper"
    click TEMP "https://github.com/billos/broadcastarr/tree/main/src/modules/templater"
    click UUID "https://github.com/billos/broadcastarr/tree/main/src/modules/uuid"
    click BST "https://github.com/billos/broadcastarr/tree/main/src/bootstrappers"
    click BST "https://github.com/billos/broadcastarr/tree/main/src/config"
    click DISAPI "https://github.com/billos/broadcastarr/blob/main/src/api/discord.ts"
    click JELLY "https://github.com/billos/broadcastarr/blob/main/src/api/jellyfin.ts"
    click GOTIFY "https://github.com/billos/broadcastarr/blob/main/src/api/gotify.ts"
    click VPN "https://github.com/billos/broadcastarr/blob/main/scripts/gateway.sh"
    click DOCKER "https://github.com/billos/broadcastarr/tree/main/Dockerfile"

    %% Styles
    classDef client fill:#FFCC00,stroke:#333,stroke-width:2px,color:#000;
    classDef api fill:#66CC66,stroke:#333,stroke-width:2px,color:#000;
    classDef module fill:#FF9999,stroke:#333,stroke-width:2px,color:#000;
    classDef external fill:#CCCCFF,stroke:#333,stroke-width:2px,color:#000;
    classDef db fill:#FFEE99,stroke:#333,stroke-width:2px,color:#000;
    classDef infra fill:#DDDDDD,stroke:#333,stroke-width:2px,color:#000;
```
