# ruby/rubygems architecture

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

- Interactive diagram: https://gitdiagram.com/ruby/rubygems
- Repository: https://github.com/ruby/rubygems

## Overview

RubyGems provides the gem command and runtime framework for creating, publishing, installing, managing, and loading Ruby packages. Its principal user workflow is to request a gem operation, resolve and retrieve package metadata or archives, install locally, and load the gem in a Ruby program. Bundler, developed in the same repository, adds an application-focused workflow: describe dependencies, resolve compatible versions, install them, record exact versions, and run the application in that environment. The README documents these capabilities; the sampled source illustrates command dispatch, compact-index access, and Bundler’s version switching, but does not expose every integration between subsystems.

Main entry points: [`lib/bundler/cli.rb`](https://github.com/ruby/rubygems/blob/master/lib/bundler/cli.rb) (bundle CLI), [`lib/rubygems/command_manager.rb`](https://github.com/ruby/rubygems/blob/master/lib/rubygems/command_manager.rb) (Command Dispatch), [`lib/rubygems/commands/install_command.rb`](https://github.com/ruby/rubygems/blob/master/lib/rubygems/commands/install_command.rb) (Install Command), [`lib/bundler/definition.rb`](https://github.com/ruby/rubygems/blob/master/lib/bundler/definition.rb) (Dependency Definition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rg_commands["RubyGems Commands"]
  node_gem_cli["gem CLI<br/>[gem_runner.rb]"]
  node_command_manager["Command Dispatch<br/>[command_manager.rb]"]
  node_install_command["Install Command<br/>[install_command.rb]"]
  node_build_command["Build Gem<br/>[build_command.rb]"]
  node_publish_command["Publish Gem<br/>[push_command.rb]"]
end

subgraph group_rg_packages["Gem Package Lifecycle"]
  node_gem_package["Gem Package<br/>[package.rb]"]
  node_gem_resolver["Gem Resolver<br/>[resolver.rb]"]
  node_gem_installer["Gem Installer<br/>[installer.rb]"]
  node_remote_fetcher["Remote Fetcher<br/>[remote_fetcher.rb]"]
  node_compact_index["Compact Index"]
  node_installed_gems[("Installed Gems<br/>[specification.rb]")]
end

subgraph group_bundler["Bundler Management"]
  node_bundle_cli["bundle CLI<br/>[cli.rb]"]
  node_gemfile_dsl["Gemfile DSL<br/>[dsl.rb]"]
  node_definition["Dependency Definition<br/>[definition.rb]"]
  node_bundle_resolver["Dependency Resolver<br/>[resolver.rb]"]
  node_bundle_fetcher["Bundle Fetcher<br/>[fetcher.rb]"]
  node_bundle_installer["Bundle Installer<br/>[installer.rb]"]
  node_lockfile["Lockfile"]
end

subgraph group_runtime["Ruby Runtime"]
  node_bundle_runtime["Bundle Runtime<br/>[runtime.rb]"]
  node_bundler_setup["Bundler Setup<br/>[setup.rb]"]
  node_self_manager["Bundler Version Switch<br/>[self_manager.rb]"]
end

node_developer(("Developer"))
node_ruby_program(("Ruby Program"))
node_gem_host(("RubyGems.org"))

node_developer -->|"runs command"| node_gem_cli
node_gem_cli -->|"dispatches"| node_command_manager
node_command_manager -->|"invokes"| node_install_command
node_command_manager -->|"invokes"| node_build_command
node_command_manager -->|"invokes"| node_publish_command
node_build_command -->|"builds package"| node_gem_package
node_publish_command -->|"publishes package"| node_gem_host
node_install_command -->|"resolves dependencies"| node_gem_resolver
node_install_command -->|"retrieves gems"| node_remote_fetcher
node_remote_fetcher -->|"requests metadata"| node_gem_host
node_compact_index -->|"fetches index"| node_gem_host
node_install_command -->|"installs gems"| node_gem_installer
node_gem_installer -->|"writes installed specs"| node_installed_gems
node_developer -->|"runs bundle command"| node_bundle_cli
node_bundle_cli -->|"evaluates dependencies"| node_gemfile_dsl
node_bundle_cli -->|"loads definition"| node_definition
node_definition -->|"resolves versions"| node_bundle_resolver
node_definition -->|"retrieves sources"| node_bundle_fetcher
node_bundle_fetcher -->|"fetches gems"| node_gem_host
node_bundle_cli -->|"installs bundle"| node_bundle_installer
node_bundle_installer -->|"records versions"| node_lockfile
node_ruby_program -->|"loads environment"| node_bundler_setup
node_bundler_setup -->|"activates bundle"| node_bundle_runtime
node_bundle_cli -->|"switches version"| node_self_manager
node_bundle_runtime -->|"uses installed gems"| node_installed_gems

click node_gem_cli "https://github.com/ruby/rubygems/blob/master/lib/rubygems/gem_runner.rb"
click node_command_manager "https://github.com/ruby/rubygems/blob/master/lib/rubygems/command_manager.rb"
click node_install_command "https://github.com/ruby/rubygems/blob/master/lib/rubygems/commands/install_command.rb"
click node_build_command "https://github.com/ruby/rubygems/blob/master/lib/rubygems/commands/build_command.rb"
click node_publish_command "https://github.com/ruby/rubygems/blob/master/lib/rubygems/commands/push_command.rb"
click node_gem_package "https://github.com/ruby/rubygems/blob/master/lib/rubygems/package.rb"
click node_gem_resolver "https://github.com/ruby/rubygems/blob/master/lib/rubygems/resolver.rb"
click node_gem_installer "https://github.com/ruby/rubygems/blob/master/lib/rubygems/installer.rb"
click node_remote_fetcher "https://github.com/ruby/rubygems/blob/master/lib/rubygems/remote_fetcher.rb"
click node_compact_index "https://github.com/ruby/rubygems/blob/master/lib/rubygems/compact_index_client.rb"
click node_installed_gems "https://github.com/ruby/rubygems/blob/master/lib/rubygems/specification.rb"
click node_bundle_cli "https://github.com/ruby/rubygems/blob/master/lib/bundler/cli.rb"
click node_gemfile_dsl "https://github.com/ruby/rubygems/blob/master/lib/bundler/dsl.rb"
click node_definition "https://github.com/ruby/rubygems/blob/master/lib/bundler/definition.rb"
click node_bundle_resolver "https://github.com/ruby/rubygems/blob/master/lib/bundler/resolver.rb"
click node_bundle_fetcher "https://github.com/ruby/rubygems/blob/master/lib/bundler/fetcher.rb"
click node_bundle_installer "https://github.com/ruby/rubygems/blob/master/lib/bundler/installer.rb"
click node_lockfile "https://github.com/ruby/rubygems/blob/master/lib/bundler/lockfile_generator.rb"
click node_bundle_runtime "https://github.com/ruby/rubygems/blob/master/lib/bundler/runtime.rb"
click node_bundler_setup "https://github.com/ruby/rubygems/blob/master/lib/bundler/setup.rb"
click node_self_manager "https://github.com/ruby/rubygems/blob/master/lib/bundler/self_manager.rb"

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_gem_cli,node_command_manager,node_install_command,node_build_command,node_publish_command toneBlue
class node_gem_package,node_gem_resolver,node_gem_installer,node_remote_fetcher,node_compact_index,node_installed_gems toneAmber
class node_bundle_cli,node_gemfile_dsl,node_definition,node_bundle_resolver,node_bundle_fetcher,node_bundle_installer,node_lockfile toneMint
class node_bundle_runtime,node_bundler_setup,node_self_manager toneRose
class node_developer,node_ruby_program,node_gem_host toneIndigo
```

## Components

### RubyGems Commands

- [gem CLI](https://github.com/ruby/rubygems/blob/master/lib/rubygems/gem_runner.rb): `lib/rubygems/gem_runner.rb`
- [Command Dispatch](https://github.com/ruby/rubygems/blob/master/lib/rubygems/command_manager.rb): `lib/rubygems/command_manager.rb`
- [Install Command](https://github.com/ruby/rubygems/blob/master/lib/rubygems/commands/install_command.rb): `lib/rubygems/commands/install_command.rb`
- [Build Gem](https://github.com/ruby/rubygems/blob/master/lib/rubygems/commands/build_command.rb): `lib/rubygems/commands/build_command.rb`
- [Publish Gem](https://github.com/ruby/rubygems/blob/master/lib/rubygems/commands/push_command.rb): `lib/rubygems/commands/push_command.rb`

### Gem Package Lifecycle

- [Gem Package](https://github.com/ruby/rubygems/blob/master/lib/rubygems/package.rb): `lib/rubygems/package.rb`
- [Gem Resolver](https://github.com/ruby/rubygems/blob/master/lib/rubygems/resolver.rb): `lib/rubygems/resolver.rb`
- [Gem Installer](https://github.com/ruby/rubygems/blob/master/lib/rubygems/installer.rb): `lib/rubygems/installer.rb`
- [Remote Fetcher](https://github.com/ruby/rubygems/blob/master/lib/rubygems/remote_fetcher.rb): `lib/rubygems/remote_fetcher.rb`
- [Compact Index](https://github.com/ruby/rubygems/blob/master/lib/rubygems/compact_index_client.rb): `lib/rubygems/compact_index_client.rb`
- [Installed Gems](https://github.com/ruby/rubygems/blob/master/lib/rubygems/specification.rb): `lib/rubygems/specification.rb`

### Bundler Management

- [bundle CLI](https://github.com/ruby/rubygems/blob/master/lib/bundler/cli.rb): `lib/bundler/cli.rb`
- [Gemfile DSL](https://github.com/ruby/rubygems/blob/master/lib/bundler/dsl.rb): `lib/bundler/dsl.rb`
- [Dependency Definition](https://github.com/ruby/rubygems/blob/master/lib/bundler/definition.rb): `lib/bundler/definition.rb`
- [Dependency Resolver](https://github.com/ruby/rubygems/blob/master/lib/bundler/resolver.rb): `lib/bundler/resolver.rb`
- [Bundle Fetcher](https://github.com/ruby/rubygems/blob/master/lib/bundler/fetcher.rb): `lib/bundler/fetcher.rb`
- [Bundle Installer](https://github.com/ruby/rubygems/blob/master/lib/bundler/installer.rb): `lib/bundler/installer.rb`
- [Lockfile](https://github.com/ruby/rubygems/blob/master/lib/bundler/lockfile_generator.rb): `lib/bundler/lockfile_generator.rb`

### Ruby Runtime

- [Bundle Runtime](https://github.com/ruby/rubygems/blob/master/lib/bundler/runtime.rb): `lib/bundler/runtime.rb`
- [Bundler Setup](https://github.com/ruby/rubygems/blob/master/lib/bundler/setup.rb): `lib/bundler/setup.rb`
- [Bundler Version Switch](https://github.com/ruby/rubygems/blob/master/lib/bundler/self_manager.rb): `lib/bundler/self_manager.rb`

### Other components

- **Developer**
- **Ruby Program**
- **RubyGems.org**

## Connections

- Developer → gem CLI: runs command
- gem CLI → Command Dispatch: dispatches
- Command Dispatch → Install Command: invokes
- Command Dispatch → Build Gem: invokes
- Command Dispatch → Publish Gem: invokes
- Build Gem → Gem Package: builds package
- Publish Gem → RubyGems.org: publishes package
- Install Command → Gem Resolver: resolves dependencies
- Install Command → Remote Fetcher: retrieves gems
- Remote Fetcher → RubyGems.org: requests metadata
- Compact Index → RubyGems.org: fetches index
- Install Command → Gem Installer: installs gems
- Gem Installer → Installed Gems: writes installed specs
- Developer → bundle CLI: runs bundle command
- bundle CLI → Gemfile DSL: evaluates dependencies
- bundle CLI → Dependency Definition: loads definition
- Dependency Definition → Dependency Resolver: resolves versions
- Dependency Definition → Bundle Fetcher: retrieves sources
- Bundle Fetcher → RubyGems.org: fetches gems
- bundle CLI → Bundle Installer: installs bundle
- Bundle Installer → Lockfile: records versions
- Ruby Program → Bundler Setup: loads environment
- Bundler Setup → Bundle Runtime: activates bundle
- bundle CLI → Bundler Version Switch: switches version
- Bundle Runtime → Installed Gems: uses installed gems