# liquipedia/lua-modules architecture

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

- Interactive diagram: https://gitdiagram.com/liquipedia/lua-modules
- Repository: https://github.com/liquipedia/lua-modules

## Overview

##### Project type and purpose
- This is a monorepo for a library of Liquipedia “Lua Modules” and accompanying assets (JavaScript widgets and SCSS styles) that run inside MediaWiki pages. It’s not a traditional client-server app but a collection of content-rendering modules, asset pipelines, test suites, and deployment scripts.

##### Top-level architecture analysis
- Source code domains:
– lua/ (Lua modules for complex page logic)
– javascript/ (client-side interactive scripts)
– stylesheets/ (SCSS styling for page elements)
- Build & test:
– npm (JS and SCSS linting/tests/visual snapshot)
– Luarocks + busted + luacheck (Lua linting & unit tests)
- Deployment & CI:
– .github/workflows (GitHub Actions for code style, tests, scheduled jobs, deploy)
– scripts/ (shell and PowerShell scripts for deploying modules into wikis, protecting pages/templates, generating changelogs)

##### Key README insights
- Describes multi-language setup (Lua/LuaJIT, Node/npm/SCSS), local developer tooling, and CI pipelines.
- References “Personal Deploy” GitHub Actions workflow to push to development or test MediaWiki environments.

1. Developer Workstation
- IDE with Lua/JS/SCSS linters & formatters
- Local runtimes: Lua 5.1/LuaJIT + Luarocks, Node.js + npm
2. Source Repository (GitHub)
- Stores lua/, javascript/, stylesheets/, scripts/, CI configs
3. CI/CD System (GitHub Actions)
- Lint jobs (ESLint, Stylelint, luacheck)
- Unit test jobs (busted for Lua, JS tests via Jest or similar)
- Visual snapshot jobs
- Deploy jobs (deploy test, deploy to production wikis)
4. Artifact & Deployment Scripts
- scripts/deploy.sh, deploy_res.sh, protect*.sh
- API calls into MediaWiki to upload modules/templates
5. Target Environments
- Dev MediaWiki environment (via “deploy test.yml”)
- Production Liquipedia wikis (after PR merge)

– Developer → push code → GitHub Repository
– GitHub Repository → triggers → CI/CD pipelines
– CI Runner → checkout code → run lint → run tests → run snapshot tests
– On success: CI → execute deploy scripts → MediaWiki API → publish modules & assets
– Scheduled CI jobs → update visual snapshots, remove dev env, protect pages/templates

c. Architectural patterns & principles:
– Monorepo pattern (multiple languages/assets in one repo)
– Pipeline as Code (GitHub Actions workflows for every stage)
– Separation of concerns:
- Lua: page logic modules
- JS: client interactivity
- SCSS: styles
- Scripts: operational concerns (deploy/protect)
– Test automation & visual regression testing

d. Significant technologies & frameworks:
– Lua + LuaJIT + Luarocks + busted + luacheck
– Node.js + npm + ESLint + Stylelint + Jest (visual snapshots)
– GitHub Actions for CI/CD
– MediaWiki API for module deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Local Development"
        Dev["Developer Workstation"]:::dev
        IDE["IDE + Linters/Formatters"]:::dev
        Runtime["Lua/LuaJIT + Node.js/npm"]:::dev
        subgraph "Code Domains"
            Lua["Lua Modules"]:::code
            JS["JavaScript Widgets"]:::code
            SCSS["SCSS Styles"]:::code
        end
        Dev --> IDE
        Dev --> Runtime
        IDE --> Lua
        IDE --> JS
        IDE --> SCSS
    end

    Dev -->|push code| Repo["GitHub Repository"]:::repo

    subgraph "Cloud CI (GitHub Actions)"
        Scheduled["Scheduled CI Jobs"]:::ci
        Lint["Lint Jobs"]:::ci
        Test["Unit Test Jobs"]:::ci
        Snapshot["Visual Snapshot Jobs"]:::ci
        DeployTest["Personal Deploy Workflow"]:::ci
        DeployProd["Production Deploy Workflow"]:::ci

        Repo -->|cron trigger| Scheduled
        Scheduled --> Lint
        Repo -->|triggers CI| Lint
        Lint --> Test
        Test --> Snapshot
        Repo -->|push to test| DeployTest
        Repo -->|merge to master| DeployProd
        Snapshot --> DeployTest
        Snapshot --> DeployProd
    end

    subgraph "Deployment & Operational Scripts"
        Scripts["scripts/"]:::scripts
        deploySH["deploy.sh"]:::scripts
        protectPage["protect_page.sh"]:::scripts
        protectTemplates["protect_templates.sh"]:::scripts
        changelog["generate_changelog_local.sh"]:::scripts

        Scripts --> deploySH
        Scripts --> protectPage
        Scripts --> protectTemplates
        Scripts --> changelog
    end

    DeployTest --> Scripts
    DeployProd --> Scripts

    subgraph "MediaWiki Environments"
        MWDev["Dev MediaWiki Environment"]:::wiki
        MWProd["Production Liquipedia Wikis"]:::wiki
    end

    Scripts -->|MediaWiki API upload| MWDev
    Scripts -->|MediaWiki API upload| MWProd

    %% Repository configuration files
    Repo --> PackageJSON["package.json & Gruntfile.js"]:::repo
    Repo --> Luarc[".luarc.json"]:::repo
    Repo --> BustedConf["lua/.busted"]:::repo
    Repo --> Luacheck["lua/.luacheckrc"]:::repo
    Repo --> Luacov["lua/.luacov"]:::repo

    %% Click Events
    click Lua "https://github.com/liquipedia/lua-modules/tree/main/lua/"
    click JS "https://github.com/liquipedia/lua-modules/tree/main/javascript/"
    click SCSS "https://github.com/liquipedia/lua-modules/tree/main/stylesheets/"
    click Scheduled "https://github.com/liquipedia/lua-modules/blob/main/.github/workflows/scheduled.yml"
    click DeployTest "https://github.com/liquipedia/lua-modules/blob/main/.github/workflows/deploy test.yml"
    click DeployProd "https://github.com/liquipedia/lua-modules/blob/main/.github/workflows/deploy.yml"
    click Snapshot "https://github.com/liquipedia/lua-modules/blob/main/.github/workflows/update visual snapshots.yml"
    click Repo "https://github.com/liquipedia/lua-modules/tree/main/.github/workflows/"
    click Scripts "https://github.com/liquipedia/lua-modules/tree/main/scripts/"
    click deploySH "https://github.com/liquipedia/lua-modules/blob/main/scripts/deploy.sh"
    click protectPage "https://github.com/liquipedia/lua-modules/blob/main/scripts/protect_page.sh"
    click protectTemplates "https://github.com/liquipedia/lua-modules/blob/main/scripts/protect_templates.sh"
    click changelog "https://github.com/liquipedia/lua-modules/blob/main/scripts/generate_changelog_local.sh"
    click PackageJSON "https://github.com/liquipedia/lua-modules/blob/main/package.json"
    click Luarc "https://github.com/liquipedia/lua-modules/blob/main/.luarc.json"
    click BustedConf "https://github.com/liquipedia/lua-modules/blob/main/lua/.busted"
    click Luacheck "https://github.com/liquipedia/lua-modules/blob/main/lua/.luacheckrc"
    click Luacov "https://github.com/liquipedia/lua-modules/blob/main/lua/.luacov"

    classDef dev fill:#e0f7fa,stroke:#006064
    classDef code fill:#e3f2fd,stroke:#0d47a1
    classDef repo fill:#fff9c4,stroke:#f57f17
    classDef ci fill:#e8f5e9,stroke:#1b5e20
    classDef scripts fill:#fff3e0,stroke:#e65100
    classDef wiki fill:#eceff1,stroke:#37474f
```
