# louscmh/gts-stream architecture

> Architecture diagram of the GitHub repository louscmh/gts-stream, 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/louscmh/gts-stream
- Repository: https://github.com/louscmh/gts-stream

## Overview

##### Main Components
- Data & Configuration Layer:
- _data folder: Contains JSON files for API keys (api.json), beatmaps, match details, qualification data, seeding, stage information, and OBS scene configurations.
- This layer feeds configuration and game data that drive scene changes and interactivity.

- Shared Assets:
- _shared_assets directory: Contains design elements (animated videos, backgrounds, stingers), dependencies (JavaScript utilities like countUp.js, fetchData.js), fonts, and setup images.
- These assets are used by the overlays for visual and interactive elements.

- Overlay Scenes & Interfaces:
- overlay directory: Includes subdirectories for “match”, “schedule”, “seeding”, and “showcase”—each with its own HTML, JavaScript, CSS, and metadata files.
- Each of these serves as a distinct OBS scene that displays different phases of the event (e.g., match scene, intro scene, mappool overview, etc.).

- Main Entry / Static Landing:
- index.html at the project root might serve as an overall landing page or an access point to the overlay components.

- External Integration:
- tosu.exe: As described in the README, this external executable from a sister project (linked in the README) integrates the overlay within the streaming setup.
- osu! API: The overlay uses an API key (provided in api.json) to integrate and pull data from the osu! API.

##### Relationships and Interactions
- Data Flow:
- The JSON files in the _data folder feed relevant configuration, match details, and scene settings into the overlay components.
- Directional data flow should be shown from the “Data & Configuration Layer” to the “Overlay Scenes.”

- Asset Distribution:
- The _shared_assets folder supplies all design assets and dependencies to each overlay.

- External Triggers & Control:
- The control panel (described thoroughly in the README) is embedded within the interactive overlays. It manages manual scene switching, auto control toggles (for picking and scene transitions), and interactive match input.
- Connections from the “Overlay Scenes” to the “Control Panel”.
- Also, show the external integration with tosu.exe, which both prepares the static folder (with overlays) and interacts with the client (osu! client) to trigger scene changes.

- External API Interaction:
- A link from the “Overlay Application/Data Layer” to the osu! API (external service) to indicate the use of API keys and external data retrieval.

##### Architectural Patterns and Design Principles
- Modular Design:
- Each overlay (match, schedule, seeding, showcase) is modular, encapsulated in its own directory with dedicated HTML, JS, and CSS files. Reflect these as distinct modules/components.

- Separation of Concerns:
- Data/configuration (JSON resources) is clearly separated from presentation (HTML overlays) and asset management.

- Client-Side Execution:
- The system is largely a static, client-side application rendered in OBS and driven by JavaScript. Emphasize that no server-side processing is required.

- Dynamic Scene Transitions:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Configuration Layer
    subgraph "Data & Configuration"
        data["_data: JSON Configuration Files"]:::configuration
    end

    %% Shared Assets Layer
    subgraph "Shared Assets"
        assets["_shared_assets: Design Assets & Dependencies"]:::asset
    end

    %% Main Entry / Landing Page
    subgraph "Main Entry"
        landing["index.html: Landing Page"]:::landing
    end

    %% Overlay Scenes & Control Panel
    subgraph "Overlay Scenes"
        match["Match Overlay (overlay/match)"]:::overlay
        schedule["Schedule Overlay (overlay/schedule)"]:::overlay
        seeding["Seeding Overlay (overlay/seeding)"]:::overlay
        showcase["Showcase Overlay (overlay/showcase)"]:::overlay
        control["Control Panel"]:::control
    end

    %% External Integrations
    subgraph "External Integrations"
        tosu["tosu.exe"]:::integration
        osuapi["osu! API"]:::integration
        readme["README.md (Integration Documentation)"]:::integration
    end

    %% Connections from Data & Config to Overlays
    data -->|"feedsConfiguration"| match
    data -->|"feedsConfiguration"| schedule
    data -->|"feedsConfiguration"| seeding
    data -->|"feedsConfiguration"| showcase

    %% Connections from Shared Assets to Overlays
    assets -->|"providesAssets"| match
    assets -->|"providesAssets"| schedule
    assets -->|"providesAssets"| seeding
    assets -->|"providesAssets"| showcase

    %% Landing page routes overlays
    landing -->|"accesses"| match
    landing -->|"accesses"| schedule
    landing -->|"accesses"| seeding
    landing -->|"accesses"| showcase

    %% Overlays interact with Control Panel
    match -->|"sceneInfo"| control
    schedule -->|"sceneInfo"| control
    seeding -->|"sceneInfo"| control
    showcase -->|"sceneInfo"| control

    %% Control Panel triggers external integration (tosu.exe)
    control -->|"triggersSceneChange"| tosu

    %% Data layer provides API key to osu! API
    data -->|"providesAPIKey"| osuapi

    %% Control Panel manages transitions among overlays
    control -->|"managesTransition"| match
    control -->|"managesTransition"| schedule
    control -->|"managesTransition"| seeding
    control -->|"managesTransition"| showcase

    %% README documents integration details with external tools
    readme ---|"documentsIntegration"| tosu
    readme ---|"documentsIntegration"| osuapi

    %% Click Events
    click data "https://github.com/louscmh/gts-stream/tree/main/_data"
    click assets "https://github.com/louscmh/gts-stream/tree/main/_shared_assets"
    click match "https://github.com/louscmh/gts-stream/tree/main/overlay/match"
    click schedule "https://github.com/louscmh/gts-stream/tree/main/overlay/schedule"
    click seeding "https://github.com/louscmh/gts-stream/tree/main/overlay/seeding"
    click showcase "https://github.com/louscmh/gts-stream/tree/main/overlay/showcase"
    click landing "https://github.com/louscmh/gts-stream/blob/main/index.html"
    click readme "https://github.com/louscmh/gts-stream/blob/main/README.md"

    %% Styling
    classDef configuration fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef asset fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef landing fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef overlay fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef control fill:#f5c6cb,stroke:#721c24,stroke-width:2px;
    classDef integration fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
