# rklos/wng-system-translation-pl architecture

> Architecture diagram of the GitHub repository rklos/wng-system-translation-pl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rklos/wng-system-translation-pl
- Repository: https://github.com/rklos/wng-system-translation-pl

## Overview

##### Project Type and Purpose
- This is a Foundry VTT “system translation” module: a plugin that provides Polish translations for the Wrath & Glory RPG system on the Foundry Virtual Tabletop platform.
- It is neither a full-stack web app nor a microservice suite, but a client-side plugin with a build pipeline that produces static assets (JSON, compiled templates, JavaScript) which are loaded by Foundry VTT at runtime.

##### High-Level Architecture Components
a. Foundry VTT Host
- The sandboxed browser-based application that discovers and loads modules/plugins.
- Provides the runtime environment (UI, chat system, actor sheets, i18n subsystem).
b. Wrath & Glory Core System (External Dependency)
- The official Foundry system package by Moo-Man. Provides data model, default English templates, UI components.
c. Translation Module
- module.json: metadata, dependency declaration on the core system.
- src/lang/*.json: translation key/value pairs for “system” and “custom” terms.
- src/template/**/*.hbs: Handlebars templates overriding or augmenting core UI (chat messages, dialogs, item traits).
- src/scripts/*.js & utils: small runtime scripts (e.g., reorder-skills) that further adapt behavior on game startup.
d. Build Pipeline
- rollup.config.js + .rollup/list-templates.js: orchestrate bundling of JS modules and templates into a single distributable file (usually dist/bundle.js).
- scripts/*.js: Node scripts to merge JSONs, generate template lists, report changes, used by CI workflows.
- GitHub Actions workflows (.github/workflows/*.yml): automate building on tag and generating change reports.
e. Distribution Package
- The final ZIP (or GitHub release) containing module.json, bundle.js, JSON data, templates—ready for installation into Foundry VTT.

##### Relationships and Data Flows
- At build time:
- JSON sources (src/lang) + Handlebars templates (src/template) + JS scripts → Rollup & custom scripts → bundled assets.
- CI workflows trigger builds and publish artifacts.
- At runtime in Foundry VTT:
- Foundry loads module.json → sees dependency on Wrath & Glory core → loads core system first.
- Module’s bundle.js registers translation strings with Foundry’s i18n API and overrides template partials.
- When rendering Actor sheets or chat messages, Foundry calls the overridden Handlebars templates, pulling in translated labels.

##### Architectural Patterns & Design Principles
- Plugin/Extension Pattern: the module declares itself to Foundry and plugs into its hook system.
- Build-then-Deploy: static site/app style—separate build pipeline produces immutable artifacts.
- Conventions-over-Configuration: relying on Foundry’s established directory/layout conventions (lang/, template/).
- Template Overriding: using Handlebars partials to override or extend core system views.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Environment Layer
    subgraph "Runtime Environment"
        direction TB
        FT["Foundry VTT Host"]:::host
        CS["Wrath & Glory Core System"]:::host
        TM["Translation Module"]:::module
    end

    FT -->|"loads dependency"| CS
    CS -->|"loads module.json"| TM
    TM -->|"registers translations & overrides"| FT

    %% Translation Module Internals
    subgraph "Translation Module Internals"
        direction TB
        MJ["module.json"]:::module
        JSONS["Translation JSON Files"]:::module
        TMPL["Handlebars Templates"]:::module
        SCRIPTS["Runtime Override Scripts"]:::module
    end

    TM --> MJ
    TM --> JSONS
    TM --> TMPL
    TM --> SCRIPTS

    %% JSON and templates breakdown
    subgraph "JSON Files" 
        direction TB
        SYS["system.json"]:::module
        CUS["custom.json"]:::module
    end
    JSONS --> SYS
    JSONS --> CUS

    subgraph "Templates Directory"
        direction TB
        TDIR["src/template/"]:::module
    end
    TMPL --> TDIR

    subgraph "Scripts"
        direction TB
        MJS["main.js"]:::module
        OTJS["override-templates.js"]:::module
        RJS["reorder-skills.js"]:::module
        UTLOG["utils/log.js"]:::module
        UTWAIT["utils/wait.js"]:::module
    end
    SCRIPTS --> MJS
    SCRIPTS --> OTJS
    SCRIPTS --> RJS
    SCRIPTS --> UTLOG
    SCRIPTS --> UTWAIT

    %% Build & CI Pipeline Layer
    subgraph "Build & CI Pipeline"
        direction TB
        subgraph "Build Tools"
            direction TB
            ROLLUP["Rollup Bundler\n(rollup.config.js + list-templates.js)"]:::build
            BJSON["bundle-jsons.js"]:::build
            LAT["get-latest-changes.js"]:::build
            RCHG["report-changes.js"]:::build
        end
        subgraph "CI Workflows"
            direction TB
            REL["release.yml"]:::ci
            RPT["report-changes.yml"]:::ci
        end
        ART["dist/bundle.js"]:::output
        REL -->|"triggers build"| ROLLUP
        LAT --> ROLLUP
        BJSON --> ROLLUP
        RCHG --> ROLLUP
        ROLLUP -->|"outputs"| ART
        ART -->|"publishes to GitHub Releases"| REL
    end

    %% Click Events
    click MJ "https://github.com/rklos/wng-system-translation-pl/blob/main/src/module.json"
    click SYS "https://github.com/rklos/wng-system-translation-pl/blob/main/src/lang/system.json"
    click CUS "https://github.com/rklos/wng-system-translation-pl/blob/main/src/lang/custom.json"
    click TDIR "https://github.com/rklos/wng-system-translation-pl/tree/main/src/template/"
    click MJS "https://github.com/rklos/wng-system-translation-pl/blob/main/src/scripts/main.js"
    click OTJS "https://github.com/rklos/wng-system-translation-pl/blob/main/src/scripts/override-templates.js"
    click RJS "https://github.com/rklos/wng-system-translation-pl/blob/main/src/scripts/reorder-skills.js"
    click UTLOG "https://github.com/rklos/wng-system-translation-pl/blob/main/src/scripts/utils/log.js"
    click UTWAIT "https://github.com/rklos/wng-system-translation-pl/blob/main/src/scripts/utils/wait.js"
    click ROLLUP "https://github.com/rklos/wng-system-translation-pl/blob/main/rollup.config.js"
    click ROLLUP "https://github.com/rklos/wng-system-translation-pl/blob/main/.rollup/list-templates.js"
    click BJSON "https://github.com/rklos/wng-system-translation-pl/blob/main/scripts/bundle-jsons.js"
    click LAT "https://github.com/rklos/wng-system-translation-pl/blob/main/scripts/get-latest-changes.js"
    click RCHG "https://github.com/rklos/wng-system-translation-pl/blob/main/scripts/report-changes.js"
    click REL "https://github.com/rklos/wng-system-translation-pl/blob/main/.github/workflows/release.yml"
    click RPT "https://github.com/rklos/wng-system-translation-pl/blob/main/.github/workflows/report-changes.yml"

    %% Styles
    classDef host fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef module fill:#98FB98,stroke:#000,stroke-width:1px
    classDef build fill:#FFD580,stroke:#000,stroke-width:1px
    classDef ci fill:#FFD580,stroke-dasharray: 5 5,stroke:#000,stroke-width:1px
    classDef output fill:#FFF8DC,stroke:#000,stroke-width:1px
```
