# hyde12/gameboy-emulator architecture

> Architecture diagram of the GitHub repository hyde12/gameboy-emulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyde12/gameboy-emulator
- Repository: https://github.com/hyde12/gameboy-emulator

## Overview

This is a small, unfinished Game Boy emulator. Its runtime workflow is: the application loads a ROM, repeatedly advances the emulated CPU, and updates a minifb window. The emulation core combines instruction execution, register state, and memory-bus access; ROMData stores the loaded cartridge bytes and external RAM. The displayed framebuffer is cleared rather than populated with emulated graphics. There is no README, and the ROM-header reader is commented out, so neither is represented as active functionality.

Main entry points: [`src/main.rs`](https://github.com/hyde12/gameboy-emulator/blob/main/src/main.rs) (Game Window), [`src/emu/gameboy.rs`](https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/gameboy.rs) (CPU Execution), [`src/emu/rom.rs`](https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/rom.rs) (ROM State), [`src/emu/registers.rs`](https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/registers.rs) (Registers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_window["Game Window<br/>[main.rs]"]
end

subgraph group_core["Emulation Core"]
  node_emulator["Emulator Runtime<br/>[gameboy.rs]"]
  node_cpu["CPU Execution<br/>[gameboy.rs]"]
  node_memory["Memory Bus<br/>[gameboy.rs]"]
  node_registers["Registers<br/>[registers.rs]"]
  node_byte_helper["Byte Helper<br/>[helpers.rs]"]
end

subgraph group_cart["Cartridge State"]
  node_rom_state["ROM State<br/>[rom.rs]"]
end

node_user(("User"))

node_user -->|"opens and controls"| node_window
node_window -->|"creates and ticks"| node_emulator
node_window -->|"loads ROM into"| node_rom_state
node_window -->|"updates display"| node_window
node_emulator -->|"runs tick"| node_cpu
node_cpu -->|"fetches and accesses"| node_memory
node_cpu -->|"reads and updates"| node_registers
node_cpu -->|"combines bytes"| node_byte_helper
node_memory -->|"reads ROM and RAM"| node_rom_state

click node_window "https://github.com/hyde12/gameboy-emulator/blob/main/src/main.rs"
click node_emulator "https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/gameboy.rs"
click node_cpu "https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/gameboy.rs"
click node_memory "https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/gameboy.rs"
click node_registers "https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/registers.rs"
click node_byte_helper "https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/helpers.rs"
click node_rom_state "https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/rom.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_window,node_user toneBlue
class node_emulator,node_cpu,node_memory,node_registers,node_byte_helper toneAmber
class node_rom_state toneMint
```

## Components

### Application

- [Game Window](https://github.com/hyde12/gameboy-emulator/blob/main/src/main.rs): `src/main.rs`

### Emulation Core

- [Emulator Runtime](https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/gameboy.rs): `src/emu/gameboy.rs`
- [CPU Execution](https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/gameboy.rs): `src/emu/gameboy.rs`
- [Memory Bus](https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/gameboy.rs): `src/emu/gameboy.rs`
- [Registers](https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/registers.rs): `src/emu/registers.rs`
- [Byte Helper](https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/helpers.rs): `src/emu/helpers.rs`

### Cartridge State

- [ROM State](https://github.com/hyde12/gameboy-emulator/blob/main/src/emu/rom.rs): `src/emu/rom.rs`

### Other components

- **User**

## Connections

- User → Game Window: opens and controls (evidence: `src/main.rs`)
- Game Window → Emulator Runtime: creates and ticks (evidence: `src/main.rs`)
- Game Window → ROM State: loads ROM into (evidence: `src/main.rs`)
- Game Window → Game Window: updates display (evidence: `src/main.rs`)
- Emulator Runtime → CPU Execution: runs tick (evidence: `src/emu/gameboy.rs`)
- CPU Execution → Memory Bus: fetches and accesses (evidence: `src/emu/gameboy.rs`)
- CPU Execution → Registers: reads and updates (evidence: `src/emu/gameboy.rs`)
- CPU Execution → Byte Helper: combines bytes (evidence: `src/emu/gameboy.rs`)
- Memory Bus → ROM State: reads ROM and RAM (evidence: `src/emu/gameboy.rs`)
