# trinistr/gem-template architecture

> Architecture diagram of the GitHub repository trinistr/gem-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trinistr/gem-template
- Repository: https://github.com/trinistr/gem-template

## Overview

#### Purpose and Scope
This repository is a reusable Ruby gem repository template, not a domain-specific implemented gem. It supplies the conventional packaging, test, typing, documentation, release, and CI structure intended to be renamed and extended by consumers.

#### Library Entry Points
RubyGems loads `lib/gem_template.rb`, which defines the top-level `GemTemplate` namespace. Version identity is isolated in `lib/gem_template/version.rb`, allowing gem packaging and runtime code to reference a single version source.

Paths:
- `lib/gem_template.rb`
- `lib/gem_template/version.rb`
- `gem_template.gemspec`

#### Packaging and Release Boundary
`gem_template.gemspec` is the package contract: a derived project must populate its metadata, dependencies, files, and publication details. The `Rakefile` is the operational entry point for local validation, installation, version bumps, documentation generation, and release. Release ultimately targets RubyGems.org.

Paths:
- `gem_template.gemspec`
- `Rakefile`
- `CHANGELOG.md`

#### Quality and Type-Checking Pipeline
The development control flow is task-driven: `rake` aggregates specs, RuboCop, and RBS validation; optional Steep checking provides stronger static type analysis. Runtime behavior is tested through RSpec, with shared test setup and coverage instrumentation separated from library code. Public type shape is declared in RBS and resolved dependencies are governed by RBS Collection.

Paths:
- `spec/gem_template_spec.rb`
- `sig/gem_template.rbs`
- `rbs_collection.yaml`

#### Developer Runtime Interfaces
Bundler provides dependency installation and command execution from the root `Gemfile`. `bin/console` is an interactive runtime shell for loading and experimenting with the gem; `bin/benchmark` is a performance-analysis entry point that produces StackProf profiling output.

Paths:
- `Gemfile`
- `bin/console`
- `bin/benchmark`

#### CI, Compatibility, and Documentation
GitHub Actions is the execution infrastructure. The primary CI workflow validates the repository, while dedicated workflows exercise CRuby, JRuby, and TruffleRuby compatibility. Documentation is generated from YARD annotations and deployed to GitHub Pages; released gem documentation is expected to be served externally by RubyDoc.

Paths:
- `.github/workflows/CI.yaml`
- `.github/workflows/cruby.yaml`
- `.github/workflows/deploy-docs.yaml`

#### Repository Governance and Security
Template consumers can import GitHub rulesets for default-branch, commit, and tag protection. Zizmor is retained as a GitHub Actions security-analysis boundary to detect unsafe workflow patterns.

Paths:
- `.github/Default branch protection.json`
- `.github/Tag protection.json`
- `.github/workflows/zizmor.yaml`

Main entry points: [`Rakefile`](https://github.com/trinistr/gem-template/blob/main/Rakefile) (Rake tasks), [`Gemfile`](https://github.com/trinistr/gem-template/blob/main/Gemfile) (Bundler dependencies), [`gem_template.gemspec`](https://github.com/trinistr/gem-template/blob/main/gem_template.gemspec) (Gem specification), [`.github/workflows/CI.yaml`](https://github.com/trinistr/gem-template/blob/main/.github/workflows/CI.yaml) (Primary CI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Library package"]
  node_entry["GemTemplate entry<br/>Ruby entry point<br/>[gem_template.rb]"]
  node_version["Version source<br/>Ruby version<br/>[version.rb]"]
  node_gemspec["Gem specification<br/>package contract"]
  node_rubygems[("RubyGems.org<br/>package registry")]
end

subgraph group_development["Developer tooling"]
  node_rake{{"Rake tasks<br/>task runner"}}
  node_gemfile["Bundler dependencies<br/>dependency manifest"]
  node_console["Interactive console<br/>developer shell"]
  node_benchmark["Benchmark runner<br/>profiling entry point"]
  node_changelog["Changelog<br/>release history<br/>[CHANGELOG.md]"]
end

subgraph group_quality["Quality and types"]
  node_specs["RSpec suite<br/>runtime tests"]
  node_rbs["Public RBS signatures<br/>type declarations<br/>[gem_template.rbs]"]
  node_rbs_collection["RBS Collection<br/>type dependency lock"]
end

subgraph group_automation["CI and documentation"]
  node_ci{{"Primary CI<br/>GitHub Actions workflow<br/>[CI.yaml]"}}
  node_cruby{{"CRuby compatibility<br/>GitHub Actions workflow<br/>[cruby.yaml]"}}
  node_docs{{"Documentation deployment<br/>GitHub Actions workflow<br/>[deploy-docs.yaml]"}}
  node_github_pages[("GitHub Pages<br/>documentation host")]
end

subgraph group_governance["Governance and security"]
  node_branch_rules["Branch protection<br/>GitHub ruleset import"]
  node_tag_rules["Tag protection<br/>GitHub ruleset import"]
  node_zizmor{{"Workflow security scan<br/>GitHub Actions workflow<br/>[zizmor.yaml]"}}
end

node_gemspec -->|"packages"| node_entry
node_gemspec -->|"uses version"| node_version
node_rake -->|"builds and releases"| node_gemspec
node_rake -->|"runs"| node_specs
node_rake -->|"validates"| node_rbs
node_rbs_collection -->|"resolves external types"| node_rbs
node_gemfile -->|"provides tool dependencies"| node_rake
node_gemfile -->|"executes under Bundler"| node_console
node_gemfile -->|"executes under Bundler"| node_benchmark
node_console -->|"loads"| node_entry
node_benchmark -->|"profiles"| node_entry
node_rake -.->|"updates for releases"| node_changelog
node_rake -->|"publishes package"| node_rubygems
node_ci -->|"runs validation tasks"| node_rake
node_cruby -->|"runs on CRuby"| node_specs
node_docs -->|"deploys generated docs"| node_github_pages
node_zizmor -.->|"scans workflow patterns"| node_ci
node_branch_rules -.->|"protects change integration"| node_ci
node_tag_rules -.->|"protects release tags"| node_rake

click node_entry "https://github.com/trinistr/gem-template/blob/main/lib/gem_template.rb"
click node_version "https://github.com/trinistr/gem-template/blob/main/lib/gem_template/version.rb"
click node_gemspec "https://github.com/trinistr/gem-template/blob/main/gem_template.gemspec"
click node_rake "https://github.com/trinistr/gem-template/blob/main/Rakefile"
click node_gemfile "https://github.com/trinistr/gem-template/blob/main/Gemfile"
click node_console "https://github.com/trinistr/gem-template/blob/main/bin/console"
click node_benchmark "https://github.com/trinistr/gem-template/blob/main/bin/benchmark"
click node_specs "https://github.com/trinistr/gem-template/blob/main/spec/gem_template_spec.rb"
click node_rbs "https://github.com/trinistr/gem-template/blob/main/sig/gem_template.rbs"
click node_rbs_collection "https://github.com/trinistr/gem-template/blob/main/rbs_collection.yaml"
click node_ci "https://github.com/trinistr/gem-template/blob/main/.github/workflows/CI.yaml"
click node_cruby "https://github.com/trinistr/gem-template/blob/main/.github/workflows/cruby.yaml"
click node_docs "https://github.com/trinistr/gem-template/blob/main/.github/workflows/deploy-docs.yaml"
click node_branch_rules "https://github.com/trinistr/gem-template/blob/main/.github/Default%20branch%20protection.json"
click node_tag_rules "https://github.com/trinistr/gem-template/blob/main/.github/Tag%20protection.json"
click node_zizmor "https://github.com/trinistr/gem-template/blob/main/.github/workflows/zizmor.yaml"
click node_changelog "https://github.com/trinistr/gem-template/blob/main/CHANGELOG.md"

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_entry,node_version,node_gemspec,node_rubygems toneBlue
class node_rake,node_gemfile,node_console,node_benchmark,node_changelog toneAmber
class node_specs,node_rbs,node_rbs_collection toneMint
class node_ci,node_cruby,node_docs,node_github_pages toneRose
class node_branch_rules,node_tag_rules,node_zizmor toneIndigo
```

## Components

### Library package

- [GemTemplate entry](https://github.com/trinistr/gem-template/blob/main/lib/gem_template.rb): Ruby entry point · Defines the top-level namespace. · `lib/gem_template.rb`
- [Version source](https://github.com/trinistr/gem-template/blob/main/lib/gem_template/version.rb): Ruby version · Central package version identity. · `lib/gem_template/version.rb`
- [Gem specification](https://github.com/trinistr/gem-template/blob/main/gem_template.gemspec): package contract · Defines metadata, dependencies, contents, and publication settings. · `gem_template.gemspec`
- **RubyGems.org**: package registry

### Developer tooling

- [Rake tasks](https://github.com/trinistr/gem-template/blob/main/Rakefile): task runner · Runs validation, installation, versioning, docs, and release operations. · `Rakefile`
- [Bundler dependencies](https://github.com/trinistr/gem-template/blob/main/Gemfile): dependency manifest · `Gemfile`
- [Interactive console](https://github.com/trinistr/gem-template/blob/main/bin/console): developer shell · `bin/console`
- [Benchmark runner](https://github.com/trinistr/gem-template/blob/main/bin/benchmark): profiling entry point · Produces StackProf profiling output. · `bin/benchmark`
- [Changelog](https://github.com/trinistr/gem-template/blob/main/CHANGELOG.md): release history · `CHANGELOG.md`

### Quality and types

- [RSpec suite](https://github.com/trinistr/gem-template/blob/main/spec/gem_template_spec.rb): runtime tests · `spec/gem_template_spec.rb`
- [Public RBS signatures](https://github.com/trinistr/gem-template/blob/main/sig/gem_template.rbs): type declarations · `sig/gem_template.rbs`
- [RBS Collection](https://github.com/trinistr/gem-template/blob/main/rbs_collection.yaml): type dependency lock · `rbs_collection.yaml`

### CI and documentation

- [Primary CI](https://github.com/trinistr/gem-template/blob/main/.github/workflows/CI.yaml): GitHub Actions workflow · Validates the repository. · `.github/workflows/CI.yaml`
- [CRuby compatibility](https://github.com/trinistr/gem-template/blob/main/.github/workflows/cruby.yaml): GitHub Actions workflow · `.github/workflows/cruby.yaml`
- [Documentation deployment](https://github.com/trinistr/gem-template/blob/main/.github/workflows/deploy-docs.yaml): GitHub Actions workflow · Generates YARD documentation and deploys it to GitHub Pages. · `.github/workflows/deploy-docs.yaml`
- **GitHub Pages**: documentation host

### Governance and security

- [Branch protection](https://github.com/trinistr/gem-template/blob/main/.github/Default%20branch%20protection.json): GitHub ruleset import · `.github/Default branch protection.json`
- [Tag protection](https://github.com/trinistr/gem-template/blob/main/.github/Tag%20protection.json): GitHub ruleset import · `.github/Tag protection.json`
- [Workflow security scan](https://github.com/trinistr/gem-template/blob/main/.github/workflows/zizmor.yaml): GitHub Actions workflow · Detects unsafe GitHub Actions patterns. · `.github/workflows/zizmor.yaml`

## Connections

- Gem specification → GemTemplate entry: packages
- Gem specification → Version source: uses version
- Rake tasks → Gem specification: builds and releases
- Rake tasks → RSpec suite: runs
- Rake tasks → Public RBS signatures: validates
- RBS Collection → Public RBS signatures: resolves external types
- Bundler dependencies → Rake tasks: provides tool dependencies
- Bundler dependencies → Interactive console: executes under Bundler
- Bundler dependencies → Benchmark runner: executes under Bundler
- Interactive console → GemTemplate entry: loads
- Benchmark runner → GemTemplate entry: profiles
- Rake tasks → Changelog: updates for releases
- Rake tasks → RubyGems.org: publishes package
- Primary CI → Rake tasks: runs validation tasks
- CRuby compatibility → RSpec suite: runs on CRuby
- Documentation deployment → GitHub Pages: deploys generated docs
- Workflow security scan → Primary CI: scans workflow patterns
- Branch protection → Primary CI: protects change integration
- Tag protection → Rake tasks: protects release tags