# senior-wanillah/gb-emulator architecture

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

- Interactive diagram: https://gitdiagram.com/senior-wanillah/gb-emulator
- Repository: https://github.com/senior-wanillah/gb-emulator

## Overview

This is a learning-focused Game Boy emulator prototype. The user runs the executable, optionally supplies a ROM, and the runtime loads it (or installs a demo program), steps the CPU, and prints CPU and PPU test output. The graph separates orchestration, core emulation, and cartridge/display behavior. It reflects the sampled implementation and documented capabilities; it does not imply complete PPU timing, memory banking, or full hardware emulation.

Main entry points: [`src/main.c`](https://github.com/senior-wanillah/gb-emulator/blob/main/src/main.c) (Emulator runtime), [`src/cpu.c`](https://github.com/senior-wanillah/gb-emulator/blob/main/src/cpu.c) (CPU execution), [`src/ppu.c`](https://github.com/senior-wanillah/gb-emulator/blob/main/src/ppu.c) (PPU test renderer), [`src/cartridge.c`](https://github.com/senior-wanillah/gb-emulator/blob/main/src/cartridge.c) (ROM loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_main["Emulator runtime<br/>[main.c]"]
end

subgraph group_core["Emulation core"]
  node_cpu["CPU execution<br/>[cpu.c]"]
  node_memory["Address space<br/>[memory.c]"]
end

subgraph group_io["Cartridge and display"]
  node_cartridge["ROM loading<br/>[cartridge.c]"]
  node_header["Header inspection<br/>[cartridge.c]"]
  node_ppu["PPU test renderer<br/>[ppu.c]"]
end

node_user(("User"))
node_filesystem["ROM file"]
node_console["Console output"]

node_user -->|"runs"| node_main
node_main -->|"resets"| node_memory
node_main -->|"resets"| node_cpu
node_main -->|"resets"| node_ppu
node_main -->|"loads ROM"| node_cartridge
node_main -->|"inspects header"| node_header
node_main -->|"steps execution"| node_cpu
node_cpu -->|"reads instructions"| node_memory
node_cartridge -->|"reads ROM"| node_filesystem
node_main -->|"renders pattern"| node_ppu
node_main -->|"prints framebuffer"| node_ppu
node_main -->|"prints status"| node_console
node_ppu -->|"prints ASCII"| node_console
node_main -->|"dumps registers"| node_cpu

click node_main "https://github.com/senior-wanillah/gb-emulator/blob/main/src/main.c"
click node_cpu "https://github.com/senior-wanillah/gb-emulator/blob/main/src/cpu.c"
click node_memory "https://github.com/senior-wanillah/gb-emulator/blob/main/src/memory.c"
click node_cartridge "https://github.com/senior-wanillah/gb-emulator/blob/main/src/cartridge.c"
click node_header "https://github.com/senior-wanillah/gb-emulator/blob/main/src/cartridge.c"
click node_ppu "https://github.com/senior-wanillah/gb-emulator/blob/main/src/ppu.c"

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_main,node_user toneBlue
class node_cpu,node_memory toneAmber
class node_cartridge,node_header,node_ppu toneMint
class node_filesystem,node_console toneIndigo
```

## Components

### Runtime orchestration

- [Emulator runtime](https://github.com/senior-wanillah/gb-emulator/blob/main/src/main.c): `src/main.c`

### Emulation core

- [CPU execution](https://github.com/senior-wanillah/gb-emulator/blob/main/src/cpu.c): `src/cpu.c`
- [Address space](https://github.com/senior-wanillah/gb-emulator/blob/main/src/memory.c): `src/memory.c`

### Cartridge and display

- [ROM loading](https://github.com/senior-wanillah/gb-emulator/blob/main/src/cartridge.c): `src/cartridge.c`
- [Header inspection](https://github.com/senior-wanillah/gb-emulator/blob/main/src/cartridge.c): `src/cartridge.c`
- [PPU test renderer](https://github.com/senior-wanillah/gb-emulator/blob/main/src/ppu.c): `src/ppu.c`

### Other components

- **User**
- **ROM file**
- **Console output**

## Connections

- User → Emulator runtime: runs (evidence: `README.md`)
- Emulator runtime → Address space: resets (evidence: `src/main.c`)
- Emulator runtime → CPU execution: resets (evidence: `src/main.c`)
- Emulator runtime → PPU test renderer: resets (evidence: `src/main.c`)
- Emulator runtime → ROM loading: loads ROM (evidence: `src/main.c`)
- Emulator runtime → Header inspection: inspects header (evidence: `src/main.c`)
- Emulator runtime → CPU execution: steps execution (evidence: `src/main.c`)
- CPU execution → Address space: reads instructions (evidence: `src/cpu.c`)
- ROM loading → ROM file: reads ROM (evidence: `src/cartridge.c`)
- Emulator runtime → PPU test renderer: renders pattern (evidence: `src/main.c`)
- Emulator runtime → PPU test renderer: prints framebuffer (evidence: `src/main.c`)
- Emulator runtime → Console output: prints status (evidence: `src/main.c`)
- PPU test renderer → Console output: prints ASCII (evidence: `src/ppu.c`)
- Emulator runtime → CPU execution: dumps registers (evidence: `src/main.c`)
