# djalilhebal/super-scoreboard architecture

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

- Interactive diagram: https://gitdiagram.com/djalilhebal/super-scoreboard
- Repository: https://github.com/djalilhebal/super-scoreboard

## Overview

##### Project Type and Purpose
- Project Type: A desktop overlay application built in Java (using Swing/AWT, JNA, etc.) that hooks into game behavior by overlaying the in-game scoreboard.
- Purpose: To track cooldowns (initially summoner spells, with potential for ult and item cooldowns) by letting users interact with the overlay (double-click, long press, etc.) and also integrate with external sources (e.g., Riot’s APIs via R4J and direct LCU calls) to fetch additional game data and adjust cooldown timings.

##### File Structure
- Top-Level Files: Standard files like .gitignore, pom.xml (Maven build configuration), LICENSE (COPYING.txt) and documentation items.
- Directories:
- raw-data: Has test/sample JSON files that mimic live game data from LCU and op.gg endpoints, which implies that services in your application parse and use these JSON responses.
- scrap: Contains prototype or experimental code (Java, JavaScript, and TypeScript files) which could demonstrate earlier iterations or ideas for static data provision, utilities, or services.
- src/main/java/me/djalil/scoreboard: This is the heart of the app, containing:
- Main entry and controller files (App.java, AppController.java).
- Service classes (DdragonService, LcuService, OpggService, etc.) that likely interface with external APIs to fetch live game data.
- Model classes (AppModel, LightGame, SpellTiming, etc.) that represent domain concepts.
- UI/Component classes (KHeader, KParticipantList, KScoreboard, etc.) establishing the overlay UI elements.

a. Major Components:
- User Interface Layer:
- Input Handler: Captures user actions (key presses, double-clicks, long presses) to trigger internal events.
- Controller/Business Logic Layer:
- Core Application Controller (AppController, IAppController) that manages user inputs and overall app state.
- Event Synthesizer and various Demo classes (e.g., SynthesizingEventsDemo, ForwardingEventsDemo) indicate event handling and testing of the input-to-action mapping.
- Domain / Model Layer:
- Domain Objects: Classes such as LightGame, LightSpell, SpellTiming, and Thing that encapsulate game data and cooldown logic.
- Service Layer:
- External API Integrations: Components like LcuService, DdragonService, and OpggService that interact with Riot endpoints or third–party APIs.
- Data Providers and Client Checkers (DumbClientChecker, IGameProvider, etc.) that validate game client status or fetch additional client data.
- Native / Platform Integration Layer:
- Utilizing libraries like JNA and (potentially) JNativeHook to interact with Windows APIs for overlay positioning and input handling.
- Data & Configuration:
- Test Data Files (in raw-data) to simulate API responses during development.
- Maven Build files (pom.xml) to manage dependencies like Google Gson, R4J, and JNA.

b. Component Interactions:
- The AppController interacts with the Model layer incorporating Game State information, and in turn refines the UI accordingly (reordering scoreboard participants, updating cooldown displays, etc.).
- The Service layer uses external libraries (Google gson for JSON parsing, R4J for Riot API calls) and native libraries (JNA) to access system APIs.

##### Architectural Patterns and Important Principles
- Event-Driven Design: Emphasize how input events are captured and processed, and how state and data flows from user actions to API calls and finally to UI updates.
- Layered Architecture: Consider displaying a layered view where the overlay presentation (UI) is separate from the controller and business logic, which in turn is separate from the service integrations.
- Extensibility: Note that additional cooldown types (ults, items) can be integrated by expanding domain models and service interactions.

##### Elements
- Clear Labels: Mark each component clearly (e.g., “UI Overlay Component”, “AppController”, “LcuService”, “Game Data Model”).
- Another for the Service/External API integration layer.
- And a different one for the Domain/Model components.
- Annotations: Add notes that indicate key libraries used (Google Gson, R4J, JNA) or significant design decisions (event synthesis for user inputs, external API call patterns).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer"
        UIOverlay["UI Overlay Component"]:::ui
        InputHandler["Input Handler"]:::ui
    end

    subgraph "Controller / Business Logic"
        AppController["Core Application Controller"]:::controller
    end

    subgraph "Domain/Model Layer"
        Domain["Game Data Model"]:::domain
    end

    subgraph "Service / External API Integrations"
        Services["Service Layer (External API Integrations)"]:::service
        ExternalSystems["External Systems/APIs (Riot, ddragon, op.gg)"]:::external
    end

    subgraph "Native / Platform Integration"
        Native["Native Libraries (JNA, etc.)"]:::native
    end

    subgraph "Data & Configuration"
        DataConfig["Raw Data & Maven Build Config"]:::data
    end

    %% Connections
    UIOverlay -->|"user-interaction"| InputHandler
    InputHandler -->|"event-forwarding"| AppController
    AppController -->|"UI-update"| UIOverlay
    AppController -->|"state-update"| Domain
    AppController -->|"trigger-API"| Services
    Services -->|"data-fetch"| ExternalSystems
    Services -->|"test-data"| DataConfig
    InputHandler -->|"native-calls"| Native

    %% Click Events
    click UIOverlay "https://github.com/djalilhebal/super-scoreboard/tree/main/src/main/java/me/djalil/scoreboard/components"
    click InputHandler "https://github.com/djalilhebal/super-scoreboard/blob/main/src/main/java/me/djalil/scoreboard/App.java"
    click InputHandler "https://github.com/djalilhebal/super-scoreboard/blob/main/src/main/java/me/djalil/scoreboard/MyUser32.java"
    click AppController "https://github.com/djalilhebal/super-scoreboard/blob/main/src/main/java/me/djalil/scoreboard/AppController.java"
    click Domain "https://github.com/djalilhebal/super-scoreboard/tree/main/src/main/java/me/djalil/scoreboard/model"
    click Services "https://github.com/djalilhebal/super-scoreboard/tree/main/src/main/java/me/djalil/scoreboard/services"
    click DataConfig "https://github.com/djalilhebal/super-scoreboard/tree/main/raw-data"
    click DataConfig "https://github.com/djalilhebal/super-scoreboard/blob/main/pom.xml"

    %% Styles
    classDef ui fill:#D1E8FF,stroke:#084298,stroke-width:2px;
    classDef controller fill:#FFF2CC,stroke:#c48f00,stroke-width:2px;
    classDef domain fill:#E1D5E7,stroke:#7030A0,stroke-width:2px;
    classDef service fill:#C9DAF8,stroke:#1F497D,stroke-width:2px;
    classDef external fill:#FCE5CD,stroke:#C65911,stroke-width:2px;
    classDef native fill:#FFE6CC,stroke:#B45F04,stroke-width:2px;
    classDef data fill:#F8CECC,stroke:#992A2A,stroke-width:2px;
```
