# ogame-infinity/web-extension architecture

> Architecture diagram of the GitHub repository ogame-infinity/web-extension, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ogame-infinity/web-extension
- Repository: https://github.com/ogame-infinity/web-extension

## Overview

##### Project Type and Purpose
- This is a cross-browser (Chrome/Firefox/Edge) extension for the Ogame web game.
- It injects scripts into the Ogame page (content scripts), runs a background process, provides a popup/overview UI, and fetches/analyzes game data (players, planets, alliances, messages).

##### File Structure
- Top-level:
– manifest.json + manifestv2.json
– background.js (background/service worker)
– packaging.sh, build/config files, docs
- src/ctxcontent: all content-script modules injected into the game page
– callbacks, helpers, services (fetch Ogame data, store, analyze messages)
- src/ctxpage: UI pages loaded in extension popups or tabs (OverviewPage.js, messages analyzer UI, configuration)
- src/util: shared utilities (DOM helpers, data models, storage wrappers, messaging)
- src/assets + src/libs: static TSV data, fonts, images, Chart.js + plugins
- src/main.js & src/ogkush.js: entry points for registering context menus, initializing background listeners, and wiring everything together.

##### Harvest Insights from the README
- Monolithic JS codebase, uses 3rd-party libs (Chart.js, chartjs-plugin-labels, DOMPurify, lz-string).
- Automated CI/CD via GitHub Actions and packaging.sh.
- No direct local testing (must package to load).

##### Main Components & Their Roles
a. Manifest
– Declares extension metadata, permissions (webRequest, storage, contextMenus, activeTab), scripts.
b. Background Script (background.js & main.js)
– Central event hub, handles context-menu clicks, message routing between UI and content scripts, persistent storage access, scheduling updates.
c. Content Scripts (ctxcontent/)
– Inject into Ogame pages, scrape game data via XHR/DOM, call services/request.* to fetch alliance/highscore/planet/player data, store/cache via universe.storage, run analyzers on in-game messages.
d. UI Pages (ctxpage/)
– Popup and overview pages, render charts (Chart.js) and tables, consume analysis results, allow user configuration.
e. Services & Analyzers (ctxcontent/services & services/analyzer)
– Low-level request modules to Ogame endpoints, plus analyzers for expeditions, fights, harvests, trades, espionage.
f. Utilities (util/)
– Shared modules for fetching, date/time, DOM manipulation, notifications, internationalization, message passing, local storage abstraction, logging.
g. Assets & Third-Party Libraries
– Fonts, images, static data (expeditions.tsv), Chart.js and plugins, DOMPurify, lz-string.

##### Relationships & Data Flows
- Background ↔ Content Scripts: chrome.runtime.sendMessage / onMessage
- Content Scripts ↔ Ogame API: XHR/fetch calls in request.* modules
- Content Scripts ↔ Local Storage: universe.storage (caching, expirations)
- UI Pages ↔ Background: for persistent data reads/writes, config options
- Packaging/CD: packaging.sh bundles + minifies all JS and assets.

##### Architectural Patterns & Design Principles
- Modular separation: content vs. UI vs. background
- Message-driven communication (pub/sub via chrome.runtime)
- Single responsibility: each analyzer/service handles one data type
- Caching & TTL: universe.storage with expirations
- Pluggable charting: Chart.js + plugin architecture
- Strict manifest-driven registration of all components

##### Final Checklist
- Annotations for third-party libraries and build pipeline.
- Versioning/packaging step illustrated if desired.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Manifest
    subgraph "Manifest" 
        manifest1["manifest.json"]:::manifest
        manifest2["manifestv2.json"]:::manifest
    end

    %% Background
    subgraph "Background Service Worker" 
        bg_js["background.js"]:::background
        main_js["main.js"]:::background
        ogkush_js["ogkush.js"]:::background
    end

    %% Content Scripts
    subgraph "Content Scripts" 
        ctx_index["index.js"]:::content
        data_helper["data-helper.js"]:::content
        exp_callback["callbacks/expedition-type.js"]:::content
        uni_alliances["helpers/universe.alliances.js"]:::content
        uni_data["helpers/universe.data.js"]:::content
        uni_highscore["helpers/universe.highscore.js"]:::content
        uni_planets["helpers/universe.planets.js"]:::content
        uni_players["helpers/universe.players.js"]:::content

        subgraph "Services & Analyzers" 
            req_alliances["request.ogameAlliances.js"]:::service
            req_highscore["request.ogameHighscore.js"]:::service
            req_planets["request.ogamePlanets.js"]:::service
            req_players["request.ogamePlayers.js"]:::service
            req_server["request.ogameServerData.js"]:::service
            uni_exp["universe.expirations.js"]:::service
            uni_storage["universe.storage.js"]:::service
            exp_analyzer["ExpeditionMessagesAnalyzer.js"]:::service
            fight_analyzer["FightMessagesAnalyzer.js"]:::service
            harvest_analyzer["HarvestMessagesAnalyzer.js"]:::service
            trade_analyzer["TradeMessagesAnalyzer.js"]:::service
            spy_analyzer["SpyMessagesAnalyzer.js"]:::service
            spy_report["SpyReport.js"]:::service
        end
    end

    %% UI Pages
    subgraph "UI Pages" 
        conf_opts["conf-options.js"]:::ui
        overview_ui["OverviewPage.js"]:::ui
        msg_analyzer_ui["messages-analyzer/index.js"]:::ui
        msg_index_ui["messages/index.js"]:::ui
    end

    %% Utilities
    utilities["Utilities (src/util/)"]:::util

    %% Assets & Third-Party Libraries
    subgraph "Assets & 3rd-Party Libs" 
        assets["assets/"]:::asset
        libs["chartjs-plugin-labels.js + Chart.js"]:::asset
    end

    %% External and Storage
    ogame_api["Ogame API Servers"]:::external
    storage["browser.storage.local"]:::storage

    %% Packaging & CI/CD
    pipeline["packaging.sh & .github/workflows/main.yml"]:::pipeline
    artifact["Deployable .zip"]:::artifact

    %% Connections
    manifest1 --> background
    manifest2 --> background
    manifest1 --> ctx_index
    manifest2 --> ctx_index
    manifest1 --> conf_opts
    manifest2 --> conf_opts

    conf_opts -->|open UI| overview_ui
    conf_opts -->|open UI| msg_analyzer_ui
    conf_opts -->|open UI| msg_index_ui

    overview_ui -->|"sendMessage"| background
    msg_analyzer_ui -->|"sendMessage"| background
    msg_index_ui -->|"sendMessage"| background

    background -->|"chrome.runtime.sendMessage"| ctx_index
    ctx_index -->|"chrome.runtime.onMessage"| background

    ctx_index --> req_alliances
    ctx_index --> req_highscore
    ctx_index --> req_planets
    ctx_index --> req_players
    ctx_index --> req_server
    ctx_index --> uni_exp
    ctx_index --> uni_storage
    ctx_index --> exp_analyzer
    ctx_index --> fight_analyzer
    ctx_index --> harvest_analyzer
    ctx_index --> trade_analyzer
    ctx_index --> spy_analyzer

    ctx_index -->|"fetch/XHR"| ogame_api
    ctx_index -->|"cache"| storage
    overview_ui --> utilities
    background --> utilities
    ctx_index --> utilities

    overview_ui -->|"render charts"| libs
    exp_analyzer --> assets

    pipeline --> bg_js
    pipeline --> ctx_index
    pipeline --> overview_ui
    pipeline --> artifact

    %% Click Events
    click manifest1 "https://github.com/ogame-infinity/web-extension/blob/master/src/manifest.json"
    click manifest2 "https://github.com/ogame-infinity/web-extension/blob/master/src/manifestv2.json"
    click bg_js "https://github.com/ogame-infinity/web-extension/blob/master/src/background.js"
    click main_js "https://github.com/ogame-infinity/web-extension/blob/master/src/main.js"
    click ogkush_js "https://github.com/ogame-infinity/web-extension/blob/master/src/ogkush.js"
    click ctx_index "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/index.js"
    click data_helper "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/data-helper.js"
    click exp_callback "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/callbacks/expedition-type.js"
    click uni_alliances "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/helpers/universe.alliances.js"
    click uni_data "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/helpers/universe.data.js"
    click uni_highscore "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/helpers/universe.highscore.js"
    click uni_planets "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/helpers/universe.planets.js"
    click uni_players "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/helpers/universe.players.js"
    click req_alliances "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/request.ogameAlliances.js"
    click req_highscore "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/request.ogameHighscore.js"
    click req_planets "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/request.ogamePlanets.js"
    click req_players "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/request.ogamePlayers.js"
    click req_server "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/request.ogameServerData.js"
    click uni_exp "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/universe.expirations.js"
    click uni_storage "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/universe.storage.js"
    click exp_analyzer "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/analyzer/ExpeditionMessagesAnalyzer.js"
    click fight_analyzer "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/analyzer/FightMessagesAnalyzer.js"
    click harvest_analyzer "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/analyzer/HarvestMessagesAnalyzer.js"
    click trade_analyzer "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/analyzer/TradeMessagesAnalyzer.js"
    click spy_analyzer "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/analyzer/SpyMessagesAnalyzer.js"
    click spy_report "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxcontent/services/analyzer/Object/SpyReport.js"
    click conf_opts "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxpage/conf-options.js"
    click overview_ui "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxpage/overview/OverviewPage.js"
    click msg_analyzer_ui "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxpage/messages-analyzer/index.js"
    click msg_index_ui "https://github.com/ogame-infinity/web-extension/blob/master/src/ctxpage/messages/index.js"
    click utilities "https://github.com/ogame-infinity/web-extension/tree/master/src/util/"
    click assets "https://github.com/ogame-infinity/web-extension/tree/master/src/assets/"
    click libs "https://github.com/ogame-infinity/web-extension/blob/master/src/libs/chartjs-plugin-labels.js"
    click pipeline "https://github.com/ogame-infinity/web-extension/blob/master/packaging.sh"
    
    %% Styles
    classDef manifest fill:#f9f,stroke:#333,stroke-width:1px
    classDef background fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef content fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px
    classDef service fill:#e1bee7,stroke:#8e24aa,stroke-width:1px
    classDef ui fill:#ffe0b2,stroke:#f57c00,stroke-width:1px
    classDef util fill:#eeeeee,stroke:#757575,stroke-width:1px
    classDef asset fill:#d7ccc8,stroke:#5d4037,stroke-width:1px
    classDef external fill:#b0bec5,stroke:#546e7a,stroke-width:1px
    classDef storage fill:#fff9c4,stroke:#fbc02d,stroke-width:1px
    classDef pipeline fill:#cfd8dc,stroke:#607d8b,stroke-width:1px
    classDef artifact fill:#dcedc8,stroke:#558b2f,stroke-width:1px
```
