# thebrutalx/factorio-mod-uploader-action architecture

> Architecture diagram of the GitHub repository thebrutalx/factorio-mod-uploader-action, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thebrutalx/factorio-mod-uploader-action
- Repository: https://github.com/thebrutalx/factorio-mod-uploader-action

## Overview

##### Project type and purpose
- This is a GitHub Action implemented in Node.js/TypeScript whose sole purpose is to automate packaging and uploading of Factorio mods to the Factorio Mod Portal.
- The README confirms three action phases: “validate” (check mod metadata), “compress” (zip the mod), and “upload” (send the zip via Factorio API).

##### File structure
- Top-level files:
- action.yml – action metadata (inputs, outputs, entrypoint)
- dist/bundle.js – compiled & bundled action code
- src/index.ts – main entrypoint that delegates to phases
- src/phases/ – contains the three core processes: validate.ts, compress.ts, upload.ts plus baseProcess.ts
- src/services/ – parsing logic (FactorioIgnoreParser, FactorioModInfoParser) and FactorioModPortalApiService (HTTP client and interfaces)
- src/utils/ – helper modules (ActionHelper for I/O, zipper for archive creation)
- src/interfaces, src/types, src/constants, src/errors – type definitions and error classes supporting the core logic
- Build & test config: tsconfig.json, webpack.config.js, jest.config.js, tests in src/__tests__.

##### README for additional insights
- Describes usage in a GitHub workflow: three sequential steps—validate, compress, upload—each implemented by the same action package but with different `with: action:` inputs.
- Points out integration with actions/checkout and secret inputs for the API key.

a. Main components
1. GitHub Actions Runner (host environment)
2. Action Definition (action.yml)
3. Node.js Runtime & Entrypoint (dist/bundle.js ↔ src/index.ts)
4. Phase Orchestrator (baseProcess.ts)
5. Phase Implementations:
- Validate Phase (src/phases/validate.ts)
- Compress Phase (src/phases/compress.ts + zipper util)
- Upload Phase (src/phases/upload.ts + FactorioModPortalApiService)
6. Parsers & Utilities (FactorioIgnoreParser, FactorioModInfoParser, ActionHelper)
7. External Service: Factorio Mod Portal API
8. Developer Tools (tests, build scripts) – optional to show or keep separate
b. Relationships & interactions
- The GitHub Runner loads action.yml → spawns Node.js process → executes bundled entrypoint.
- Entrypoint reads input parameters (action type, API key, etc.) via ActionHelper.
- Entrypoint instantiates BaseProcess, which in turn invokes the selected Phase module.
- Validate Phase uses FactorioModInfoParser and FactorioIgnoreParser to check project structure and manifest.
- Compress Phase zips the mod folder using zipper utility.
- Upload Phase calls FactorioModPortalApiService (HTTP client) to send the zip file, using the API key.
- Errors bubble up into custom error classes; successful steps emit outputs back to GitHub via ActionHelper.
c. Architectural patterns & design principles
- Strategy pattern: phases share a common BaseProcess interface (IBaseProcess).
- Single-responsibility modules: parsers, services, utils are decoupled.
- Dependency injection via inputs/options rather than hard-coded values.
- All external side-effects (file I/O, HTTP calls) abstracted behind utility/service layers.
d. Key technologies/frameworks
- Node.js & TypeScript
- Webpack for bundling into dist/bundle.js
- Jest for testing
- GitHub Actions metadata (action.yml) and Runner environment variables

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "GitHub Workflow"
        Workflow["GitHub Actions Workflow"]:::external
    end

    subgraph "Runner Environment"
        Runner["GitHub Actions Runner"]:::external
    end

    subgraph "Action Code"
        AD["Action Definition\naction.yml"]:::internal
        EntrypointDist["Bundle\ndist/bundle.js"]:::internal
        EntrypointSrc["Entrypoint\nsrc/index.ts"]:::internal
        Base["BaseProcess\nsrc/phases/baseProcess.ts"]:::internal
        subgraph "Phases"
            Val["Validate Phase\nsrc/phases/validate.ts"]:::internal
            Comp["Compress Phase\nsrc/phases/compress.ts"]:::internal
            Upload["Upload Phase\nsrc/phases/upload.ts"]:::internal
        end
    end

    subgraph "Services & Utilities"
        ParserIgnore["FactorioIgnoreParser\nsrc/services/FactorioIgnoreParser.ts"]:::util
        ParserInfo["FactorioModInfoParser\nsrc/services/FactorioModInfoParser.ts"]:::util
        ApiService["FactorioModPortalApiService\nsrc/services/FactorioModPortalApiService/index.ts"]:::util
        Helper["ActionHelper\nsrc/utils/ActionHelper.ts"]:::util
        Zipper["Zipper Utility\nsrc/utils/zipper.ts"]:::util
        subgraph "Interfaces & Types"
            IProc["IBaseProcess\nsrc/interfaces/IBaseProcess.ts"]:::internal
            IIgnore["IFactorioIgnoreRule\nsrc/interfaces/IFactorioIgnoreRule.ts"]:::internal
            IModInfo["IFactorioModInfo\nsrc/interfaces/IFactorioModInfo.ts"]:::internal
            Const["Constants\nsrc/constants.ts"]:::internal
            Types["FactorioTypes\nsrc/types/FactorioTypes.ts"]:::internal
            InputTypes["Input Types\nsrc/types/input.ts"]:::internal
        end
        Errors["Errors\nsrc/errors/FactorioModPortalApiErrors.ts"]:::error
    end

    subgraph "External Service"
        Portal["Factorio Mod Portal API"]:::external
    end

    subgraph "Developer Tools"
        Tests["Tests\nsrc/__tests__/**/*.test.ts"]:::devtools
        TSConfig["tsconfig.json"]:::devtools
        Webpack["webpack.config.js"]:::devtools
        JestConfig["jest.config.js"]:::devtools
    end

    Workflow -->|"triggers"| Runner
    Runner -->|"loads action.yml"| AD
    AD -->|"entrypoint"| EntrypointDist
    EntrypointDist -->|"executes"| EntrypointSrc
    EntrypointSrc -->|"reads inputs"| Helper
    EntrypointSrc -->|"instantiates"| Base
    Base -->|"executes validate"| Val
    Base -->|"executes compress"| Comp
    Base -->|"executes upload"| Upload
    Val -->|"reads manifest"| ParserInfo
    Val -->|"reads .factorioignore"| ParserIgnore
    Comp -->|"creates zip"| Zipper
    Upload -->|"posts zip"| ApiService
    ApiService -->|"HTTP POST"| Portal
    Helper -->|"I/O to Runner"| Runner

    click Workflow "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/.github/workflows/*.yml"
    click AD "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/action.yml"
    click EntrypointSrc "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/index.ts"
    click EntrypointDist "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/dist/bundle.js"
    click Base "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/phases/baseProcess.ts"
    click Val "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/phases/validate.ts"
    click Comp "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/phases/compress.ts"
    click Upload "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/phases/upload.ts"
    click ParserIgnore "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/services/FactorioIgnoreParser.ts"
    click ParserInfo "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/services/FactorioModInfoParser.ts"
    click ApiService "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/services/FactorioModPortalApiService/index.ts"
    click Helper "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/utils/ActionHelper.ts"
    click Zipper "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/utils/zipper.ts"
    click IProc "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/interfaces/IBaseProcess.ts"
    click IIgnore "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/interfaces/IFactorioIgnoreRule.ts"
    click IModInfo "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/interfaces/IFactorioModInfo.ts"
    click Const "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/constants.ts"
    click Types "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/types/FactorioTypes.ts"
    click InputTypes "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/types/input.ts"
    click Errors "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/errors/FactorioModPortalApiErrors.ts"
    click Tests "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/src/__tests__/**/*.test.ts"
    click TSConfig "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/tsconfig.json"
    click Webpack "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/webpack.config.js"
    click JestConfig "https://github.com/thebrutalx/factorio-mod-uploader-action/blob/main/jest.config.js"

    classDef internal fill:#E0F7FA,stroke:#000
    classDef util fill:#E8F5E9,stroke:#000
    classDef external fill:#FFE0B2,stroke:#000
    classDef devtools fill:#CFD8DC,stroke:#000
    classDef error fill:#FFCDD2,stroke:#000
```
