# jordanconway/hw-bom architecture

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

- Interactive diagram: https://gitdiagram.com/jordanconway/hw-bom
- Repository: https://github.com/jordanconway/hw-bom

## Overview

##### Project type and purpose
- This is an open-source GitHub Action, implemented in TypeScript/Node.js, that runs on Linux-based GitHub Actions runners and collects hardware details (CPU, GPU, memory, disk, cloud-metadata) from the host and cloud metadata service.
- The README outlines use cases (CI/CD hardware inventory, validation, reports) and target platforms (AWS, Azure, GCE, OpenStack).

##### File structure
- Top-level artifacts:
- action.yml – declares inputs, outputs, entrypoint.
- src/index.ts & src/main.ts – core logic and CLI wrapper.
- dist/index.js – compiled output invoked at runtime.
- __tests__ & __fixtures__ – unit tests and data fixtures.
- .github/workflows/main.yml – CI building, testing, releasing.
- package.json, tsconfig.json, linting & formatting configs – build and dev toolchain.
- Patterns: simple linear flow (no microservices), modular separation of core logic vs. entrypoint, CI pipeline to publish to npm/GitHub registry.

##### Extract architecture insights from the README
- Action runs on a GitHub runner VM with sudo.
- Internally executes:
- Calls out to OS commands (lshw, uname, free, df).
- Queries cloud metadata endpoints (AWS IMDS, Azure Instance Metadata Service, GCE, OpenStack).
- Parses results and exposes them as GitHub Action outputs.

##### Main components and their interactions
a. GitHub Actions Runner
– A Linux VM/container orchestrated by GitHub.
b. Action Entrypoint
– action.yml invokes dist/index.js via Node.js.
c. Node.js Runtime & Action Code
– index.js loads main.ts logic, executes hardware probes.
– Core module orchestrates:
· Metadata fetchers for each cloud provider
· Shell commands (lshw, uname, free, df) with child_process
· Parsers to normalize output
d. External Services & Tools
– Cloud metadata service endpoints (HTTP calls)
– lshw (via sudo), uname, free, df
e. Outputs
– Aggregated JSON/string results mapped to GitHub Action outputs for downstream steps.
f. CI/CD Pipeline (secondary view)
– .github/workflows/main.yml: build → test (__tests__) → lint → release-drafter → git tag → publish.

##### Architectural patterns & design principles
- Modular separation: metadata fetchers vs. OS command probes vs. output mapper.
- Single responsibility: each module gathers one category of data.
- Graceful error handling: wrappers return fallback messages on failure.
- Build-artifact separation: src/ → dist/ for production code.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runner Layer
    Runner["GitHub Runner"]:::runner

    %% Entrypoint & Runtime
    Entrypoint["action.yml Entrypoint"]:::code
    click Entrypoint "https://github.com/jordanconway/hw-bom/blob/main/action.yml"
    NodeJS["Node.js Runtime\n(dist/index.js)"]:::code
    click NodeJS "https://github.com/jordanconway/hw-bom/blob/main/dist/index.js"
    SrcIndex["src/index.ts\n(Entrypoint Wrapper)"]:::code
    click SrcIndex "https://github.com/jordanconway/hw-bom/blob/main/src/index.ts"
    MainTS["src/main.ts\n(Core Logic)"]:::code
    click MainTS "https://github.com/jordanconway/hw-bom/blob/main/src/main.ts"

    Runner -->|"triggers"| Entrypoint
    Entrypoint -->|"invokes"| NodeJS
    NodeJS -->|"loads wrapper"| SrcIndex
    SrcIndex -->|"calls core"| MainTS

    %% Core Modules
    subgraph "Core Modules" 
        direction TB
        Probe["Hardware Probe Module"]:::code
        CloudMod["Cloud Metadata Module"]:::code
    end

    MainTS -->|"orchestrates"| Probe
    MainTS -->|"orchestrates"| CloudMod

    %% OS Commands
    subgraph "OS Commands" 
        direction TB
        LSHW["lshw"]:::oscmd
        UNAME["uname"]:::oscmd
        FREE["free"]:::oscmd
        DF["df"]:::oscmd
    end

    Probe -->|"executes"| LSHW
    Probe -->|"executes"| UNAME
    Probe -->|"executes"| FREE
    Probe -->|"executes"| DF
    LSHW -->|"returns output"| Probe
    UNAME -->|"returns output"| Probe
    FREE -->|"returns output"| Probe
    DF -->|"returns output"| Probe

    %% Cloud Services
    subgraph "Cloud Metadata Services"
        direction TB
        AWS["AWS IMDS"]:::cloud
        Azure["Azure Instance Metadata Service"]:::cloud
        GCE["GCE Metadata"]:::cloud
        OpenStack["OpenStack Metadata"]:::cloud
    end

    CloudMod -->|"HTTP GET"| AWS
    CloudMod -->|"HTTP GET"| Azure
    CloudMod -->|"HTTP GET"| GCE
    CloudMod -->|"HTTP GET"| OpenStack
    AWS -->|"response"| CloudMod
    Azure -->|"response"| CloudMod
    GCE -->|"response"| CloudMod
    OpenStack -->|"response"| CloudMod

    %% Outputs
    Outputs["GitHub Action Outputs"]:::output
    MainTS -->|"aggregates results"| Outputs

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        CIYML["Build/Test/Release Workflow"]:::ci
        click CIYML "https://github.com/jordanconway/hw-bom/blob/main/.github/workflows/main.yml"
        Tests["Unit Tests\n__tests__/main.test.ts"]:::ci
        click Tests "https://github.com/jordanconway/hw-bom/blob/main/__tests__/main.test.ts"
        Fixtures["Test Fixtures\n__fixtures__/core.ts"]:::ci
        click Fixtures "https://github.com/jordanconway/hw-bom/blob/main/__fixtures__/core.ts"
        subgraph "Build & Dependency Configs"
            direction TB
            PKG["package.json"]:::ci
            click PKG "https://github.com/jordanconway/hw-bom/blob/main/package.json"
            PKGLock["package-lock.json"]:::ci
            click PKGLock "https://github.com/jordanconway/hw-bom/blob/main/package-lock.json"
            TSConfig["tsconfig.json"]:::ci
            click TSConfig "https://github.com/jordanconway/hw-bom/blob/main/tsconfig.json"
        end
        subgraph "Linting & Formatting"
            direction TB
            ESLint["eslint.config.mjs"]:::ci
            click ESLint "https://github.com/jordanconway/hw-bom/blob/main/eslint.config.mjs"
            Prettierrc[".prettierrc.json"]:::ci
            click Prettierrc "https://github.com/jordanconway/hw-bom/blob/main/.prettierrc.json"
            Ignore[".prettierignore"]:::ci
            click Ignore "https://github.com/jordanconway/hw-bom/blob/main/.prettierignore"
            Gitlint[".gitlint"]:::ci
            click Gitlint "https://github.com/jordanconway/hw-bom/blob/main/.gitlint"
            PreCommit[".pre-commit-config.yaml"]:::ci
            click PreCommit "https://github.com/jordanconway/hw-bom/blob/main/.pre-commit-config.yaml"
        end
        subgraph "Licenses"
            direction TB
            License1["LICENSE"]:::ci
            click License1 "https://github.com/jordanconway/hw-bom/tree/main/LICENSE"
            License2["Apache-2.0 License"]:::ci
            click License2 "https://github.com/jordanconway/hw-bom/blob/main/LICENSES/Apache-2.0.txt"
        end
    end

    %% Styles
    classDef runner fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef code fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef oscmd fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20,shape:parallelogram;
    classDef cloud fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00,shape:cylinder;
    classDef output fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A;
    classDef ci fill:#ECEFF1,stroke:#607D8B,color:#37474F;
```
