# ndekopon/overlaytools architecture

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

- Interactive diagram: https://gitdiagram.com/ndekopon/overlaytools
- Repository: https://github.com/ndekopon/overlaytools

## Overview

##### Project Type and Purpose
- This is a full-stack, single-machine overlay tool for Apex Legends custom matches.
- The C++ “proxy” component connects to the game’s LiveAPI via WebSocket, processes incoming events, and exposes them over local HTTP and WebSocket endpoints.
- A browser-based frontend (“htdocs”) consumes those streams to render real-time overlays in OBS.
- A WebView2-based configuration GUI (“webapi-config” solution) allows match administrators to view, correct, and switch overlays in real time.

##### High-Level File Structure Analysis
Top-level:
- apexliveapi_proxy.sln / .vcxproj           ← C++ proxy solution
- dump2json.vcxproj                         ← standalone CLI to convert raw events to JSON
- htdocs/                                   ← static web assets & sample custom overlays
- src/                                      ← core proxy code (threads, WebSocket server, LiveAPI client, protobuf events)
- webapi-config/                            ← WebView2 GUI solution for configuration

##### Key Components and Their Roles
- Game LiveAPI WebSocket Client (src/http_get_thread.cpp, livedata.cpp)
- Event Processing Core (src/events/*.pb.cc/.pb.h, duplicated in threads, filters, shared_context)
- Local HTTP Server for static files (htdocs) and WebSocket Server for event push (websocket_server.cpp/thread.cpp)
- dump2json tool for offline event dumps
- WebView2-based Admin GUI (webapi-config/main_window.cpp + htm/css/js from htdocs/webapi-config.*)

##### proxy’s HTTP_GET_THREAD connects, decodes, forwards events into the Event Processing Core.
3. Core uses multiple worker threads (duplication_thread, filedump, local_thread) to buffer, log, dump, or transform events.
4. WebSocket Server thread broadcasts processed events to all connected frontends (OBS browser, Admin GUI).

##### Architectural Patterns and Principles
- Modular, thread-per-responsibility (producer, consumer, logger, WebSocket broadcaster).
- Publisher–Subscriber pattern: event core publishes to WebSocket clients and file dump.
- Separation of concerns:
- Core C++ engine handles I/O, processing, network.
- Web frontend handles presentation and customization.
- GUI handles configuration and live control.
- No external dependencies: entirely local, minimal external network.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External System
    subgraph "External System" 
        direction TB
        Game["Apex Legends Game Client"]:::external
    end

    %% Backend Engine
    subgraph "C++ Proxy Service" 
        direction TB
        SLN["apexliveapi_proxy.sln / .vcxproj"]:::backend
        MainEntrypoint["main.cpp / main.hpp"]:::backend
        ConfigIni["config_ini.cpp / config_ini.hpp"]:::backend

        subgraph "LiveAPI Client Thread"
            direction TB
            HTTPGet["http_get_thread.cpp / http_get_thread.hpp"]:::backend
            LiveData["livedata.cpp / livedata.hpp"]:::backend
        end

        subgraph "Event Processing Core"
            direction TB
            EventsDef["events.pb.cc / events.pb.h"]:::backend
            CoreThread["core_thread.cpp / core_thread.hpp"]:::backend
            SharedCtx["shared_context.cpp / shared_context.hpp"]:::backend
        end

        subgraph "Worker Threads"
            direction TB
            Duplicator["duplicator.cpp / duplicator.hpp"]:::backend
            DupThread["duplication_thread.cpp / duplication_thread.hpp"]:::backend
            Filedump["filedump.cpp / filedump.hpp"]:::backend
            LocalThread["local_thread.cpp / local_thread.hpp"]:::backend
            LogUtil["log.cpp / log.hpp"]:::backend
        end

        subgraph "Servers"
            direction TB
            WebAPI["webapi.cpp / webapi.hpp"]:::backend
            WebSocketSrv["websocket_server.cpp / websocket_server.hpp"]:::backend
            WebSocketThread["websocket_thread.cpp / websocket_thread.hpp"]:::backend
        end
    end

    %% Offline Tool and Data Store
    subgraph "Offline Utility"
        direction TB
        DumpProj["dump2json.vcxproj"]:::tool
        DumpSrc["dump2json.cpp"]:::tool
        DumpRes["dump2json.rc"]:::tool
    end
    RawFiles["Raw Event Files"]:::storage

    %% Frontends
    subgraph "Frontends"
        direction TB
        Browser["OBS Browser Overlay"]:::frontend
        htdocs["htdocs/ (Static Overlays)"]:::frontend
        subgraph "Admin GUI (WebView2)"
            direction TB
            GUIProj["webapi-config.sln / webapi-config.vcxproj"]:::frontend
            GUIEntry["main.cpp / main.hpp"]:::frontend
            MainWin["main_window.cpp / main_window.hpp"]:::frontend
            Resource["resource.hpp"]:::frontend
            GUIRes["webapi-config.rc"]:::frontend
            GUIAssetsCSS["htdocs/webapi-config.css"]:::frontend
            GUIAssetsJS["htdocs/webapi-config.js"]:::frontend
        end
    end

    %% Data Flows
    Game -->|"LiveAPI JSON"| HTTPGet
    HTTPGet --> LiveData
    LiveData --> EventsDef
    EventsDef --> CoreThread
    CoreThread --> SharedCtx

    SharedCtx --> Duplicator
    SharedCtx --> DupThread
    SharedCtx --> Filedump
    SharedCtx --> LocalThread
    SharedCtx --> LogUtil

    SharedCtx --> WebSocketThread
    WebSocketThread --> WebSocketSrv

    WebSocketSrv -->|"WebSocket Event Stream"| Browser
    WebSocketSrv -->|"WebSocket Event Stream"| MainWin

    WebAPI -->|"HTTP GET Static Files"| htdocs
    htdocs --> Browser
    htdocs --> MainWin

    DumpProj --> DumpSrc
    DumpSrc --> DumpRes
    DumpSrc --> RawFiles
    RawFiles --> DumpSrc

    %% Click Events
    click SLN "https://github.com/ndekopon/overlaytools/blob/main/apexliveapi_proxy.sln"
    click MainEntrypoint "https://github.com/ndekopon/overlaytools/blob/main/src/main.cpp"
    click ConfigIni "https://github.com/ndekopon/overlaytools/blob/main/src/config_ini.cpp"
    click HTTPGet "https://github.com/ndekopon/overlaytools/blob/main/src/http_get_thread.cpp"
    click LiveData "https://github.com/ndekopon/overlaytools/blob/main/src/livedata.cpp"
    click EventsDef "https://github.com/ndekopon/overlaytools/blob/main/src/events/events.pb.cc"
    click CoreThread "https://github.com/ndekopon/overlaytools/blob/main/src/core_thread.cpp"
    click SharedCtx "https://github.com/ndekopon/overlaytools/blob/main/src/shared_context.cpp"
    click Duplicator "https://github.com/ndekopon/overlaytools/blob/main/src/duplicator.cpp"
    click DupThread "https://github.com/ndekopon/overlaytools/blob/main/src/duplication_thread.cpp"
    click Filedump "https://github.com/ndekopon/overlaytools/blob/main/src/filedump.cpp"
    click LocalThread "https://github.com/ndekopon/overlaytools/blob/main/src/local_thread.cpp"
    click LogUtil "https://github.com/ndekopon/overlaytools/blob/main/src/log.cpp"
    click WebAPI "https://github.com/ndekopon/overlaytools/blob/main/src/webapi.cpp"
    click WebSocketSrv "https://github.com/ndekopon/overlaytools/blob/main/src/websocket_server.cpp"
    click WebSocketThread "https://github.com/ndekopon/overlaytools/blob/main/src/websocket_thread.cpp"
    click DumpProj "https://github.com/ndekopon/overlaytools/blob/main/dump2json.vcxproj"
    click DumpSrc "https://github.com/ndekopon/overlaytools/blob/main/src/dump2json.cpp"
    click DumpRes "https://github.com/ndekopon/overlaytools/blob/main/src/dump2json.rc"
    click htdocs "https://github.com/ndekopon/overlaytools/tree/main/htdocs/"
    click GUIProj "https://github.com/ndekopon/overlaytools/blob/main/webapi-config/webapi-config.sln"
    click GUIEntry "https://github.com/ndekopon/overlaytools/blob/main/webapi-config/main.cpp"
    click MainWin "https://github.com/ndekopon/overlaytools/blob/main/webapi-config/main_window.cpp"
    click Resource "https://github.com/ndekopon/overlaytools/blob/main/webapi-config/resource.hpp"
    click GUIRes "https://github.com/ndekopon/overlaytools/blob/main/webapi-config/webapi-config.rc"
    click GUIAssetsCSS "https://github.com/ndekopon/overlaytools/blob/main/htdocs/webapi-config.css"
    click GUIAssetsJS "https://github.com/ndekopon/overlaytools/blob/main/htdocs/webapi-config.js"

    %% Styles
    classDef external fill:#cccccc,stroke:#666666,color:#000000;
    classDef backend fill:#cce5ff,stroke:#3399ff,color:#003366;
    classDef frontend fill:#d4edda,stroke:#28a745,color:#155724;
    classDef tool fill:#fff3cd,stroke:#ffcd39,color:#856404;
    classDef storage fill:#e2e3e5,stroke:#adb5bd,color:#495057;
```
