# overlayplugin/cactbot architecture

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

- Interactive diagram: https://gitdiagram.com/overlayplugin/cactbot
- Repository: https://github.com/overlayplugin/cactbot

## Overview

##### Project Type and Purpose
- Cactbot is an open-source plugin overlay system for the Advanced Combat Tracker (ACT) tool, built to provide real-time raid assistance for Final Fantasy XIV.
- It is a mixed-environment project with a C#/.NET “EventSource” backend that parses network logs (via OverlayPlugin), a Node/npm‐based build pipeline (TypeScript, webpack, util scripts) that generates and bundles resources, and a collection of HTML/TypeScript “overlay” front ends loaded by OverlayPlugin via a local WebSocket server.

##### Top-Level Components
A. Backend Plugin Layer (“plugin/”)
- CactbotEventSource (.NET 4.6.1+) – reads FFXIV combat logs from the FFXIV_ACT_Plugin, filters and normalizes events, exposes a JSON event stream to OverlayPlugin.
- CactbotOverlay – minimal C# loader that registers on ACT’s plugin chain and hands off to the EventSource.
B. Overlay Host (OverlayPlugin)
- Hosts and serves a WebSocket API (`OverlayPlugin.dll`), acting as the bridge between CactbotEventSource and any number of browser‐based overlay clients.
C. WebSocket API
- A standardized JSON message protocol over a local `ws://127.0.0.1:10501/ws` interface, through which UI overlays subscribe to combat events, config changes, and user triggers.
D. Front-End Overlays (“ui/” directory)
- A set of independent HTML+CSS+TypeScript applications (“raidboss”, “oopsyraidsy”, “jobs”, “eureka”, “radar”, “dps”, “pullcounter”, “test”).
- Each overlay implements its own Data → View binding, event handling, styling, and user configuration.
- The “raidboss emulator” mimics the live WebSocket feed using dropped network logs.
E. Build & Tooling
- Node/npm + webpack configurations (`webpack/`, `tsconfig*.json`, `package.json`) compile TypeScript overlays and util scripts.
- “util/” scripts generate JSON/TypeScript data (zone IDs, effect IDs, timeline files) and automate version bumps, translation coverage, and release packaging.
- Test harnesses (`test/`, `ui/raidboss/test/`, `ui/test/`) validate triggers, regexes, timeline parsing, and UI components.

##### Run-Time Data Flow
1. FFXIV game writes network log → FFXIV_ACT_Plugin (ACT)
2. CactbotEventSource reads raw log entries → parses into structured events.
3. OverlayPlugin WebSocket server forwards events over WS.
4. Each UI overlay subscribes to the WS feed → processes events through its own triggers/timelines → renders visual and audio alerts in the browser overlay.
5. User interactions (config panel, user scripts) send commands back to EventSource via the same WS or via updateable JSON config files under `%APPDATA%\...OverlayPlugin.config.json`.

##### Architectural Patterns & Principles
- **Plugin‐Architecture**: CactbotEventSource and CactbotOverlay plug into ACT’s extension points.
- **Event‐Driven**: All communication uses publish/subscribe over WebSocket.
- **Separation of Concerns**:
- Backend (.NET) exclusively handles log ingest and event normalization.
- Front-end (HTML/TS) exclusively handles rendering and user interaction.
- Build scripts (Node) exclusively handle code generation, packaging, and resource management.
- **Modular Overlays**: Each overlay resides in its own directory and can be added/removed independently in the OverlayPlugin UI.

- **Detail Balance**: Capture all essential pieces (C# plugin, WS API, each overlay, build scripts) without cluttering minor utilities.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Systems"
        FG["FFXIV Game / Network Log"]:::external
        AP["FFXIV_ACT_Plugin.dll"]:::external
    end

    subgraph "Backend Plugin Layer"
        OL["CactbotOverlay (Plugin Loader)"]:::backend
        EO["CactbotEventSource (.NET C#)"]:::backend
    end

    subgraph "Overlay Host & WS API"
        WS["OverlayPlugin.dll (WebSocket Server)"]:::core
    end

    subgraph "Front-End Overlays + Build Tools"
        subgraph "Build & Tooling"
            WP["webpack/ (Build Config)"]:::tooling
            TS["tsconfig*.json"]:::tooling
            PK["package.json / package-lock.json"]:::tooling
            UT["util/ (Data Generation Scripts)"]:::tooling
        end
        subgraph "Overlays"
            RB["raidboss"]:::overlay
            OR["oopsyraidsy"]:::overlay
            JB["jobs"]:::overlay
            EU["eureka"]:::overlay
            RD["radar"]:::overlay
            DP["dps"]:::overlay
            PC["pullcounter"]:::overlay
            CP["config panel"]:::overlay
            GT["ui/test"]:::overlay
            EM["raidboss emulator"]:::overlay
        end
    end

    FG -->|"Logs"| AP
    AP -->|"Registers Plugin"| OL
    OL -->|"Hands off to"| EO
    EO -->|"Parsed Combat Event JSON"| WS
    WS -->|"WS Feed"| RB
    WS -->|"WS Feed"| OR
    WS -->|"WS Feed"| JB
    WS -->|"WS Feed"| EU
    WS -->|"WS Feed"| RD
    WS -->|"WS Feed"| DP
    WS -->|"WS Feed"| PC
    WS -->|"WS Feed"| CP
    WS -->|"WS Feed"| GT
    WS -->|"WS Feed"| EM
    CP -->|"Config Commands"| WS

    WP -->|"Bundles Assets"| RB
    WP -->|"Bundles Assets"| OR
    WP -->|"Bundles Assets"| JB
    WP -->|"Bundles Assets"| EU
    WP -->|"Bundles Assets"| RD
    WP -->|"Bundles Assets"| DP
    WP -->|"Bundles Assets"| PC
    WP -->|"Bundles Assets"| CP
    WP -->|"Bundles Assets"| EM
    TS --> WP
    PK --> WP
    UT --> WP

    %% Click Events
    click EO "https://github.com/overlayplugin/cactbot/tree/main/plugin/CactbotEventSource/"
    click OL "https://github.com/overlayplugin/cactbot/tree/main/plugin/CactbotOverlay/"
    click WS "https://github.com/overlayplugin/cactbot/blob/main/resources/overlay_plugin_api.ts"
    click RB "https://github.com/overlayplugin/cactbot/tree/main/ui/raidboss/"
    click OR "https://github.com/overlayplugin/cactbot/tree/main/ui/oopsyraidsy/"
    click JB "https://github.com/overlayplugin/cactbot/tree/main/ui/jobs/"
    click EU "https://github.com/overlayplugin/cactbot/tree/main/ui/eureka/"
    click RD "https://github.com/overlayplugin/cactbot/tree/main/ui/radar/"
    click DP "https://github.com/overlayplugin/cactbot/tree/main/ui/dps/"
    click PC "https://github.com/overlayplugin/cactbot/tree/main/ui/pullcounter/"
    click CP "https://github.com/overlayplugin/cactbot/tree/main/ui/config/"
    click GT "https://github.com/overlayplugin/cactbot/tree/main/ui/test/"
    click EM "https://github.com/overlayplugin/cactbot/tree/main/ui/raidboss/emulator/"
    click WP "https://github.com/overlayplugin/cactbot/tree/main/webpack/"
    click TS "https://github.com/overlayplugin/cactbot/blob/main/tsconfig.json"
    click TS "https://github.com/overlayplugin/cactbot/blob/main/tsconfig.node.json"
    click TS "https://github.com/overlayplugin/cactbot/blob/main/tsconfig.npm.json"
    click TS "https://github.com/overlayplugin/cactbot/blob/main/tsconfig.eslint.json"
    click PK "https://github.com/overlayplugin/cactbot/blob/main/package.json"
    click PK "https://github.com/overlayplugin/cactbot/blob/main/package-lock.json"
    click UT "https://github.com/overlayplugin/cactbot/tree/main/util/"

    %% Styles
    classDef external fill:#dddddd,stroke:#888,stroke-width:1px;
    classDef backend fill:#add8e6,stroke:#444,stroke-width:1px;
    classDef core fill:#90ee90,stroke:#444,stroke-width:1px;
    classDef tooling fill:#ffa500,stroke:#444,stroke-width:1px;
    classDef overlay fill:#dda0dd,stroke:#444,stroke-width:1px;
```
