# matlab-actions/setup-matlab architecture

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

- Interactive diagram: https://gitdiagram.com/matlab-actions/setup-matlab
- Repository: https://github.com/matlab-actions/setup-matlab

## Overview

##### Project Type and Purpose
- This is an open-source GitHub Action (matlab-actions/setup-matlab) implemented in TypeScript.
- Purpose: download, install, and configure MATLAB (and optional MathWorks products) on GitHub-hosted or self-hosted runners, with optional caching.

##### File Structure
Top-level artifacts:
- action.yml         → metadata & I/O contract for the Action
- src/               → TypeScript source, subdivided into:
– index.ts        → primary entrypoint (runs in “with” step)
– post.ts         → post-action cleanup (runs in “post” step)
– install.ts      → logic to fetch/install MATLAB via MPM
– cache-restore.ts / cache-save.ts / cache-state.ts
→ logic to restore/record/save cache
– script.ts       → handles optional custom MATLAB script invocation
– mpm.ts          → abstraction for MATLAB Package Manager (mpm) CLI
– matlab.ts       → abstraction for MATLAB CLI details
– *.unit.test.ts  → Jest tests for each module
– properties.json → static definitions consumed by toolkit
- package.json, tsconfig.json, jest.config.js → build/test configuration
- .github/workflows/*.yml → CI for lint, test, and publish

##### Architecture Insights from README
- Inputs: release, products, cache
- Steps in a typical workflow:
a. GitHub runner checks out code
b. “Setup MATLAB” action runs (this package)
- Pre-step (index.ts): parse inputs, try cache restore
- Install step: invoke install.ts → download MPM → run `mpm install`
- Post-step (post.ts): record state & save cache
c. Subsequent MATLAB-related actions use PATH

##### Main Components
A. GitHub Actions Runner
– executes steps defined in user workflow
– provides environment, file system, networking
B. “Setup MATLAB” Action Container
– Node.js runtime
– index.ts (main)
– post.ts (cleanup)
C. Submodules (all in src/)
1. Input Parser & Orchestrator
– reads action.yml inputs via @actions/core
2. Cache Layer
– cache-restore.ts → tries GitHub cache restore
– cache-state.ts   → writes metadata for post step
– cache-save.ts    → restores or saves cache
3. Installer Layer
– install.ts       → pulls mpm, invokes mpm.ts
– mpm.ts           → wraps `mpm` CLI calls
4. MATLAB Abstraction
– matlab.ts        → wraps `matlab` CLI details
5. Script Runner (optional)
– script.ts        → runs user-specified MATLAB commands
D. External Services
– GitHub Cache Service (REST API & local cache store)
– MathWorks package servers (for MPM downloads)

##### Component Relationships & Data Flow
1. Workflow → Runner → Action container
2. index.ts reads inputs → calls cache-restore → (if hit) populates installation directory
3. index.ts → calls install.ts → mpm.ts ↔ network ↔ MathWorks servers
4. install.ts → on success writes PATH via @actions/core
5. index.ts → if `script` input provided, invokes script.ts → matlab.ts
6. Post step (post.ts) retrieves cache-state → calls cache-save → cache service
7. Runner → next steps in workflow

##### Architectural Patterns & Principles
- Single Responsibility: each module handles one concern (cache, install, script)
- Orchestration vs. implementation separation: index.ts & post.ts orchestrate, modules implement
- Declarative metadata (action.yml) driving dynamic behavior
- Layered external interaction: Node.js → GitHub Actions Toolkit → GitHub Services / OS / Network

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "GitHub Runner Environment"
        style RunnerEnv fill:#f0f0f0,stroke:#888,stroke-width:1px
        RunnerEnv["GitHub Actions Runner"]
    end

    subgraph "Action Container (Node.js Runtime)"
        style Container fill:#ffffff,stroke:#888,stroke-width:1px
        YM["action.yml"]:::metadata
        IDX["index.ts"]:::core
        PST["post.ts"]:::core

        subgraph "Cache Layer"
            CR["cache-restore.ts"]:::utility
            CS["cache-state.ts"]:::utility
            CSave["cache-save.ts"]:::utility
        end

        subgraph "Installer Layer"
            INST["install.ts"]:::utility
            MPM["mpm.ts"]:::utility
        end

        subgraph "MATLAB Abstraction"
            ML["matlab.ts"]:::utility
        end

        subgraph "Script Runner"
            SCR["script.ts"]:::utility
        end

        PP["properties.json"]:::metadata
    end

    CacheService["GitHub Cache Service"]:::external
    MWS["MathWorks Package Servers"]:::external

    RunnerEnv -->|workflow invocation| IDX
    YM -->|inputs: release,products,cache| IDX
    IDX -->|restore cache| CR
    CR -->|REST API call| CacheService
    CR -->|cache hit| IDX

    IDX -->|install MATLAB| INST
    INST -->|uses MPM CLI| MPM
    MPM -->|download packages| MWS
    INST -->|set PATH via @actions/core| RunnerEnv

    IDX -->|run script if provided| SCR
    SCR -->|invoke MATLAB CLI| ML

    IDX -->|end pre-step| PST
    PST -->|record state| CS
    PST -->|save cache| CSave
    CSave -->|REST API call| CacheService
    PST -->|finish post-step| RunnerEnv

    click YM "https://github.com/matlab-actions/setup-matlab/blob/main/action.yml"
    click IDX "https://github.com/matlab-actions/setup-matlab/blob/main/src/index.ts"
    click PST "https://github.com/matlab-actions/setup-matlab/blob/main/src/post.ts"
    click CR "https://github.com/matlab-actions/setup-matlab/blob/main/src/cache-restore.ts"
    click CS "https://github.com/matlab-actions/setup-matlab/blob/main/src/cache-state.ts"
    click CSave "https://github.com/matlab-actions/setup-matlab/blob/main/src/cache-save.ts"
    click INST "https://github.com/matlab-actions/setup-matlab/blob/main/src/install.ts"
    click MPM "https://github.com/matlab-actions/setup-matlab/blob/main/src/mpm.ts"
    click ML "https://github.com/matlab-actions/setup-matlab/blob/main/src/matlab.ts"
    click SCR "https://github.com/matlab-actions/setup-matlab/blob/main/src/script.ts"
    click PP "https://github.com/matlab-actions/setup-matlab/blob/main/src/properties.json"
    click TSConfig "https://github.com/matlab-actions/setup-matlab/blob/main/tsconfig.json"
    click JestConfig "https://github.com/matlab-actions/setup-matlab/blob/main/jest.config.js"
    click LintWF "https://github.com/matlab-actions/setup-matlab/blob/main/.github/workflows/bat.yml"
    click PublishWF "https://github.com/matlab-actions/setup-matlab/blob/main/.github/workflows/publish.yml"

    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef utility fill:#d4edda,stroke:#155724,color:#155724;
    classDef metadata fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
```
