# BACON_DOCS

System Architecture
User Manuals
Download
System Architecture

# Overview & Setup

Welcome to BaconSuite V4. This modular, locally-hosted streaming engine unifies interactions across Twitch, Kick, YouTube, OBS, and Discord. Designed entirely on Node.js and Socket.IO, it provides a centralized hub for overlays, chat aggregation, custom alerts, and stream control.

## System Boot Process

Getting the suite running requires establishing the environment securely and initializing the main server process.

1
Environment Setup

Navigate to the `baconsuite-core/engines/` directory. Ensure the `.env` file is fully populated with your platform API keys, OAuth tokens, Client IDs, and OBS WebSocket credentials. (Managed via System Vault).

2
Install Dependencies

Open a terminal in the root directory and run `npm install`. This generates your `node_modules` based on `package.json`.

3
Boot the Suite

Run the provided `start.bat` script. This initiates `index.js`, loading all core engines first, followed by dynamically loading all modules.

### Global Settings & Logs

Access your main command center at `http://localhost:3000/admin`. From the dashboard header, click the settings gear to update your OBS credentials on the fly or assign moderator access to specific modules. All bot activities are logged to `backstage_logs.json`.

System Architecture

# Core Connections

### DO NOT MODIFY WARNING

The files providing working connections for Twitch, Kick, YouTube, OBS, and Nightbot are LOCKED. They function flawlessly as intended and do not need to be changed or modified when adding new modules. Interface with them strictly via their exposed Socket.IO events.

## Foundational Components

### system-vault.js

Acts as the secure credentials parser. It extracts sensitive variables from the `.env` file and securely passes them into the server backend without exposing them to the frontend DOM.

### connections.json

The global state ledger. As connections to APIs and websockets open or drop, this file is written to. All admin frontend UI panels listen to this file to display real-time network status indicators.

### baconchat-engine.js

The unified chat bridge. Connects to Twitch, Kick, and YouTube simultaneously. It catches every message, translates varying platform structures into a standardized `BaconMessage` object, handles emote parsing, and emits the finalized data to the frontend overlay.

User Manual

# Module: Grid 2.0

Grid 2.0 is an interactive, highly dynamic media grid. It allows streamers and chatters to display URLs, images, and videos dynamically on-screen up to 8 independent cells simultaneously.

## Access Points & Views

- Viewer/OBS Mode: Add `http://localhost:3000/modules/grid2.0/viewer.html` as an OBS Browser Source. This is the live, transparent output.
- Admin Control Panel: The central management hub via the BaconSuite dashboard.
- OBS Dock Mode: Append `?mode=dock` to the control panel URL. This strips away extra UI padding so it fits perfectly inside a slim OBS custom dock.
- Moderator Mode: Append `?role=mod`. This hides the master configuration gear but retains cell control functionality for your trusted team.

## Interface & Controls

From the control panel, you can instantly manipulate the live grid state. Data is saved in real-time to `grid-data.json`.

- Add/Remove Cells: Dynamically scale the grid from 1 to 8 cells. The frontend instantly auto-sizes the layout to fit the screen.
- Cell Locking: Click the "Lock" icon on any slot. This prevents chatters or automated commands from overriding the content in that specific cell.
- Library Backups: Open the Library Sidebar to save your current entire grid layout as a preset. You can export/import these setups as JSON files. Mark backups as "Approved" or "Locked" to protect them.

## Chat Commands

You can toggle viewer command access on or off via the master config. If enabled, chatters (or mods based on your permissions) can control the grid live.

!focus <1-8>
Forces the viewer output to prioritize and maximize a specific cell. E.g., `!focus 3` or simply `!3`.
!url <cell> <url>
Pushes a new image, video, or website to a specific cell. Example: `!url 1 https://example.com/image.png`.
!title <cell> <text>
Updates the text label displayed underneath a specific cell.
!blur <cell>
Instantly applies a heavy CSS blur filter to censor the content of a cell. Run again to unblur.
!refresh / !r
Forces the frontend to reload the contents of a specific cell (useful for stuck iframes).
!swap <a> <b>
Swaps the content and state of two cells. Example: `!swap 1 4`.
Note on Permissions: Inside the Grid Config modal, you can independently set every single command above to require "Viewer" or "Moderator" status, and toggle which platforms (Twitch, YouTube) they are active on.
User Manual

# Module: OBS Control

The OBS Controller Engine (`engine (obs).js`) connects directly to OBS Studio via WebSocket, giving your BaconSuite dashboard remote control over your broadcast hardware.

## Initial Setup

1. In OBS Studio, navigate to Tools -> WebSocket Server Settings.
2. Ensure "Enable WebSocket server" is checked. Note the Port (usually 4455) and generate/set a Password.
3. In the BaconSuite Admin Dashboard header, click the settings gear and input this IP, Port, and Password. BaconSuite will auto-reconnect.

## Live Control Features

Once connected, the backend engine translates Socket.IO commands into native OBS actions.

### Live Preview Engine

The module actively utilizes `GetSourceScreenshot` via OBS to fetch low-latency JPEG frames of your current scene and broadcasts them to your dashboard, creating a real-time monitor without needing OBS open on your screen.

### Scene Switching

Triggers `SetCurrentProgramScene`. Your dashboard automatically fetches all available scenes from OBS and creates clickable buttons to transition instantly.

### Source Toggling

Dynamically extracts all items/sources in your currently active scene. You can toggle their visibility (eyes) on and off with `SetSceneItemEnabled`.

### Audio Mixing & Muting

Provides volume sliders for specific audio inputs using `SetInputVolume` and instantly mute tracks using `ToggleInputMute`.

Warning: The OBS Control module has dedicated "Toggle Stream" and "Toggle Record" buttons. Ensure you verify your status indicators before clicking these to avoid accidentally dropping your live broadcast.
User Manual

# Overlay & Chat Systems

The Overlay system manages dynamic on-screen stream widgets, while the Chat module visualizes the aggregated cross-platform feed. Both rely on `overlay-data.json` for configuration persistence.

## Unified Chat Widget

Add `http://localhost:3000/modules/chat/chat.html` as a Browser Source in OBS. It features a transparent background and smooth auto-scrolling.

### Customization (via Overlay Engine)

- Themes: Supports multiple CSS themes (e.g., 'persona'). The engine broadcasts the active theme via socket event `chat_config_sync`.
- Animations: Control how messages appear (e.g., `slideInLeft`).
- Lifespan (Timeout): Set a duration (e.g., 30 seconds). The frontend javascript automatically triggers an exit animation and removes the DOM element after this timer expires to keep the screen uncluttered.
- Styling: Master control over font sizes and background opacity.

## General Stream Overlays

Add `http://localhost:3000/modules/overlay/live.html` as your primary full-screen (1920x1080) OBS Browser Source.

This module listens passively to core engine events (like new followers from the Twitch/Kick connections or manual triggers from the admin panel) and executes rich HTML/CSS animations. The config is saved directly to `overlay-data.json` via the `saveOverlay` socket command.

System Architecture

# Developer Guide

BaconSuite's architecture is highly modular. The core `index.js` file automatically scans the `/modules/` directory on boot. To create a new module, simply create a new folder and provide the required file structure.

## 1. Folder Structure

    baconsuite-core/
    └── modules/
        └── your-module-name/
            ├── manifest.json       (Required)
            ├── engine.js           (Required Backend Logic)
            └── public/             (Required Frontend Directory)
                └── panel.html      (Admin UI)

## 2. Starter Template: manifest.json

This tells the main server how to register your module and where to link it in the admin sidebar.

    {
      "name": "My Custom Module",
      "version": "1.0.0",
      "description": "Does something awesome.",
      "main": "engine.js",
      "panelUrl": "/modules/your-module-name/panel.html"
    }

## 3. Starter Template: engine.js

This file handles backend logic. It MUST export an exported class with an `init()` function, following the established V4 architecture.

    export default class CustomEngine {
        constructor({ app, io, chatEngine, vault }) {
            this.app = app;
            this.io = io;
            this.vault = vault;
        }

        init() {
            console.log('[Module: Custom] Initializing backend logic...');

            // Set up specific Socket.IO listeners for this module
            this.io.on('connection', (socket) => {
                socket.on('customModuleAction', (data) => {
                    console.log('Received action from panel:', data);
                    // Broadcast an update to viewers/overlays
                    this.io.emit('customModuleUpdate', { status: 'success' });
                });
            });
        }
    }