# sugurunatsuno/lol-mac-obs-clip architecture

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

- Interactive diagram: https://gitdiagram.com/sugurunatsuno/lol-mac-obs-clip
- Repository: https://github.com/sugurunatsuno/lol-mac-obs-clip

## Overview

##### Project Type and Purpose
- This is a utility tool designed for gamers or streamers who want automated replay saving during League of Legends games.
- It listens to game events (through the LoL API) and communicates with OBS to trigger recording actions.
- The tool also supports playing a shutter sound and optionally displays a simple overlay on the screen.

##### Analyzing the File Structure
- Top-Level Files & Directories: The repository includes essential configuration and build files like .gitignore, GitHub workflow configurations, tool version definitions, and changelog.
- The primary code resides in the "src" directory.
- Within "src", different submodules are clearly separated:
- The "lol_api" folder contains modules (events.py, player.py) that handle interactions with the League of Legends API.
- The "obs" folder (with obs_client.py) manages communications with OBS via its WebSocket interface.
- The "utils" directory includes supporting functionalities such as configuration parsing (config.py), logging utilities (logger.py), options handling (option.py), and result management (result.py).
- There are also standalone scripts like dump.py, mock.py, and main.py that likely serve for testing, debugging, and running the main application.

##### Components & Their Interactions
a. Main Application (src/main.py):
- Acts as the orchestrator that integrates events from LoL, processes them, and dispatches commands to OBS.

b. League of Legends API Module (src/lol_api):
- events.py: Handles event detection from the LoL Live Client API.
- player.py: Might be responsible for player-specific logic or configurations tied to game events.
- Interaction: These modules listen to real-time inputs and pass relevant data (e.g., death events) to the main application.

c. OBS Integration Module (src/obs/obs_client.py):
- Connects with OBS via WebSocket (version 5) to trigger functions such as saving the replay buffer.
- It receives commands from the main application when a LoL event triggers a recording.

d. Utility & Configuration Modules (src/utils):
- config.py: Loads and manages configuration settings (e.g., config.json placed alongside the executable).
- logger.py: Manages logging across the application to capture debug and information messages.
- Additional utility modules (option.py, result.py) support common functions or encapsulate results.

e. Auxiliary Components:
- dump.py and mock.py: Likely used for testing and debugging different parts of the application logic.
- Audio and Overlay: The project includes a shutter.mp3 file for the shutter sound effect. There is also mention in the README of a “簡易オーバーレイボタン” (simple overlay), which suggests another visual integration, possibly managed by external tools or additional modules not shown in the file tree directly.

##### Architectural Patterns and Design Principles
- Modular Design: The directory structure clearly promotes separation of concerns with distinct modules for API integration, OBS communication, and common utilities.
- Event-Driven: The system reacts to external events (from LoL) and triggers specific actions (OBS commands), suggesting an event-driven architecture.
- Configurable Behavior: With configuration files (config.json) and utility modules, critical behavior (like which events trigger recording) is customizable, promoting flexibility.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Sources
    subgraph "External Sources"
        LoLClient["League of Legends Client"]:::external
        OBSExternal["OBS (WebSocket Interface)"]:::external
        SystemAudio["System Audio"]:::external
    end

    %% LoL API Module
    subgraph "League of Legends API Module"
        LoLEvents["LoL API - Events"]:::module
        LoLPlayer["LoL API - Player"]:::module
    end

    %% Main Orchestrator
    MainController["Main Orchestrator"]:::module

    %% OBS Integration Module
    subgraph "OBS Integration"
        OBSClient["OBS WebSocket Client"]:::module
    end

    %% Utility & Configuration Modules
    subgraph "Utility & Configuration"
        Config["Configuration Parser"]:::utility
        Logger["Logging Utilities"]:::utility
        Option["Options Handling"]:::utility
        Result["Result Management"]:::utility
    end

    %% Auxiliary Scripts
    subgraph "Auxiliary Scripts"
        DumpScript["Dump Script"]:::aux
        MockScript["Mock Script"]:::aux
    end

    %% Additional Components
    ShutterSound["Shutter Sound Asset"]:::external
    Overlay["Simple Overlay"]:::module

    %% Connections
    LoLClient -->|"sends_event_data"| LoLEvents
    LoLClient -->|"sends_player_info"| LoLPlayer
    LoLEvents -->|"notifies"| MainController
    LoLPlayer -->|"updates"| MainController
    MainController -->|"triggers"| OBSClient
    MainController -->|"loads"| Config
    MainController -->|"logs_via"| Logger
    MainController -->|"uses"| Option
    MainController -->|"manages"| Result
    MainController -->|"plays"| ShutterSound
    MainController -->|"activates"| Overlay
    OBSClient -->|"commands"| OBSExternal
    DumpScript -->|"debugs"| MainController
    MockScript -->|"tests"| MainController

    %% Styles
    classDef external fill:#ffef96,stroke:#f39c12,stroke-width:2px;
    classDef module fill:#d0e6a5,stroke:#68a357,stroke-width:2px;
    classDef utility fill:#a9cce3,stroke:#2874a6,stroke-width:2px;
    classDef aux fill:#f5b7b1,stroke:#d98880,stroke-width:2px;

    %% Click Events
    click MainController "https://github.com/sugurunatsuno/lol-mac-obs-clip/blob/master/src/main.py"
    click LoLEvents "https://github.com/sugurunatsuno/lol-mac-obs-clip/blob/master/src/lol_api/events.py"
    click LoLPlayer "https://github.com/sugurunatsuno/lol-mac-obs-clip/blob/master/src/lol_api/player.py"
    click OBSClient "https://github.com/sugurunatsuno/lol-mac-obs-clip/blob/master/src/obs/obs_client.py"
    click Config "https://github.com/sugurunatsuno/lol-mac-obs-clip/blob/master/src/utils/config.py"
    click Logger "https://github.com/sugurunatsuno/lol-mac-obs-clip/blob/master/src/utils/logger.py"
    click Option "https://github.com/sugurunatsuno/lol-mac-obs-clip/blob/master/src/utils/option.py"
    click Result "https://github.com/sugurunatsuno/lol-mac-obs-clip/blob/master/src/utils/result.py"
    click DumpScript "https://github.com/sugurunatsuno/lol-mac-obs-clip/blob/master/src/dump.py"
    click MockScript "https://github.com/sugurunatsuno/lol-mac-obs-clip/blob/master/src/mock.py"
    click ShutterSound "https://github.com/sugurunatsuno/lol-mac-obs-clip/blob/master/shutter.mp3"
```
