# smparsons/retroboy architecture

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

- Interactive diagram: https://gitdiagram.com/smparsons/retroboy
- Repository: https://github.com/smparsons/retroboy

## Overview

##### Main Components
- Emulator Core (Rust):
- Contains modules for CPU (with opcodes, ALU, bit operations, interrupts, timers, etc. in src/cpu).
- APU for sound synthesis and envelope management (found in src/apu).
- GPU for graphics and scanline rendering (found in src/gpu).
- MMU for memory management, cartridge emulation (src/mmu with bank switching, MBC support, etc.).
- Other components such as DMA, serial, RTC/cheats, and miscellaneous utilities.
- WASM Interface:
- Located in src/wasm; responsible for providing JavaScript bindings for the emulator core. This is built using wasm-pack via build-wasm.sh.
- Web Frontend:
- A React/TypeScript application (frontends/web) that loads the generated WASM module.
- Contains UI components (menus, game screens, modals, form elements) and hooks for managing audio, key listeners, responsiveness, and settings.
- Utilizes the Web Audio API, HTML Canvas for graphics rendering, and saves cartridge data to browser local storage.
- Test Runner:
- A JSON-based test runner (frontends/json_test_runner) provides a mechanism to run and verify CPU emulation using established JSON test suites.

##### Relationships and Data Flow
- The Web Frontend interacts with the WASM module:
- When a user loads a ROM or starts the emulator, the React app calls the WASM API functions, which in turn invoke the corresponding routines in the emulator core.
- Data flows from the emulator core (e.g., GPU scanline rendering, audio samples from APU) to the Web Frontend where it is rendered or played.
- The WASM layer serves as the bridge between JavaScript/TypeScript and the native Rust emulator core.
- The JSON test runner component interacts directly with the emulator core (or a simplified version thereof) to run automated tests for accuracy.
- Internally, modules in the Emulator Core communicate through function calls and shared memory access (e.g., the CPU’s instructions triggering GPU updates or memory transfers via DMA).

##### Architectural Patterns & Technologies
- Modularity and Separation of Concerns:
- Clear separation between emulation logic (Rust modules) and presentation (React frontend).
- The WASM layer encapsulates the native logic and exposes only necessary interfaces to the web.
- Layered Architecture:
- Divide the system into three layers: the core emulation backend (Rust code), the integration layer (WASM bindings), and the web presentation layer.
- Use of Test-Driven Development:
- A heavy emphasis on testing with dedicated JSON CPU tests and a comprehensive test suite (invoked via cargo test).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Emulator Core"
        CORE["Emulator Core"]:::core
        CPU["CPU Module"]:::emulator
        GPU["GPU Module"]:::emulator
        APU["APU Module"]:::emulator
        MMU["MMU Module"]:::emulator
    end

    subgraph "WASM Bindings"
        WASM["WASM Interface"]:::wasm
    end

    subgraph "Web Frontend"
        WEB["React/TypeScript App"]:::frontend
    end

    subgraph "Test Runner"
        TEST["JSON Test Runner"]:::test
    end

    %% Connections between layers
    WEB -->|"WASM_API"| WASM
    WASM -->|"Invokes"| CORE
    TEST -->|"Validates"| CORE

    %% Internal Emulator Core connections
    CORE -->|"Manages"| CPU
    CORE -->|"Manages"| GPU
    CORE -->|"Manages"| APU
    CORE -->|"Manages"| MMU

    CPU -->|"Triggers"| GPU
    CPU -->|"Triggers"| APU
    CPU -->|"Accesses"| MMU

    GPU -->|"VideoOutput"| WEB
    APU -->|"AudioOutput"| WEB

    %% Click Events
    click CORE "https://github.com/smparsons/retroboy/tree/main/src"
    click CPU "https://github.com/smparsons/retroboy/tree/main/src/cpu"
    click GPU "https://github.com/smparsons/retroboy/tree/main/src/gpu"
    click APU "https://github.com/smparsons/retroboy/tree/main/src/apu"
    click MMU "https://github.com/smparsons/retroboy/tree/main/src/mmu"
    click WASM "https://github.com/smparsons/retroboy/tree/main/src/wasm"
    click WEB "https://github.com/smparsons/retroboy/tree/main/frontends/web"
    click TEST "https://github.com/smparsons/retroboy/tree/main/frontends/json_test_runner"

    %% Styles
    classDef core fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef emulator fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef wasm fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef frontend fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef test fill:#DDA0DD,stroke:#333,stroke-width:2px;
```
