# ioncodes/ayyboy architecture

> Architecture diagram of the GitHub repository ioncodes/ayyboy, 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/ioncodes/ayyboy
- Repository: https://github.com/ioncodes/ayyboy

## Overview

##### Project Type and Purpose
- Its main focus is on hardware emulation (CPU, memory, graphics, sound) and providing a frontend for debugging.

##### File Structure
- Top-level directories and files like Cargo.toml, src, and Dockerfile suggest that this is a Rust project with conventional Rust project structure.
- The src directory organizes the core modules:
- CPU and instruction handling under “src/lr35902” (with cpu.rs, registers.rs, etc.)
- Memory handling including mappers is found in “src/memory” (with submodules for different MBC types).
- Video emulation is in “src/video” (with modules for PPU, sprites, etc.)
- Sound processing is handled in “src/sound” (channels, APU, stereo, etc.)
- The frontend for debugging and rendering is housed in “src/frontend.”
- The external folder holds documents, test ROMs, and auxiliary scripts for comparing emulator traces, which support testing and validation.

##### Main Components of the System
a. Emulator Core
- CPU Emulation Module
- Contains core execution logic (found in src/lr35902) for the LR35902 (the GameBoy CPU) and possibly SM83 (for debugging or additional tests).
- Handles instruction decoding, execution pipelines, register operations, IRQ (interrupts), and timers.
- Memory Subsystem
- Includes memory mapping and the various memory mappers (MBC1, MBC3, MBC5) under src/memory.
- Manages ROM loading, save game persistence (RAM-based save files), and addressable memory.
- Graphics (PPU) Module
- Resides in src/video (modules: ppu, tile, sprite, palette, cram, state, and oam).
- Implements a scanline-based renderer without the pixel FIFO, as noted in the README.
- Sound (APU) Module
- Located under src/sound with different channel implementations (square, noise, wave) and stereo mixing.
- Additional emulation parts:
- Joypad handling (src/joypad).
- Possibly miscellaneous support like error handling (src/error.rs) and CPU testing (src/tests.rs).
b. Frontend and Debugging Interface
- Debugger and Renderer Components (within src/frontend) provide an UI for debugging the emulator state, visualizing frames, and configuring emulator settings.
c. Optional/Rumple Support
- Experimental integration (enabled via the “nsfw” feature flag) for Lovense devices to provide rumble feedback.

##### Relationships and Interactions Between Components
- The main emulator loop (entry point in src/main.rs) coordinates the interaction between CPU, memory, video, and sound.
- The CPU module fetches instructions from the memory subsystem and may trigger updates in the PPU (to update scanlines) and APU (for sound synthesis).
- The memory module interacts with the mapper modules to correctly load and handle ROM data.
- The frontend receives real-time data from the core (e.g., registers, video buffers, sound channels) for debugging and rendering.

##### Architectural Patterns or Design Principles
- Modular design with clearly separated concerns: CPU, Memory, Video, and Sound are in separate modules.
- Use of Rust’s module system supports encapsulation, and the project’s file structure signals an emphasis on clean separation between emulation core and debugging/visualization (frontend).
- The use of Cargo for dependency and build management shows adherence to Rust’s ecosystem practices.
- There’s a mix between synchronous operations (main emulation loop) and optional asynchronous or event-driven handling (e.g., for Lovense device scanning, if activated).

##### Elements
- “CPU Emulation (lr35902, sm83)”
- “Memory Subsystem and Mappers (MBC1, MBC3, MBC5)”
- “Graphics/PPU”
- “Sound/ APU and Channels (Square, Noise, Wave)”
- “Input (Joypad)”
- “Frontend/Debugger & Renderer”
- “External ROMs & BootROM Loader”
- Optional “Lovense BLE Interface for Rumble”
- Data/instruction flow from ROM to Memory to CPU.
- Control and synchronization signals between CPU, Timer/IRQ, PPU, and APU.
- Feedback loops from the Frontend to the core (e.g., for debugging or configuration changes).
- Optionally, annotate parts with key libraries or technologies:
- "Rust" as the primary language with Cargo management.
- Mention features like “nsfw” flag for conditional compilation of certain modules.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Emulator Core"
        ME["Main Emulator Loop"]:::core
        CPU["CPU Emulation (lr35902, sm83)"]:::core
        MEM["Memory Subsystem and Mappers"]:::core
        VID["Graphics (PPU) Module"]:::core
        SND["Sound (APU & Channels)"]:::core
        JOY["Input (Joypad)"]:::core
        LOV["Lovense BLE Interface (Experimental)"]:::optional
    end

    subgraph "Frontend"
        FE["Debugger & Renderer"]:::frontend
    end

    EXT["External Testing & Documentation"]:::external

    ME -->|"delegates"| CPU
    ME -->|"sends_debug_data"| FE
    FE -->|"issues_commands"| ME
    CPU -->|"fetches_instructions"| MEM
    CPU -->|"updates_graphics"| VID
    CPU -->|"triggers_sound"| SND
    CPU -->|"polls_input"| JOY
    CPU ---|"optional_rumble"| LOV
    EXT -->|"supplies_ROMs"| MEM

    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef optional fill:#f8d7da,stroke:#721c24,stroke-width:2px,stroke-dasharray: 5,5;
    classDef frontend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;

    click CPU "https://github.com/ioncodes/ayyboy/tree/master/src/lr35902"
    click MEM "https://github.com/ioncodes/ayyboy/tree/master/src/memory"
    click VID "https://github.com/ioncodes/ayyboy/tree/master/src/video"
    click SND "https://github.com/ioncodes/ayyboy/tree/master/src/sound"
    click FE "https://github.com/ioncodes/ayyboy/tree/master/src/frontend"
    click JOY "https://github.com/ioncodes/ayyboy/blob/master/src/joypad.rs"
    click EXT "https://github.com/ioncodes/ayyboy/tree/master/external"
```
