# vedant416/rustynes architecture

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

- Interactive diagram: https://gitdiagram.com/vedant416/rustynes
- Repository: https://github.com/vedant416/rustynes

## Overview

##### Project Type & Purpose
- RustyNES is a cross‐platform NES emulator written in Rust.
- It provides a “core” emulation engine (`RustyNES_core`) plus three front-ends/adapters:
- A native CLI using SDL2 (`RustyNES_cli`)
- A WASM port library (`RustyNES_wasm`)
- A browser-based UI around the WASM port (`RustyNES_web_ui`)

##### File Structure
- Top-level crates:
- RustyNES_core: engine modules (CPU, PPU, APU, Mappers, Bus, Controller, ROM, Save/Load)
- RustyNES_cli: `main.rs` + `build.rs`, SDL2 binaries/libs, command‐line interface, file I/O
- RustyNES_wasm: `lib.rs` producing WebAssembly + JS glue (`foo.js`)
- RustyNES_web_ui: HTML/CSS/TS, NPM, `vite` dev server, bundling the WASM module
- External dependencies: SDL2 (native), wasm-pack / npm (web).

##### Extract Architectural Insights from the README
- Core is pure Rust with zero external deps.
- CLI uses SDL2 for graphics/audio/input.
- WASM crate compiles core for the browser.
- Web UI loads the `.wasm` bundle, JS bindings, and presents an HTML5 UI.

##### Main Components & How They Interact
a. RustyNES_core (Engine layer)
- Subcomponents: CPU (6502 instructions), PPU (render pipeline), APU (sound channels), Memory Bus, Mappers, Controller Input, ROM loading, Save/Load.
b. RustyNES_cli (Native adapter)
- Uses `rusty_nes_core` API → Runs emulation loop → Pushes frame buffer & audio samples → Renders via SDL2 → Reads Keyboard for controller → Reads/Writes save files.
c. RustyNES_wasm (WASM adapter)
- Compiles `rusty_nes_core` to WebAssembly → Exposes `init()`, `step()`, `loadROM()`, `saveState()` functions to JS.
d. RustyNES_web_ui (Browser front end)
- HTML/CSS/TS UI → Loads WASM via JS bindings → Maps browser events (keyboard) to controller API → Draws frames into `<canvas>` → Plays audio via Web Audio API → Provides file‐picker for ROMs & save states.

##### Architectural Patterns & Design Principles
- Layered architecture: Core Engine (pure logic) → Platform Adapters → Presentation/UI.
- Separation of concerns: Emulation logic is platform‐agnostic; front ends handle rendering/input.
- Modular crates (Rust’s package model) enable reuse across CLI and WASM.
- Adapter pattern: each front end “adapts” the same core API to different host environments (SDL2 vs JS).

## Diagram (Mermaid)

```mermaid
graph TD
    Title["RustyNES System Architecture\nv1.0"]:::title

    %% Core Engine Layer
    subgraph "RustyNES_core (Core Engine)"
        CPU["CPU Module"]:::core
        PPU["PPU Module"]:::core
        APU["APU Module"]:::core
        Bus["Memory Bus"]:::core
        Controller["Controller Input"]:::core
        ROM["ROM Loading"]:::core
        Buffer["Save/Load & Buffer"]:::core
    end

    %% Adapters Layer
    subgraph "RustyNES_cli (CLI Adapter)"
        Entry["main.rs & build.rs"]:::adapter
        SDL2bins["SDL2 Binaries & Libs"]:::adapter
    end

    subgraph "RustyNES_wasm (WASM Adapter)"
        WASMLib["WASM Library"]:::adapter
        JSGlue["JS Glue Code"]:::adapter
    end

    subgraph "RustyNES_web_ui (Web UI Adapter)"
        HTML["index.html & CSS"]:::adapter
        TS["main.ts"]:::adapter
        Config["package.json & tsconfig.json"]:::adapter
        Pkg["Bundled WASM pkg"]:::adapter
        Roms["Sample ROMs"]:::adapter
    end

    %% Native Runtime Layer
    subgraph "Native Runtime"
        SDL2["SDL2 (Graphics/Audio/Input)"]:::runtime
        FileSys["File System (ROMs & .sav)"]:::storage
    end

    %% Browser Runtime Layer
    subgraph "Browser Runtime"
        JS["JS Bindings"]:::runtime
        Canvas["HTML5 Canvas"]:::runtime
        AudioAPI["Web Audio API"]:::runtime
    end

    %% Data Flows
    Entry -->|"calls API"| CPU
    Entry -->|"calls API"| PPU
    Entry -->|"calls API"| APU
    Entry -->|"calls API"| Bus
    Entry -->|"calls API"| Controller
    Entry -->|"loadROM()"| ROM
    Entry -->|"saveState()"| Buffer

    WASMLib -->|"API calls"| CPU
    WASMLib -->|"API calls"| PPU
    WASMLib -->|"API calls"| APU
    WASMLib -->|"API calls"| Bus
    WASMLib -->|"API calls"| Controller
    WASMLib -->|"loadROM()"| ROM
    WASMLib -->|"saveState()"| Buffer

    HTML -->|"imports JS glue"| JSGlue
    TS -->|"imports JS glue"| JSGlue
    JSGlue -->|"binds to wasm"| WASMLib
    JS -->|"frame buffer"| Canvas
    JS -->|"audio samples"| AudioAPI
    TS -->|"select ROM"| Roms

    Entry -->|"render"| SDL2
    Entry -->|"audio output"| SDL2
    Entry -->|-->| FileSys
    WASMLib -->|-->| Roms

    %% File System interaction for Web
    Roms -->|-->| WASMLib

    %% Click Events
    click CPU "https://github.com/vedant416/rustynes/tree/main/RustyNES_core/src/cpu/"
    click PPU "https://github.com/vedant416/rustynes/tree/main/RustyNES_core/src/ppu/"
    click APU "https://github.com/vedant416/rustynes/tree/main/RustyNES_core/src/apu/"
    click Bus "https://github.com/vedant416/rustynes/blob/main/RustyNES_core/src/bus.rs"
    click Controller "https://github.com/vedant416/rustynes/blob/main/RustyNES_core/src/controller.rs"
    click ROM "https://github.com/vedant416/rustynes/blob/main/RustyNES_core/src/rom.rs"
    click Buffer "https://github.com/vedant416/rustynes/blob/main/RustyNES_core/src/buffer.rs"

    click Entry "https://github.com/vedant416/rustynes/blob/main/RustyNES_cli/src/main.rs"
    click SDL2bins "https://github.com/vedant416/rustynes/tree/main/RustyNES_cli/gnu-mingw/"

    click WASMLib "https://github.com/vedant416/rustynes/blob/main/RustyNES_wasm/src/lib.rs"
    click JSGlue "https://github.com/vedant416/rustynes/blob/main/RustyNES_wasm/foo.js"

    click HTML "https://github.com/vedant416/rustynes/blob/main/RustyNES_web_ui/index.html"
    click TS "https://github.com/vedant416/rustynes/blob/main/RustyNES_web_ui/src/main.ts"
    click Config "https://github.com/vedant416/rustynes/blob/main/RustyNES_web_ui/package.json"
    click Pkg "https://github.com/vedant416/rustynes/tree/main/RustyNES_web_ui/public/pkg/"
    click Roms "https://github.com/vedant416/rustynes/tree/main/RustyNES_web_ui/public/roms/"

    %% Styles
    classDef title fill:#ffffff,stroke:#000000,color:#000000,font-weight:bold
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef adapter fill:#d4edda,stroke:#155724,color:#155724
    classDef runtime fill:#fff3cd,stroke:#856404,color:#856404
    classDef storage fill:#f8d7da,stroke:#721c24,color:#721c24
```
