# locussphere/streampause architecture

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

- Interactive diagram: https://gitdiagram.com/locussphere/streampause
- Repository: https://github.com/locussphere/streampause

## Overview

##### What this project is (type + purpose)
From the README and file tree, **`streampause` is a lightweight, static, browser-based “stream modules”/overlay toolkit**. It looks like a **pure front-end static site** (no backend service, no server code beyond static hosting) that provides different “screens” (e.g., BRB, visualizers) as separate HTML modules.

Key indicators:
- Top-level `index.html`, `app.js`, `style.css` ⇒ classic static web app.
- `screens/` contains multiple standalone HTML pages ⇒ each “module” is likely a self-contained screen/overlay.
- `screens.json` ⇒ registry/config describing available screens (names, paths, metadata).
- `.github/workflows/static.yml` ⇒ automated static deployment (likely GitHub Pages).

##### Runtime (what runs in the browser)
- **Entry point UI / launcher**
- `index.html` (top-level)
- `app.js` (top-level)
- `style.css` (top-level)
- **Screens / modules**
- `screens/index.html` (possibly a directory index or a screen gallery)
- `screens/loficalm.html` (example module)
- (more screens likely to be added here)
- **Screen registry/config**
- `screens.json` (source of truth for what screens exist and how to link/load them)

##### Delivery (how it’s published)
- **Static hosting pipeline**
- `.github/workflows/static.yml` (CI/CD)
- **Hosting target**
- Not explicitly in repo, but implied: GitHub Pages or another static host.

Use a “static web module platform” framing: the core architecture is **Browser + Static Host + Screen Modules + Config**.

##### User / Streamer
- Uses a browser or OBS browser source to load the site/screen.
##### Static Host (e.g., GitHub Pages)
- Serves `index.html`, `app.js`, `style.css`, `screens.json`, and `screens/*.html`.
##### Browser Runtime
- Loads and executes `app.js`
- Fetches and parses `screens.json`
- Renders the main UI and/or loads individual screens
##### Screen Modules (HTML screens)
- `screens/loficalm.html`, etc.
- May reference shared `style.css` and/or their own embedded JS/CSS.
##### Configuration / Registry
- `screens.json` as the catalog of modules

##### User → Browser
- “Open overlay URL” / “Load in OBS Browser Source”
##### Browser → Static Host
- HTTP GET `index.html`
- HTTP GET `app.js`, `style.css`
- HTTP GET `screens.json`
##### app.js → screens.json
- “Fetch screen registry”
##### Browser/app.js → Screen Module HTML
- “Navigate to / load / embed screen HTML”
- If the app uses navigation: `index.html` links to `screens/<screen>.html`

Optional (only if supported by code once inspected):
- **Screen module → Web APIs**
- Audio API, Canvas/WebGL, etc. (common for visualizers). If present, show as “Browser Web APIs”.

##### Architectural pattern worth calling out
- **Static, client-only architecture**
- All logic runs in-browser; hosting is a dumb file server.
- **Module/plug-in style via file + registry**
- A new screen by:
1) creating `screens/<name>.html`
2) adding/adjusting an entry in `screens.json`
- **Shared assets**
- Shared `style.css` (and potentially shared JS patterns in `app.js`) provide consistency across screens.

##### Technologies to label (based on evidence)
- **HTML/CSS/JavaScript**
- **Static hosting** (GitHub Pages implied by `.github/workflows/static.yml`)
- **GitHub Actions** (deployment pipeline)

##### Diagramming conventions (make it unambiguous and detailed)
To satisfy “be very detailed, separate into as many components as possible”:

##### Labels
- Use file-level labels where it helps accuracy:
- “Entry: `/index.html`”
- “Logic: `/app.js`”
- “Styles: `/style.css`”
- “Registry: `/screens.json`”
- “Module: `/screens/loficalm.html`”

- “HTTP GET /screens.json”
- “Loads module HTML”
- “Renders UI”
- “User selects screen”

##### Don’t forget deployment (it’s part of the real architecture)

- “GitHub Repo”
→ “GitHub Actions: `.github/workflows/static.yml`”
→ “Static Host (GitHub Pages)”
→ “Serves versioned static assets to Browser”

- Confirm how screens are loaded by reading `app.js`:
- navigation vs iframe vs dynamic fetch/innerHTML
- Confirm what fields exist in `screens.json`:
- name, path, tags, default screen, ordering, etc.
- Check whether screens share `style.css` or have per-screen styling.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% System Context (Level 1)
  %% =========================================================
  subgraph "System Context (Level 1)"
    U["Streamer / Creator"]:::external
    OBS["OBS Browser Source / Web Browser"]:::external
    SP["streampause (Static Overlay Toolkit)"]:::system
  end

  U -->|"configures_overlay_URL"| OBS
  OBS -->|"loads_static_site"| SP

  %% =========================================================
  %% Delivery & Hosting (CI/CD + Static Host)
  %% =========================================================
  subgraph "Delivery & Hosting"
    subgraph "Source Control"
      REPO["GitHub Repository"]:::repo
      WF["GitHub Actions Workflow (static deploy)"]:::cicd
    end

    HOST["Static Host (GitHub Pages / Static File Server)"]:::host
  end

  REPO -->|"triggers_CI_on_push"| WF
  WF -->|"publishes_static_assets"| HOST
  SP -->|"hosted_as_static_files"| HOST

  %% =========================================================
  %% Runtime in Browser (Level 2 + Level 3)
  %% =========================================================
  subgraph "Browser Runtime (Level 2 + Level 3)"
    BR["Browser Runtime"]:::runtime

    subgraph "Entry App (Static Assets)"
      IDX["Entry HTML (index.html)"]:::static
      CSS["Shared Styles (style.css)"]:::static
      JSON["Screen Registry (screens.json)"]:::config
    end

    subgraph "Client-side App Logic (app.js)"
      APP["Application Script (app.js)"]:::logic
      INIT["Bootstrap / Init (DOMContentLoaded)"]:::logic
      LOADER["Screen Registry Loader (fetch + parse)"]:::logic
      ROUTER["Router / Screen Selector (UI + URL params)"]:::logic
      RENDER["Renderer (DOM update + module loader)"]:::logic
    end

    subgraph "Screen Modules (standalone HTML pages)"
      SDIR["Screens Directory (screens/)"]:::module
      SIDX["Screens Index / Gallery (screens/index.html)"]:::module
      SLOFI["Example Screen: LoFi Calm (screens/loficalm.html)"]:::module
      SMORE["Additional Screens (screens/*.html)"]:::module
    end

    WEBAPI["Browser Web APIs (Optional: Audio/Canvas/WebGL)"]:::webapi
  end

  %% =========================================================
  %% Browser <-> Host fetches
  %% =========================================================
  OBS -->|"HTTP_GET_/index.html"| HOST
  OBS -->|"HTTP_GET_/app.js"| HOST
  OBS -->|"HTTP_GET_/style.css"| HOST
  OBS -->|"HTTP_GET_/screens.json"| HOST
  OBS -->|"HTTP_GET_/screens/*.html"| HOST

  HOST -->|"serves_index.html"| IDX
  HOST -->|"serves_style.css"| CSS
  HOST -->|"serves_screens.json"| JSON
  HOST -->|"serves_screen_modules"| SDIR
  HOST -->|"serves_app.js"| APP

  %% =========================================================
  %% In-browser wiring
  %% =========================================================
  IDX -->|"loads_script"| APP
  IDX -->|"links_stylesheet"| CSS

  APP -->|"runs_in"| BR
  INIT -->|"bootstraps"| LOADER
  LOADER -->|"fetches_registry"| JSON
  LOADER -->|"provides_screen_list"| ROUTER
  ROUTER -->|"user_selects_screen_or_route"| RENDER
  RENDER -->|"loads_or_embeds_module_HTML"| SDIR
  RENDER -->|"navigates_to_or_embeds"| SIDX
  RENDER -->|"navigates_to_or_embeds"| SLOFI
  RENDER -->|"navigates_to_or_embeds"| SMORE

  %% Shared styling (optional/typical)
  SDIR -->|"may_reference_shared_styles"| CSS

  %% Optional: screen modules may use Web APIs
  SDIR -.->|"optional_visualizer_APIs"| WEBAPI

  %% =========================================================
  %% Click Events (from component_mapping)
  %% =========================================================
  click IDX "https://github.com/locussphere/streampause/blob/main//index.html"
  click APP "https://github.com/locussphere/streampause/blob/main//app.js"
  click CSS "https://github.com/locussphere/streampause/blob/main//style.css"
  click JSON "https://github.com/locussphere/streampause/blob/main//screens.json"
  click SDIR "https://github.com/locussphere/streampause/tree/main//screens/"
  click SIDX "https://github.com/locussphere/streampause/blob/main//screens/index.html"
  click SLOFI "https://github.com/locussphere/streampause/blob/main//screens/loficalm.html"
  click WF "https://github.com/locussphere/streampause/blob/main//.github/workflows/static.yml"

  %% =========================================================
  %% Styles
  %% =========================================================
  classDef external fill:#F3F4F6,stroke:#6B7280,stroke-width:1px,color:#111827;
  classDef system fill:#E0F2FE,stroke:#0284C7,stroke-width:1.5px,color:#0B1220;
  classDef repo fill:#FFF7ED,stroke:#C2410C,stroke-width:1px,color:#111827;
  classDef cicd fill:#FFE4E6,stroke:#BE123C,stroke-width:1.5px,color:#111827;
  classDef host fill:#ECFDF5,stroke:#047857,stroke-width:1.5px,color:#052e2b;
  classDef runtime fill:#EEF2FF,stroke:#4338CA,stroke-width:1.5px,color:#111827;
  classDef static fill:#E0E7FF,stroke:#3730A3,stroke-width:1px,color:#111827;
  classDef logic fill:#DDD6FE,stroke:#6D28D9,stroke-width:1px,color:#111827;
  classDef config fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#111827;
  classDef module fill:#DCFCE7,stroke:#16A34A,stroke-width:1px,color:#052e2b;
  classDef webapi fill:#FAE8FF,stroke:#A21CAF,stroke-width:1px,color:#111827;
```
