# atesgoral/hrm-solutions architecture

> Architecture diagram of the GitHub repository atesgoral/hrm-solutions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atesgoral/hrm-solutions
- Repository: https://github.com/atesgoral/hrm-solutions

## Overview

1. This repository is primarily a curated archive of Human Resource Machine assembly solutions, plus a thin static-site and CI layer around that content. The core “application data” is the `solutions/` tree, not a traditional source codebase.

2. `solutions/` is organized by puzzle level. Each level has a folder named like `<level>-<level name>-<size par>.<speed par>`, and inside are multiple `.asm` files representing different submissions/variants. The filename encodes the achieved size and speed, optional strategy/type tags, and the author.

3. The `.asm` files are the main payload: they are Human Resource Machine programs in the game’s assembly-like syntax. Many levels contain multiple approaches for comparison, including “specific”, “unroll”, “exploit”, “obsolete”, and other strategy labels.

4. The repo also carries contributor metadata in `contributors.json`. Combined with the filenames, this supports attribution and presentation of who authored each solution in the site/README ecosystem.

5. The top-level `index.html` suggests a browser-facing static site. The README links to a GitHub Pages deployment for “Top Scores and more info,” so the site likely renders or indexes the solution set for browsing rather than serving dynamic application logic.

6. `gulpfile.js` is the build orchestration layer. It likely bundles, copies, or transforms the content into the static site published by GitHub Pages. This is the repo’s main build boundary: source content in `solutions/` becomes a browsable site artifact.

7. CI/CD is handled through GitHub Actions. `test.yml` runs validation on pull requests, while `build-and-deploy.yml` publishes the site. That creates a clear separation between contributor-facing verification and release/deployment to GitHub Pages.

8. The testing pipeline is architecture-significant because it validates the solution corpus, not just code style. The README states tests perform static/runtime analysis and benchmarking, so correctness and performance are both first-class constraints.

9. The test stack depends on external HRM-specific tooling: `hrm-parser` for static analysis, `hrm-cpu` for execution/runtime analysis, `hrm-level-data` for puzzle constraints, and inbox/outbox generators for benchmark inputs and expected outputs. These tools are what turn the solution archive into an automatically checked dataset.

10. Data flow is roughly: puzzle metadata and generated inboxes feed the test harness; each `.asm` solution is parsed and executed against the level constraints; results determine pass/fail and performance; the validated content is then packaged for the static site and deployed.

11. The project boundaries are therefore: content repository at the center, validation tooling around it, and a static publication layer on top. There is no server-side runtime, database, or API in this repo; the only “live” external dependencies are GitHub Actions/GitHub Pages and the HRM analysis libraries.

12. Practical diagram takeaway: show a large content store of level folders and assembly files, a contributor metadata file, a Node/Yarn-based test/benchmark pipeline using HRM tooling, and a build/deploy path from that verified corpus to a GitHub Pages-hosted static index.

Main entry points: [`package.json`](https://github.com/atesgoral/hrm-solutions/blob/main/package.json) (Package config), [`.github/workflows/test.yml`](https://github.com/atesgoral/hrm-solutions/blob/main/.github/workflows/test.yml) (Test CI), [`solutions`](https://github.com/atesgoral/hrm-solutions/tree/main/solutions) (ASM files), [`contributors.json`](https://github.com/atesgoral/hrm-solutions/blob/main/contributors.json) (Contributors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Solution Archive"]
  node_solutions_root[("Solutions<br/>solution corpus")]
  node_level_puzzles["Level folders<br/>puzzle sets"]
  node_asm_variants["ASM files<br/>hrm programs"]
  node_strategy_tags{{"Strategy tags<br/>filename metadata"}}
end

subgraph group_metadata["Metadata"]
  node_contributors_json["Contributors<br/>attribution data<br/>[contributors.json]"]
  node_readme["README<br/>project guide<br/>[README.md]"]
end

subgraph group_validation["Validation"]
  node_test_workflow["Test CI<br/>github actions<br/>[test.yml]"]
  node_hrm_parser["Parser<br/>static analysis"]
  node_hrm_cpu["CPU runner<br/>runtime analysis"]
  node_level_data[("Level data<br/>puzzle constraints")]
  node_io_generators["I/O generators<br/>benchmark data"]
  node_static_analysis(("Checks<br/>validation stage"))
  node_benchmarking(("Benchmarks<br/>validation stage"))
end

subgraph group_delivery["Build & Delivery"]
  node_index_html["Index page<br/>static site entry<br/>[index.html]"]
  node_gulpfile["Gulp build<br/>build orchestration<br/>[gulpfile.js]"]
  node_package_json["Package config<br/>node workspace<br/>[package.json]"]
  node_build_workflow["Deploy CI<br/>github actions"]
  node_site_publish[("Pages site<br/>published artifact")]
end

node_solutions_root -->|"organizes"| node_level_puzzles
node_level_puzzles -->|"contains"| node_asm_variants
node_asm_variants -->|"encoded by"| node_strategy_tags
node_contributors_json -.->|"attributes"| node_asm_variants
node_readme -.->|"points to"| node_index_html
node_package_json -->|"drives"| node_gulpfile
node_package_json -->|"installs"| node_test_workflow
node_package_json -->|"installs"| node_build_workflow
node_test_workflow -->|"runs"| node_static_analysis
node_test_workflow -->|"runs"| node_benchmarking
node_static_analysis -->|"uses"| node_hrm_parser
node_static_analysis -->|"uses"| node_level_data
node_benchmarking -->|"uses"| node_hrm_cpu
node_benchmarking -->|"uses"| node_io_generators
node_benchmarking -->|"uses"| node_level_data
node_gulpfile -->|"builds"| node_site_publish
node_index_html -->|"served as"| node_site_publish
node_build_workflow -->|"deploys"| node_site_publish
node_site_publish -->|"indexes"| node_solutions_root
node_site_publish -.->|"displays"| node_contributors_json

click node_solutions_root "https://github.com/atesgoral/hrm-solutions/tree/main/solutions"
click node_level_puzzles "https://github.com/atesgoral/hrm-solutions/tree/main/solutions"
click node_asm_variants "https://github.com/atesgoral/hrm-solutions/tree/main/solutions"
click node_strategy_tags "https://github.com/atesgoral/hrm-solutions/tree/main/solutions"
click node_contributors_json "https://github.com/atesgoral/hrm-solutions/blob/main/contributors.json"
click node_readme "https://github.com/atesgoral/hrm-solutions/blob/main/README.md"
click node_index_html "https://github.com/atesgoral/hrm-solutions/blob/main/index.html"
click node_gulpfile "https://github.com/atesgoral/hrm-solutions/blob/main/gulpfile.js"
click node_package_json "https://github.com/atesgoral/hrm-solutions/blob/main/package.json"
click node_test_workflow "https://github.com/atesgoral/hrm-solutions/blob/main/.github/workflows/test.yml"
click node_build_workflow "https://github.com/atesgoral/hrm-solutions/blob/main/.github/workflows/build-and-deploy.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_solutions_root,node_level_puzzles,node_asm_variants,node_strategy_tags toneBlue
class node_contributors_json,node_readme toneAmber
class node_test_workflow,node_hrm_parser,node_hrm_cpu,node_level_data,node_io_generators,node_static_analysis,node_benchmarking toneMint
class node_index_html,node_gulpfile,node_package_json,node_build_workflow,node_site_publish toneRose
```

## Components

### Solution Archive

Curated Human Resource Machine level folders and assembly submissions.

- [Solutions](https://github.com/atesgoral/hrm-solutions/tree/main/solutions): solution corpus · Top-level archive of level folders and `.asm` submissions. · `solutions`
- [Level folders](https://github.com/atesgoral/hrm-solutions/tree/main/solutions): puzzle sets · Per-level directories grouping variants for each HRM puzzle. · `solutions`
- [ASM files](https://github.com/atesgoral/hrm-solutions/tree/main/solutions): hrm programs · Human Resource Machine assembly solutions and strategy variants. · `solutions`
- [Strategy tags](https://github.com/atesgoral/hrm-solutions/tree/main/solutions): filename metadata · Encoded labels such as specific, unroll, exploit, obsolete, and similar approaches. · `solutions`

### Metadata

Contributor attribution and repository-facing presentation data.

- [Contributors](https://github.com/atesgoral/hrm-solutions/blob/main/contributors.json): attribution data · Author metadata used to resolve names and present credits. · `contributors.json`
- [README](https://github.com/atesgoral/hrm-solutions/blob/main/README.md): project guide · Repository overview and link hub for browsing, testing, and deployment. · `README.md`

### Validation

Static analysis, runtime execution, and benchmarking of solutions.

- [Test CI](https://github.com/atesgoral/hrm-solutions/blob/main/.github/workflows/test.yml): github actions · Pull-request validation workflow. · `.github/workflows/test.yml`
- **Parser**: static analysis · Parses HRM assembly for structural checks.
- **CPU runner**: runtime analysis · Executes solutions to validate behavior and performance.
- **Level data**: puzzle constraints · Puzzle-specific constraints and expectations used by tests.
- **I/O generators**: benchmark data · Inbox and outbox generation for automated test cases.
- **Checks**: validation stage · Static validation of solution structure and legality.
- **Benchmarks**: validation stage · Runtime and performance measurement across solution variants.

### Build & Delivery

Static-site generation and GitHub Pages deployment.

- [Index page](https://github.com/atesgoral/hrm-solutions/blob/main/index.html): static site entry · Browser-facing landing page for the solution archive. · `index.html`
- [Gulp build](https://github.com/atesgoral/hrm-solutions/blob/main/gulpfile.js): build orchestration · Build pipeline for packaging the archive into a publishable static site. · `gulpfile.js`
- [Package config](https://github.com/atesgoral/hrm-solutions/blob/main/package.json): node workspace · Node/Yarn scripts and dependency boundary for build and test tooling. · `package.json`
- [Deploy CI](https://github.com/atesgoral/hrm-solutions/blob/main/.github/workflows/build-and-deploy.yml): github actions · Build-and-deploy workflow for GitHub Pages publishing. · `.github/workflows/build-and-deploy.yml`
- **Pages site**: published artifact · Static browsable site generated from the verified archive.

## Connections

- Solutions → Level folders: organizes · Archive is partitioned into per-level folders.
- Level folders → ASM files: contains · Each level directory stores multiple solution submissions.
- ASM files → Strategy tags: encoded by · Filenames capture size, speed, strategy, and author.
- Contributors → ASM files: attributes · Contributor metadata supports author presentation for solutions.
- README → Index page: points to · README directs users to the browsable site and scores.
- Package config → Gulp build: drives · Package scripts wire up build orchestration.
- Package config → Test CI: installs · CI uses the Node/Yarn dependency set.
- Package config → Deploy CI: installs · Deployment workflow relies on the same package boundary.
- Test CI → Checks: runs · PR validation invokes repository checks.
- Test CI → Benchmarks: runs · PR validation includes runtime and performance evaluation.
- Checks → Parser: uses · Structural validation is performed with the HRM parser.
- Checks → Level data: uses · Parsing checks are constrained by puzzle metadata.
- Benchmarks → CPU runner: uses · Solution execution is performed by the HRM CPU runner.
- Benchmarks → I/O generators: uses · Benchmarks consume generated inbox/outbox cases.
- Benchmarks → Level data: uses · Runtime checks are bounded by level-specific rules.
- Gulp build → Pages site: builds · Build step packages the archive into a browsable artifact.
- Index page → Pages site: served as · Landing page is part of the published site.
- Deploy CI → Pages site: deploys · GitHub Actions publishes the static site to Pages.
- Pages site → Solutions: indexes · Published site presents the validated solution corpus.
- Pages site → Contributors: displays · Published views can surface author attribution.