# streamelements/widgets architecture

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

- Interactive diagram: https://gitdiagram.com/streamelements/widgets
- Repository: https://github.com/streamelements/widgets

## Overview

##### Main Components

- Widget Repository Core:
- A central component representing this code repository where all the custom widgets reside.
- Each widget (e.g., AlertboxTextFit, CustomChat, ChatPoll, etc.) can be shown as independent modules or blocks.
- A consistent structure for every widget module (each containing widget.html, widget.js, widget.css, and widget.json).

- Documentation and Guidelines:
- A component for documentation (the docs folder, toc.json, and supplemental READMEs) that guides the widget development and integration process.
- That these resources define standards and best practices for widget creation and for using custom code in alertboxes, overlays, and other parts.

- GitHub Configuration and Workflows:
- A component for version control and CI workflows (.github directory and associated workflow files such as code analysis and PR title checkers).
- How Pull Requests and quality assurance processes integrate with the repository’s maintenance.

- External Integration Point:
- The StreamElements platform where these custom widgets are intended to be deployed.

##### Relationships and Interactions

- Community Contribution Flow:
- Developers or community members as external contributors who fork, modify, or add widget modules.
- Contributors via 'Pull Requests' that flow into the GitHub repository – then processed by automated GitHub workflows (e.g., code analysis using the provided yml files).

- Modular Architecture:
- Demonstrate that each widget module is independent but follows a standardized structure.

- Documentation and Guidelines:
- Link the docs folder to each widget to indicate that documentation governs widget structure and custom code practices.

##### Architectural Patterns and Design Principles

- Plugin/Modular Design:

- Standardization:
- The repository follows a standard layout for each widget that includes HTML (structure), CSS (presentation), JavaScript (behavior), and a JSON configuration.

- Continuous Integration and Quality Assurance:
- The presence of GitHub workflows (CI/CD pipelines, code analysis tasks) should be highlighted. Represent these as part of the “Quality Gate” that each contribution must pass before becoming part of the main repo.

- Component "Community Contributors":

- Component "GitHub Repository":
- Split into sub-components:
- "Widget Modules" (each widget is a node).
- "Documentation (docs folder, toc.json, README files)" tied to the widgets.
- "GitHub Workflows" (specifically the .github directory with its workflows for automation, code analysis, and PR checks).

- Component "StreamElements Platform":

- Data and Control Flows:
- How pull requests (with their associated CI checks) get merged.
- How widget structure (the standardized set of files) feeds into the widget system that the StreamElements platform uses.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Contributors
    subgraph "Top Layer: Contributors"
        CC["Community Contributors"]:::community
    end

    %% Middle Layer: GitHub Repository
    subgraph "Middle Layer: GitHub Repository"
        %% Widget Modules Subgraph
        subgraph "Widget Modules"
            AWT["AlertboxTextFit (Widget)"]:::widget
            CCW["CustomChat (Widget)"]:::widget
            CP["ChatPoll (Widget)"]:::widget
        end
        %% Documentation & Guidelines Subgraph
        subgraph "Documentation & Guidelines"
            Docs["docs (Documentation)"]:::docs
            TOC["toc.json (DocConfig)"]:::docs
        end
        %% CI/CD Workflows Subgraph
        subgraph "CI/CD Workflows"
            GH[".github (CI/CD)"]:::ci
            WF[".github/workflows (Workflows)"]:::ci
            CodeQL["codeql-analysis.yml"]:::ci
            PRChecker["pr-title-checker.yml"]:::ci
        end
    end

    %% Bottom Layer: External Integration
    subgraph "Bottom Layer: External Integration"
        SE["StreamElements Platform"]:::external
    end

    %% Relationships and Data Flow
    CC -->|"pullRequests"| AWT
    CC -->|"pullRequests"| CCW
    CC -->|"pullRequests"| CP

    Docs -->|"definesStandards"| AWT
    Docs -->|"definesStandards"| CCW
    Docs -->|"definesStandards"| CP

    WF -->|"QAworkflow"| AWT
    WF -->|"QAworkflow"| CCW
    WF -->|"QAworkflow"| CP

    AWT -->|"deploys"| SE
    CCW -->|"deploys"| SE
    CP -->|"deploys"| SE

    GH -->|"triggers"| WF
    WF -->|"includes"| CodeQL
    WF -->|"includes"| PRChecker

    %% Click Events for Component Mapping
    click AWT "https://github.com/streamelements/widgets/tree/master/AlertboxTextFit"
    click CCW "https://github.com/streamelements/widgets/tree/master/CustomChat"
    click CP "https://github.com/streamelements/widgets/tree/master/ChatPoll"
    click Docs "https://github.com/streamelements/widgets/tree/master/docs/"
    click TOC "https://github.com/streamelements/widgets/blob/master/toc.json"
    click GH "https://github.com/streamelements/widgets/blob/master/.github"
    click WF "https://github.com/streamelements/widgets/tree/master/.github/workflows"
    click CodeQL "https://github.com/streamelements/widgets/blob/master/.github/workflows/codeql-analysis.yml"
    click PRChecker "https://github.com/streamelements/widgets/blob/master/.github/workflows/pr-title-checker.yml"

    %% Styles
    classDef community fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef widget fill:#A3E4D7,stroke:#117864,stroke-width:2px;
    classDef docs fill:#ABEBC6,stroke:#1E8449,stroke-width:2px;
    classDef ci fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
