# sciruby/iruby architecture

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

- Interactive diagram: https://gitdiagram.com/sciruby/iruby
- Repository: https://github.com/sciruby/iruby

## Overview

Below are detailed steps and guidelines tailored to IRuby’s structure:

##### Main Components
- Jupyter Frontend: This is the external environment where users interact with notebooks. (This isn’t part of IRuby’s source, but it’s a critical external actor.)
- Application Layer (lib/iruby/application.rb): This likely handles the high-level application logic and the lifecycle of the IRuby kernel.
- Core Kernel and Session Management: For example, lib/iruby/kernel.rb and lib/iruby/session.rb along with the session adapters (ffirzmq, cztop, etc.) represent the messaging and session logic to connect to Jupyter.
- Backend Processing: The “backend” for Ruby code execution, where you see files like lib/iruby/backend.rb and the differentiation between PlainBackend and PryBackend.
- Communication (Comm): The module in lib/iruby/comm.rb is responsible for the interactive messaging system that communicates with Jupyter’s front-end.
- Input Widgets: The lib/iruby/input directory (and its various widget components) represents the abstraction for handling user inputs coming from notebook widgets.
- Asset Management: The assets directory under lib/iruby/assets (containing CSS and JS files) serves to customize or support the Jupyter interface.
- Utilities and Error Handling: Modules like logger, formatter, display, and error handling code provide support functions that glue the system together.

##### Relationships and Interactions
- The “Application & Core” block (including Application, Kernel, and Logger).
- The “Session & Communication” block (including Session, Session Adapter layers, and Comm) that interacts with ZeroMQ (via ffi-rzmq or cztop as indicated by their directories and the README).
- The “Backend” block showing the exchange between Ruby’s native IRB (or Pry) and the kernel code.
- The “Input Widget” block (all components in lib/iruby/input) responsible for managing interactive UI elements.
- The “Assets” block (CSS/JS) that supports any web-based interface customizations.
- Incoming code or widget actions pass into the communication (Comm) and session modules.
- The kernel then delegates code execution onto the selected backend (PlainBackend with IRB, or PryBackend if switched).
- Results are then formatted (using Formatter or Display) and sent back to the front-end.

##### Architectural Patterns
- Layered Communication: With session adapters (ffirzmq, cztop) abstracting the underlying ZeroMQ communication, represent an abstraction layer between IRuby’s core and the external messaging system.

##### Relevant Technologies and Dependencies
- External dependencies such as ZeroMQ (libzmq, ffi-rzmq, and optionally cztop) used by session adapters.
- Mention that Jupyter (not part of the repository but fundamental to IRuby’s functionality) is the primary frontend.
- That IRuby leverages Ruby’s runtime (IRB or Pry) for executing code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actor
    JF["Jupyter Frontend"]:::external

    %% IRuby Kernel Container
    subgraph "IRuby Kernel"
        %% Application & Core Block
        subgraph "Application & Core"
            A1["Application Layer"]:::kernel
            K["Core Kernel"]:::kernel
            %% Utilities and Error Handling
            subgraph "Utilities & Error Handling"
                L["Logger"]:::utils
                F["Formatter"]:::utils
                D["Display"]:::utils
                E["Error Handling"]:::utils
            end
        end

        %% Session & Communication Block
        subgraph "Session & Communication"
            S1["Session Management File"]:::communication
            S2["Session Management Directory"]:::communication
            SA["Session Adapters"]:::communication
            C["Communication Module"]:::communication
        end

        %% Backend Block
        subgraph "Backend"
            B["Backend Processing"]:::backend
        end

        %% Input Widgets Block
        subgraph "Input Widgets"
            IW["Input Widgets"]:::widgets
        end

        %% Assets Block
        subgraph "Assets"
            A["Assets (CSS/JS)"]:::assets
        end
    end

    %% Connections (Vertical Flow)
    JF --->|"sends_messages"| C
    C --->|"init_session"| S1
    S1 -->|"uses"| S2
    C --->|"delegates_code"| B
    B --->|"returns_result"| A1
    A1 --->|"formats_reply"| C
    C --->|"sends_response"| JF

    %% Additional Connection: Session Adapters used by Session management
    S1 ---|"adapter_interface"| SA

    %% Click Events
    click A1 "https://github.com/sciruby/iruby/blob/master/lib/iruby/application.rb"
    click K "https://github.com/sciruby/iruby/blob/master/lib/iruby/kernel.rb"
    click S1 "https://github.com/sciruby/iruby/blob/master/lib/iruby/session.rb"
    click S2 "https://github.com/sciruby/iruby/tree/master/lib/iruby/session"
    click SA "https://github.com/sciruby/iruby/tree/master/lib/iruby/session_adapter/"
    click B "https://github.com/sciruby/iruby/blob/master/lib/iruby/backend.rb"
    click C "https://github.com/sciruby/iruby/blob/master/lib/iruby/comm.rb"
    click IW "https://github.com/sciruby/iruby/tree/master/lib/iruby/input"
    click A "https://github.com/sciruby/iruby/tree/master/lib/iruby/assets"
    click L "https://github.com/sciruby/iruby/blob/master/lib/iruby/logger.rb"
    click F "https://github.com/sciruby/iruby/blob/master/lib/iruby/formatter.rb"
    click D "https://github.com/sciruby/iruby/blob/master/lib/iruby/display.rb"
    click E "https://github.com/sciruby/iruby/blob/master/lib/iruby/error.rb"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px,color:#000;
    classDef kernel fill:#C0FFC0,stroke:#333,stroke-width:1px,color:#000;
    classDef communication fill:#FFFACD,stroke:#333,stroke-width:1px,color:#000;
    classDef backend fill:#FFD700,stroke:#333,stroke-width:1px,color:#000;
    classDef utils fill:#FFB6C1,stroke:#333,stroke-width:1px,color:#000;
    classDef widgets fill:#E6E6FA,stroke:#333,stroke-width:1px,color:#000;
    classDef assets fill:#F0E68C,stroke:#333,stroke-width:1px,color:#000;
```
