# sacckey/rubyboy architecture

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

- Interactive diagram: https://gitdiagram.com/sacckey/rubyboy
- Repository: https://github.com/sacckey/rubyboy

## Overview

##### Main Components
- Emulator Core – This is the central engine that ties all subcomponents together (found in lib/rubyboy/emulator.rb, emulator_headless.rb, and emulator_wasm.rb).
- CPU & Registers – Represented by lib/rubyboy/cpu.rb and lib/rubyboy/registers.rb, this module emulates the processor’s behavior, fetching and executing instructions.
- Memory & Bus – The bus (lib/rubyboy/bus.rb) connects the CPU with RAM (lib/rubyboy/ram.rb), cartridge memory (lib/rubyboy/cartridge directory), and I/O components.
- Cartridge & ROM Management – With components under lib/rubyboy/cartridge and lib/roms, including a factory pattern (lib/rubyboy/cartridge/factory.rb) to load ROM files.
- Graphics (PPU & LCD) – Handled by lib/rubyboy/ppu.rb and lib/rubyboy/lcd.rb, possibly with additional abstraction for SDL (lib/rubyboy/sdl.rb) or via raylib (lib/rubyboy/raylib).
- Audio (APU & Channels) – Emulated by lib/rubyboy/apu.rb along with its channel submodules (e.g., channel1.rb – channel4.rb).
- Timer & Interrupts – Managed by lib/rubyboy/timer.rb and lib/rubyboy/interrupt.rb, ensuring correct timing of operations and event handling.
- Input Handling – Through lib/rubyboy/joypad.rb to map keyboard input (as described in the README) to emulator controls.

##### Diagramming the Relationships and Interactions
- The CPU, which in turn connects to the Bus.
- The Bus that facilitates communication with Memory (RAM) and Cartridge (ROM) components.
- The Timer/Interrupt system that interacts with the CPU to manage synchronization.
- Separate branches from the core indicate I/O:
- One branch leads to the Graphics subsystem (PPU, LCD) which may utilize external libraries (SDL2 and/or raylib).
- Another branch routes to the Audio subsystem (APU and associated channels).
- Input subsystem (Joypad) that feeds into the core for user commands.
- Cartridge & ROM loader as the entry point for loading game data. Show how the ROM is parsed and its data injected into the Memory subsystem via the Bus.

##### Architectural Patterns and Design Principles
- Modularity: Each hardware component (e.g., CPU, GPU, APU) is encapsulated in its own module, allowing easier maintenance and potential reuse.
- Clear Data/Control Flow: The CPU fetches instructions from memory (often involving Cartridge ROMe) and coordinates with peripherals (Graphics, Audio, Input).
- Use of Factory Pattern: For cartridge management (the Cartridge Factory module), indicating a layer of abstraction when loading different ROMs.
- Separation of Concerns especially shown by having distinct implementations for headless running, WebAssembly, and standard execution modes.

##### Final Recommendations
- Every component and interaction is clearly labeled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Emulation"
        EmulatorCore["Emulator Core"]:::core
        CPU["CPU & Registers"]:::processing
        MemoryBus["Memory & Bus"]:::processing
        Timer["Timer & Interrupt"]:::processing
        EmulatorCore -->|"executes"| CPU
        CPU -->|"fetches_from"| MemoryBus
        Timer -->|"signals"| CPU
    end

    subgraph "ROM Management"
        Cartridge["Cartridge & ROM"]:::storage
        Cartridge -->|"loads_into"| MemoryBus
    end

    subgraph "I/O Subsystems"
        Graphics["Graphics (PPU & LCD)"]:::io
        Audio["Audio (APU & Channels)"]:::io
        Input["Input (Joypad)"]:::io
        EmulatorCore -->|"renders_to"| Graphics
        EmulatorCore -->|"outputs_to"| Audio
        EmulatorCore -->|"receives"| Input
    end

    %% Click Events for Emulator Core
    click EmulatorCore "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/emulator.rb"
    click EmulatorCore "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/emulator_headless.rb"
    click EmulatorCore "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/emulator_wasm.rb"

    %% Click Events for CPU & Registers
    click CPU "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/cpu.rb"
    click CPU "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/registers.rb"

    %% Click Events for Memory & Bus
    click MemoryBus "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/bus.rb"
    click MemoryBus "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/ram.rb"

    %% Click Events for Cartridge & ROM Management
    click Cartridge "https://github.com/sacckey/rubyboy/tree/main/lib/rubyboy/cartridge"
    click Cartridge "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/cartridge/factory.rb"
    click Cartridge "https://github.com/sacckey/rubyboy/tree/main/lib/roms"

    %% Click Events for Graphics (PPU & LCD)
    click Graphics "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/ppu.rb"
    click Graphics "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/lcd.rb"
    click Graphics "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/sdl.rb"
    click Graphics "https://github.com/sacckey/rubyboy/tree/main/lib/rubyboy/raylib"

    %% Click Events for Audio (APU & Channels)
    click Audio "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/apu.rb"
    click Audio "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/apu_channels/channel1.rb"
    click Audio "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/apu_channels/channel2.rb"
    click Audio "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/apu_channels/channel3.rb"
    click Audio "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/apu_channels/channel4.rb"

    %% Click Events for Timer & Interrupts
    click Timer "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/timer.rb"
    click Timer "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/interrupt.rb"

    %% Click Event for Input Handling (Joypad)
    click Input "https://github.com/sacckey/rubyboy/blob/main/lib/rubyboy/joypad.rb"

    %% Styles
    classDef core fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef processing fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef storage fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef io fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
```
