gitchegumi/GitchAlerts

Watch

Fork 0

Add GitHub Pages user/developer guide and refactor Alerts/Overlay into canvas-based workspace #44

New issue

Closed

opened 2026-06-04 18:50:09 -05:00 by Gitchegumi · 1 comment

Gitchegumi commented

2026-06-04 18:50:09 -05:00

(Migrated from github.com)

Problem

GitchAlerts needs two related improvements before it is usable by anyone besides the person who built it:

A proper user's guide and developer guide hosted on GitHub Pages.
A complete refactor of the current Alerts and Overlay tabs.

Right now, the Overlay tab is not useful, and the Alerts tab is too cumbersome and confusing. The core workflow should feel closer to a StreamElements-style Element: the user manages streamable canvases, each canvas has a browser-source URL, and alert/event types are assigned to that canvas.

Reference for the product model: https://dev.streamelements.com/docs/widgets-elements-sdk/9do3bhwlp2fdt-introduction

Part 1: Documentation site

Create a documentation site hosted with GitHub Pages and linked from the GitchAlerts dashboard.

Requirements

Add a /docs documentation structure made from Markdown files.
Host the docs on GitHub Pages.
Add a dashboard link to the guide.
The guide should cover both end-user usage and development.
The docs should be easy to expand as the app changes.

Suggested docs structure

docs/
  index.md
  user-guide/
    getting-started.md
    dashboard.md
    canvases.md
    alerts.md
    browser-sources.md
    assets.md
    account-settings.md
    troubleshooting.md
  developer-guide/
    architecture.md
    local-development.md
    environment-variables.md
    database.md
    auth.md
    webhooks.md
    overlays-and-canvases.md
    deployment.md
    contributing.md

User guide should explain

What GitchAlerts is and what problem it solves.
How to sign in.
How to create and manage a canvas.
How to copy the canvas URL into OBS/streaming software as a browser source.
How to assign alert types to a canvas.
How to test alerts.
How asset storage works.
Basic troubleshooting.

Developer guide should explain

App architecture: web, ingress, worker, database, Redis, object storage.
Local development workflow.
Environment variables.
Auth/OIDC flow.
Webhook ingestion flow.
Alert/event routing model.
Canvas rendering model.
Deployment notes for Docker/TrueNAS/reverse proxy use.

Part 2: Refactor Alerts and Overlay tabs into a canvas workspace

Replace the current Alerts/Overlay experience with a canvas-centered workflow.

Desired user experience

When a user opens the Alerts tab, they should see:

Left panel: list of their canvases.
Top of main workspace: the selected canvas URL.
- This is the URL the user copies into OBS, Streamlabs, Twitch Studio, etc. as a browser source.
Middle workspace: selected canvas editor/preview area.
Right panel: list of Alert Types that can be linked to the selected canvas.

This should behave more like a StreamElements Element: one streamable canvas/browser-source URL, with alert/event types assigned to it.

Proposed information architecture

Left panel: Canvases

Show all canvases owned by the current user.
Support create, rename, duplicate, delete.
Show the active/selected canvas.
Include useful metadata such as name, orientation/size, and last updated date if available.

Main workspace

Show the selected canvas name.
Show/copy the canvas browser-source URL at the top.
Provide a preview area for the selected canvas.
Provide basic canvas settings:
- Name
- Slug or display key
- Width/height or preset layout sizes
- Background behavior, likely transparent by default
- Active/inactive status
Provide a test alert action for the selected canvas.

Right panel: Alert Types

Show available alert types, for example:
- Ko-fi tip
- Twitch follow
- Twitch sub
- Twitch cheer
- Twitch raid
- YouTube subscriber
- YouTube super chat
- Other future provider events
Allow multiple alert types to be assigned to the same canvas.
Allow the same alert type to be assigned to different canvases if the user wants.
Make the assignment state obvious.
Alert types should be configured per user/channel, not globally hardcoded.

Data model considerations

The implementation likely needs a clear separation between:

Canvas: the streamable browser-source surface.
AlertType: normalized event types such as kofi.tip, twitch.follow, etc.
CanvasAlertAssignment: many-to-many mapping between canvases and alert types.
AlertLayout or WidgetConfig: visual/layout configuration for how a specific alert type renders on a specific canvas.

This avoids forcing a one-alert-to-one-overlay model and supports assigning multiple alert types to the same canvas.

Routing / URLs

Each canvas needs a stable browser-source URL.
The URL should be copyable from the top of the workspace.
The browser-source URL should not expose the admin dashboard.
The URL should be safe to use in OBS and refresh without requiring dashboard login.
Use a display key/token/slug model as appropriate so the streamable URL is not predictable.

Example shape, not required:

/overlay/c/:displayKey

/canvas/:displayKey

Acceptance criteria

GitHub Pages documentation site exists and is published.
Dashboard includes a visible link to the guide.
Docs are written as Markdown files and include both user and developer sections.
Current Alerts/Overlay tabs are replaced or consolidated into a canvas-centered Alerts workspace.
User can create, select, rename, duplicate, and delete canvases.
Selected canvas shows a copyable browser-source URL at the top of the workspace.
User can copy the canvas URL and use it as a streaming browser source.
User can assign multiple alert types to one canvas.
User can assign the same alert type to multiple canvases if desired.
Right panel clearly shows which alert types are linked to the selected canvas.
Workspace includes a preview/test mechanism for the selected canvas.
Existing webhook/event handling continues to work after the refactor.
Existing auth/OIDC behavior is not broken.
Existing Docker deployment remains functional.

Notes

This is not a small cosmetic change. Treat it as an information architecture and workflow refactor. The current tab split is the wrong mental model. The primary object should be the canvas/browser-source element, and alerts should attach to that canvas.

## Problem GitchAlerts needs two related improvements before it is usable by anyone besides the person who built it: 1. A proper user's guide and developer guide hosted on GitHub Pages. 2. A complete refactor of the current Alerts and Overlay tabs. Right now, the Overlay tab is not useful, and the Alerts tab is too cumbersome and confusing. The core workflow should feel closer to a StreamElements-style Element: the user manages streamable canvases, each canvas has a browser-source URL, and alert/event types are assigned to that canvas. Reference for the product model: https://dev.streamelements.com/docs/widgets-elements-sdk/9do3bhwlp2fdt-introduction ## Part 1: Documentation site Create a documentation site hosted with GitHub Pages and linked from the GitchAlerts dashboard. ### Requirements - Add a `/docs` documentation structure made from Markdown files. - Host the docs on GitHub Pages. - Add a dashboard link to the guide. - The guide should cover both end-user usage and development. - The docs should be easy to expand as the app changes. ### Suggested docs structure ```text docs/ index.md user-guide/ getting-started.md dashboard.md canvases.md alerts.md browser-sources.md assets.md account-settings.md troubleshooting.md developer-guide/ architecture.md local-development.md environment-variables.md database.md auth.md webhooks.md overlays-and-canvases.md deployment.md contributing.md ``` ### User guide should explain - What GitchAlerts is and what problem it solves. - How to sign in. - How to create and manage a canvas. - How to copy the canvas URL into OBS/streaming software as a browser source. - How to assign alert types to a canvas. - How to test alerts. - How asset storage works. - Basic troubleshooting. ### Developer guide should explain - App architecture: web, ingress, worker, database, Redis, object storage. - Local development workflow. - Environment variables. - Auth/OIDC flow. - Webhook ingestion flow. - Alert/event routing model. - Canvas rendering model. - Deployment notes for Docker/TrueNAS/reverse proxy use. ## Part 2: Refactor Alerts and Overlay tabs into a canvas workspace Replace the current Alerts/Overlay experience with a canvas-centered workflow. ### Desired user experience When a user opens the Alerts tab, they should see: 1. **Left panel:** list of their canvases. 2. **Top of main workspace:** the selected canvas URL. - This is the URL the user copies into OBS, Streamlabs, Twitch Studio, etc. as a browser source. 3. **Middle workspace:** selected canvas editor/preview area. 4. **Right panel:** list of Alert Types that can be linked to the selected canvas. This should behave more like a StreamElements Element: one streamable canvas/browser-source URL, with alert/event types assigned to it. ### Proposed information architecture #### Left panel: Canvases - Show all canvases owned by the current user. - Support create, rename, duplicate, delete. - Show the active/selected canvas. - Include useful metadata such as name, orientation/size, and last updated date if available. #### Main workspace - Show the selected canvas name. - Show/copy the canvas browser-source URL at the top. - Provide a preview area for the selected canvas. - Provide basic canvas settings: - Name - Slug or display key - Width/height or preset layout sizes - Background behavior, likely transparent by default - Active/inactive status - Provide a test alert action for the selected canvas. #### Right panel: Alert Types - Show available alert types, for example: - Ko-fi tip - Twitch follow - Twitch sub - Twitch cheer - Twitch raid - YouTube subscriber - YouTube super chat - Other future provider events - Allow multiple alert types to be assigned to the same canvas. - Allow the same alert type to be assigned to different canvases if the user wants. - Make the assignment state obvious. - Alert types should be configured per user/channel, not globally hardcoded. ### Data model considerations The implementation likely needs a clear separation between: - `Canvas`: the streamable browser-source surface. - `AlertType`: normalized event types such as `kofi.tip`, `twitch.follow`, etc. - `CanvasAlertAssignment`: many-to-many mapping between canvases and alert types. - `AlertLayout` or `WidgetConfig`: visual/layout configuration for how a specific alert type renders on a specific canvas. This avoids forcing a one-alert-to-one-overlay model and supports assigning multiple alert types to the same canvas. ### Routing / URLs - Each canvas needs a stable browser-source URL. - The URL should be copyable from the top of the workspace. - The browser-source URL should not expose the admin dashboard. - The URL should be safe to use in OBS and refresh without requiring dashboard login. - Use a display key/token/slug model as appropriate so the streamable URL is not predictable. Example shape, not required: ```text /overlay/c/:displayKey ``` or ```text /canvas/:displayKey ``` ### Acceptance criteria - [ ] GitHub Pages documentation site exists and is published. - [ ] Dashboard includes a visible link to the guide. - [ ] Docs are written as Markdown files and include both user and developer sections. - [ ] Current Alerts/Overlay tabs are replaced or consolidated into a canvas-centered Alerts workspace. - [ ] User can create, select, rename, duplicate, and delete canvases. - [ ] Selected canvas shows a copyable browser-source URL at the top of the workspace. - [ ] User can copy the canvas URL and use it as a streaming browser source. - [ ] User can assign multiple alert types to one canvas. - [ ] User can assign the same alert type to multiple canvases if desired. - [ ] Right panel clearly shows which alert types are linked to the selected canvas. - [ ] Workspace includes a preview/test mechanism for the selected canvas. - [ ] Existing webhook/event handling continues to work after the refactor. - [ ] Existing auth/OIDC behavior is not broken. - [ ] Existing Docker deployment remains functional. ### Notes This is not a small cosmetic change. Treat it as an information architecture and workflow refactor. The current tab split is the wrong mental model. The primary object should be the canvas/browser-source element, and alerts should attach to that canvas.

Gitchegumi commented

2026-06-04 22:19:01 -05:00

(Migrated from github.com)

The Integrations menu should be nested under Settings.

Rationale

Integrations are configuration/admin concerns, not a primary workspace destination. Moving them under Settings keeps the main navigation focused on the user’s active streaming workflow, especially if the Alerts experience is being refactored around canvases.

Acceptance criteria

Integrations is removed as a top-level navigation item.
Integrations appears under Settings.
Existing integration configuration pages remain accessible.
Existing routes, auth guards, and saved integration settings continue to work.
Any dashboard links or breadcrumbs are updated to reflect the new Settings > Integrations location.

## Additional navigation requirement The **Integrations** menu should be nested under **Settings**. ### Rationale Integrations are configuration/admin concerns, not a primary workspace destination. Moving them under Settings keeps the main navigation focused on the user’s active streaming workflow, especially if the Alerts experience is being refactored around canvases. ### Acceptance criteria - [ ] Integrations is removed as a top-level navigation item. - [ ] Integrations appears under Settings. - [ ] Existing integration configuration pages remain accessible. - [ ] Existing routes, auth guards, and saved integration settings continue to work. - [ ] Any dashboard links or breadcrumbs are updated to reflect the new Settings > Integrations location.

No milestone

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

gitchegumi/GitchAlerts#44

No description provided.

Rows
Columns