# ruby/irb architecture

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

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

## Overview

##### Project Type & Purpose
- The README clearly states that IRB is an interactive Ruby shell that lets developers test code snippets, debug using binding.irb, and explore Ruby’s behavior interactively.
- The project is structured as a Ruby gem and includes comprehensive testing, documentation, and extension capabilities.

##### File Structure
- Top-Level Organization:
- Directories such as .github (for CI/CD workflows), doc (documentation reference), and test (unit and integration tests) indicate practices for continuous integration and robust documentation.
- The bin and exe directories provide executables for starting an IRB session.
- The Core Library:
- The “lib” directory contains the heart of IRB’s functionality. Within this, the “lib/irb” subfolder contains many command-related files (e.g., cd, copy, debug, help, etc.), which together implement the command parser and execution flows of the REPL.
- Other parts of the lib directory include important modules such as “irb/context.rb”, “irb/debug.rb”, “irb/history.rb”, and “irb/workspace.rb” that manage session state, history, and evaluation contexts.
- Extensions and Helpers:
- The “lib/irb/ext” and “lib/irb/helper_method” folders indicate extension points to enhance IRB’s capabilities.
- Testing and Documentation:
- The “test” folder covers a suite of tests across commands, completion, context, debugger integration, etc., ensuring that each part of the REPL behaves as expected.
- Documentation in the “doc” folder provides manuals and usage guides.

a. Main Components to Represent:
- IRB Shell Executor: Representing the entry point (the executables in the bin and exe folders) which start the interactive session.
- Core REPL Engine:
ˇ Contains session and context management (e.g., irb/context.rb, irb/workspace.rb).
ˇ Command Parsing & Execution: Show all the different command modules (cd, copy, debug, exit, help, etc.) as a collective component.
- Extensions & Customization Layer:
ˇ Illustrate extension hooks (lib/irb/ext and lib/irb/helper_method) that allow users or libraries to enhance functionality.
- Auxiliary Components:
ˇ Debug Integration: Components that integrate with the Ruby debugger (as mentioned in the README and seen in modules like lib/irb/debug).
ˇ Integration with Debug.gem: Represent how binding.irb triggers a debugging session within the current context.
- Testing and CI Infrastructure:

b. Relationships and Interactions:

c. Architectural Patterns:
- Separation of Concerns: Show how the project is broken down into distinct layers – the input/command layer, evaluation/context management, and extension points.
- Modularity and Extensibility: Emphasize that each command exists in its own module/file and can be independently maintained or extended.
- Test-driven Development: Include a note indicating the extensive test suite ensures reliability of each component.

d. Relevant Technologies & Frameworks:
- Ruby Gem Specification: Represent that this is provided as a gem (highlight Gemfile, irb.gemspec).
- CI/CD Workflows: Show that automated tests and releases are managed using GitHub Actions (from the .github/workflows and release files).
- Documentation Tools: References to RDoc / RubyDoc tools (README and doc folder).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% IRB Shell Executor
    subgraph "IRB Shell Executor"
        A1["exe/irb"]:::executable
        A2["bin/console"]:::executable
    end

    %% Core REPL Engine
    subgraph "Core REPL Engine"
        subgraph "Session & Context Management"
            B1["Context Manager"]:::core
            B2["Workspace Manager"]:::core
        end
        subgraph "Command Handling"
            C1["Command Modules"]:::core
            C2["Default Commands"]:::core
        end
    end

    %% Input & Evaluation Engine
    subgraph "Input & Evaluation Engine"
        I1["Input Method"]:::eval
        I2["Ruby Lexer"]:::eval
    end

    %% Debug Integration
    subgraph "Debug Integration"
        D1["Debug Core"]:::debug
        D2["Command Debugger"]:::debug
        D3["Debug UI"]:::debug
    end

    %% Extensions & Customization
    subgraph "Extensions & Customization"
        E1["Extensions"]:::extension
        E2["Helper Methods"]:::extension
    end

    %% Testing & CI Infrastructure
    subgraph "Testing & CI Infrastructure"
        F1["Test Suite"]:::testing
        F2["CI/CD Workflows"]:::testing
    end

    %% Connections from IRB Shell Executor to Core REPL Engine
    A1 -->|"starts"| B1
    A1 -->|"starts"| C1
    A2 -->|"starts"| B1
    A2 -->|"starts"| C1

    %% Connections from Core REPL Engine to Input & Evaluation Engine
    B1 -->|"initializes"| I1
    B2 -->|"supports"| I1
    C1 -->|"processes commands"| I1
    C2 -->|"provides defaults"| I1
    I2 --- I1

    %% Connection from Input & Evaluation Engine to Debug Integration
    I1 -->|"triggers"| D1
    I1 -->|"triggers"| D2
    D1 -->|"manages"| D3

    %% Extension hooks from Command Handling to Extensions & Customization
    C1 ---|"extendable"| E1
    C2 ---|"extendable"| E1
    E1 -->|"uses"| E2

    %% Testing and CI monitoring connections (dotted lines)
    I1 ---|"validated_by"| F1
    E1 ---|"validated_by"| F1
    D1 ---|"validated_by"| F1
    F1 -->|"integrated with"| F2

    %% Styles
    classDef executable fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef eval fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef debug fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef extension fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef testing fill:#e2e3e5,stroke:#333,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/ruby/irb/tree/master/exe/irb"
    click A2 "https://github.com/ruby/irb/tree/master/bin/console"
    click B1 "https://github.com/ruby/irb/blob/master/lib/irb/context.rb"
    click B2 "https://github.com/ruby/irb/blob/master/lib/irb/workspace.rb"
    click C1 "https://github.com/ruby/irb/tree/master/lib/irb/command"
    click C2 "https://github.com/ruby/irb/blob/master/lib/irb/default_commands.rb"
    click I1 "https://github.com/ruby/irb/blob/master/lib/irb/input-method.rb"
    click I2 "https://github.com/ruby/irb/blob/master/lib/irb/ruby-lex.rb"
    click D1 "https://github.com/ruby/irb/blob/master/lib/irb/debug.rb"
    click D2 "https://github.com/ruby/irb/blob/master/lib/irb/command/debug.rb"
    click D3 "https://github.com/ruby/irb/blob/master/lib/irb/debug/ui.rb"
    click E1 "https://github.com/ruby/irb/tree/master/lib/irb/ext"
    click E2 "https://github.com/ruby/irb/tree/master/lib/irb/helper_method"
    click F1 "https://github.com/ruby/irb/tree/master/test"
    click F2 "https://github.com/ruby/irb/blob/master/.github"
```
