# sin-1337/crabs architecture

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

- Interactive diagram: https://gitdiagram.com/sin-1337/crabs
- Repository: https://github.com/sin-1337/crabs

## Overview

##### Project type and purpose
- This is an open-source browser “user script” (aka a front-end extension) named **CRABS** (Crazy Roster Add-on).

##### File structure
– Top‐level build & config files:
- `package.json` / `rollup.config.mjs` (build bundler)
- `tsconfig.json` / `eslint.config.mjs` (TypeScript + linting)
- `crabsloader.user.js` (the installer/loader user‐script)
– `src/` directory:
- `main.ts` – entry point, initializes the script when loaded in the browser
- `base.ts` + `globals.d.ts` – shared utilities & ambient types for the BC environment
- `modules/` – feature modules: `banner.ts`, `roster.ts`, `help.ts`, `whisperplus.ts`, `dom.ts`
- `modules/templates/` – per-module HTML & CSS templates
- `templates/` – global wrapper HTML & CSS
- `types/` – custom type definitions for HTML and CSS imports

##### README insights
- Usage instructions describe three installation methods (FUSAM addon, Violent/Tampermonkey, bookmarklet).

a. Main components:
1. **Loader** (`crabsloader.user.js` / bookmarklet)
2. **Build Pipeline** (Rollup + TS → `bundle.js`)
3. **Browser Environment** (Bondage Club page & global JS API)
4. **CRABS Runtime** (the injected `bundle.js` running in page context)
– **main.ts** initializer
– **Module Registry** (manages feature modules)
– **Feature Modules**
- Banner Module
- Roster Module
- Whisper+ Module
- Help Module
- DOM Utilities Module
– **Templates & Styles** (HTML/CSS assets loaded by modules)
5. **User Interactions** (chat commands, DOM clicks)

b. Relationships & interactions:
- **Loader** fetches & executes `bundle.js` in BC page.
- **main.ts** boots, reads `globals` for BC APIs, registers modules.
- **User types** commands in chat or clicks UI → **bundle** intercepts events via `dom.ts`.
- **Modules** parse commands, fetch appropriate HTML templates & CSS, then manipulate DOM to render overlays or banners.
- **Templates** are embedded strings that modules inject into the page.
- **Build Pipeline** compiles TS + templates into a flat JS bundle.

c. Architectural patterns & principles:
- **Modular design**: each feature in its own file + templates.
- **Separation of concerns**: `dom.ts` for low-level DOM ops, modules for feature logic, templates purely for view.
- **Single-bundle deployment**: Rollup produces one user-scriptable bundle.
- **Progressive enhancement**: non-intrusive injection into existing game UI.

d. Key technologies/frameworks/libraries:
- TypeScript (static types)
- Rollup (module bundler)
- FUSAM / GreaseMonkey API (optional)
- Vanilla DOM APIs

##### Final recommendations
- Every distinct part: loader, build pipeline, runtime modules, templates, and the target environment.
- **data/control flow**: how a chat command or click travels from browser → your code → DOM update.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Browser["Bondage Club Page"]:::external
    BrowserAPI["Browser APIs (FUSAM/GM)"]:::external

    %% Loader
    Loader["Loader (crabsloader.user.js)"]:::runtime

    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        packJson["package.json"]:::build
        rollupConfig["rollup.config.mjs"]:::build
        tsconfig["tsconfig.json"]:::build
        eslint["eslint.config.mjs"]:::build
        Bundle[(bundle.js)]:::build
    end

    %% CRABS Runtime
    subgraph "CRABS Runtime (injected bundle.js)"
        direction TB
        Main["main.ts"]:::runtime
        Base["base.ts"]:::runtime
        Globals["globals.d.ts"]:::runtime
        CSSdts["css.d.ts"]:::runtime
        HTMLdts["html.d.ts"]:::runtime
        Registry["Module Registry"]:::runtime

        subgraph "Feature Modules"
            direction TB
            Banner["Banner Module"]:::runtime
            Roster["Roster Module"]:::runtime
            Whisper["Whisper+ Module"]:::runtime
            Help["Help Module"]:::runtime
            DOM["DOM Utilities Module"]:::runtime
        end

        subgraph "Module Templates & Styles"
            direction TB
            bannerHTML["banner.html"]:::runtime
            bannerCSS["banner.css"]:::runtime
            rosterHTML["roster.html"]:::runtime
            rosterCSS["roster.css"]:::runtime
            rosterCards["roster_cards.html"]:::runtime
            helpHTML["help.html"]:::runtime
        end

        subgraph "Global Templates & Styles"
            direction TB
            wrapperHTML["wrapper.html"]:::runtime
            baseCSS["base.css"]:::runtime
        end
    end

    %% Build Relationships
    packJson -->|configures| Bundle
    rollupConfig -->|bundles TS| Bundle
    tsconfig -->|compiles TS| Bundle
    eslint -->|lints code| Bundle

    %% Loader to Bundle
    Loader -->|fetches & executes| Bundle

    %% Initialization Flow
    Bundle -->|initializes| Main
    Main -->|loads utilities| Base
    Main -->|loads types| Globals
    Main -->|loads types| CSSdts
    Main -->|loads types| HTMLdts
    Main -->|registers modules| Registry

    %% Module Registration
    Registry -->|includes| Banner
    Registry -->|includes| Roster
    Registry -->|includes| Whisper
    Registry -->|includes| Help
    Registry -->|includes| DOM

    %% Templates Usage
    Banner -->|uses| bannerHTML
    Banner -->|uses| bannerCSS
    Roster -->|uses| rosterHTML
    Roster -->|uses| rosterCSS
    Roster -->|uses| rosterCards
    Help -->|uses| helpHTML
    Main -->|renders wrapper| wrapperHTML
    Main -->|applies styles| baseCSS

    %% User Interaction Flow
    Browser -->|user events| DOM
    DOM -->|forwards events| Registry
    Registry -->|triggers| Banner
    Registry -->|triggers| Roster
    Registry -->|triggers| Whisper
    Registry -->|triggers| Help
    Banner -->|manipulates DOM| Browser
    Roster -->|manipulates DOM| Browser
    Whisper -->|manipulates DOM| Browser
    Help -->|manipulates DOM| Browser

    %% Click Events
    click Loader "https://github.com/sin-1337/crabs/blob/Stable/crabsloader.user.js"
    click packJson "https://github.com/sin-1337/crabs/blob/Stable/package.json"
    click rollupConfig "https://github.com/sin-1337/crabs/blob/Stable/rollup.config.mjs"
    click tsconfig "https://github.com/sin-1337/crabs/blob/Stable/tsconfig.json"
    click eslint "https://github.com/sin-1337/crabs/blob/Stable/eslint.config.mjs"
    click Main "https://github.com/sin-1337/crabs/blob/Stable/src/main.ts"
    click Base "https://github.com/sin-1337/crabs/blob/Stable/src/base.ts"
    click Globals "https://github.com/sin-1337/crabs/blob/Stable/src/globals.d.ts"
    click CSSdts "https://github.com/sin-1337/crabs/blob/Stable/src/types/css.d.ts"
    click HTMLdts "https://github.com/sin-1337/crabs/blob/Stable/src/types/html.d.ts"
    click Registry "https://github.com/sin-1337/crabs/blob/Stable/src/modules/index.ts"
    click Banner "https://github.com/sin-1337/crabs/blob/Stable/src/modules/banner.ts"
    click Roster "https://github.com/sin-1337/crabs/blob/Stable/src/modules/roster.ts"
    click Whisper "https://github.com/sin-1337/crabs/blob/Stable/src/modules/whisperplus.ts"
    click Help "https://github.com/sin-1337/crabs/blob/Stable/src/modules/help.ts"
    click DOM "https://github.com/sin-1337/crabs/blob/Stable/src/modules/dom.ts"
    click bannerHTML "https://github.com/sin-1337/crabs/blob/Stable/src/modules/templates/banner.html"
    click bannerCSS "https://github.com/sin-1337/crabs/blob/Stable/src/modules/templates/banner.css"
    click rosterHTML "https://github.com/sin-1337/crabs/blob/Stable/src/modules/templates/roster.html"
    click rosterCSS "https://github.com/sin-1337/crabs/blob/Stable/src/modules/templates/roster.css"
    click rosterCards "https://github.com/sin-1337/crabs/blob/Stable/src/modules/templates/roster_cards.html"
    click helpHTML "https://github.com/sin-1337/crabs/blob/Stable/src/modules/templates/help.html"
    click wrapperHTML "https://github.com/sin-1337/crabs/blob/Stable/src/templates/wrapper.html"
    click baseCSS "https://github.com/sin-1337/crabs/blob/Stable/src/templates/base.css"

    %% Styles
    classDef build fill:#1f77b4,stroke:#000,color:#fff
    classDef runtime fill:#2ca02c,stroke:#000,color:#fff
    classDef external fill:#7f7f7f,stroke:#000,color:#fff
```
