# victorgomes/gb architecture

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

- Interactive diagram: https://gitdiagram.com/victorgomes/gb
- Repository: https://github.com/victorgomes/gb

## Overview

Leiksveinn is a C Game Boy/Color emulator with SDL3 and browser/WASM hosts. The main workflow is to load a ROM, select its cartridge mapper, execute CPU instructions over the memory bus while timed hardware advances, then present video and audio. Cartridge persistence, save states, link play, printer output, and camera input are additional product branches. The browser shell adds touch controls and IndexedDB persistence, while its service worker caches the offline app shell. The sampled source is partial; unsampled subsystem links are included only where the README or module roles support them.

Main entry points: [`src/main.c`](https://github.com/victorgomes/gb/blob/main/src/main.c) (SDL host), [`web/main.js`](https://github.com/victorgomes/gb/blob/main/web/main.js) (Browser shell), [`src/mmu.c`](https://github.com/victorgomes/gb/blob/main/src/mmu.c) (System bus), [`src/cartridge.c`](https://github.com/victorgomes/gb/blob/main/src/cartridge.c) (Cartridge mapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hosts["Hosts and controls"]
  node_native["SDL host<br/>[main.c]"]
  node_browser["Browser shell<br/>[main.js]"]
  node_wasm["WASM core<br/>[main.c]"]
  node_offline["Offline shell<br/>[sw.js]"]
end

subgraph group_core["Emulation core"]
  node_cpu["SM83 CPU<br/>[cpu.c]"]
  node_bus["System bus<br/>[mmu.c]"]
  node_ppu["Pixel renderer<br/>[ppu.c]"]
  node_apu["Audio unit<br/>[apu.c]"]
  node_timer["Timer<br/>[timer.c]"]
end

subgraph group_media["Cartridges and persistence"]
  node_cart["Cartridge mapper<br/>[cartridge.c]"]
  node_config["Configuration<br/>[config.c]"]
  node_state["Save states<br/>[state.c]"]
  node_savefiles[("Battery saves<br/>[cartridge.c]")]
  node_webstorage[("Browser storage<br/>[main.js]")]
end

subgraph group_io["Peripheral I/O"]
  node_serial["Serial link<br/>[serial.c]"]
  node_printer["Game Boy Printer<br/>[printer.c]"]
  node_camera["Camera device<br/>[camera.c]"]
end

node_player(("Player"))
node_rom["Game ROM"]
node_webcam(("Host camera"))
node_audioout(("Audio output"))
node_display(("Display"))

node_player -->|"controls"| node_native
node_player -->|"controls"| node_browser
node_rom -->|"loads"| node_native
node_rom -->|"loads"| node_browser
node_native -->|"loads settings"| node_config
node_native -->|"loads cartridge"| node_cart
node_native -->|"runs emulation"| node_cpu
node_browser -->|"drives frames"| node_wasm
node_wasm -->|"runs emulation"| node_cpu
node_cpu -->|"reads and writes"| node_bus
node_bus -->|"dispatches access"| node_cart
node_bus -->|"advances timing"| node_ppu
node_bus -->|"advances timing"| node_apu
node_bus -->|"advances timing"| node_timer
node_bus -->|"dispatches access"| node_serial
node_cart -->|"persists SRAM"| node_savefiles
node_native -->|"saves snapshots"| node_state
node_browser -->|"saves snapshots"| node_state
node_browser -->|"reads and writes"| node_webstorage
node_state -.->|"browser snapshots"| node_webstorage
node_ppu -->|"framebuffer"| node_native
node_native -->|"presents video"| node_display
node_ppu -->|"framebuffer"| node_browser
node_browser -->|"draws video"| node_display
node_apu -->|"audio samples"| node_native
node_native -->|"plays audio"| node_audioout
node_apu -->|"audio samples"| node_browser
node_browser -->|"streams audio"| node_audioout
node_serial -.->|"sends print data"| node_printer
node_printer -->|"print output"| node_native
node_cart -->|"camera cartridge"| node_camera
node_camera -.->|"captures image"| node_webcam
node_native -.->|"registers worker"| node_offline

click node_native "https://github.com/victorgomes/gb/blob/main/src/main.c"
click node_browser "https://github.com/victorgomes/gb/blob/main/web/main.js"
click node_wasm "https://github.com/victorgomes/gb/blob/main/src/main.c"
click node_offline "https://github.com/victorgomes/gb/blob/main/web/sw.js"
click node_cpu "https://github.com/victorgomes/gb/blob/main/src/cpu.c"
click node_bus "https://github.com/victorgomes/gb/blob/main/src/mmu.c"
click node_ppu "https://github.com/victorgomes/gb/blob/main/src/ppu.c"
click node_apu "https://github.com/victorgomes/gb/blob/main/src/apu.c"
click node_timer "https://github.com/victorgomes/gb/blob/main/src/timer.c"
click node_cart "https://github.com/victorgomes/gb/blob/main/src/cartridge.c"
click node_config "https://github.com/victorgomes/gb/blob/main/src/config.c"
click node_state "https://github.com/victorgomes/gb/blob/main/src/state.c"
click node_savefiles "https://github.com/victorgomes/gb/blob/main/src/cartridge.c"
click node_serial "https://github.com/victorgomes/gb/blob/main/src/serial.c"
click node_printer "https://github.com/victorgomes/gb/blob/main/src/printer.c"
click node_camera "https://github.com/victorgomes/gb/blob/main/src/camera.c"
click node_webstorage "https://github.com/victorgomes/gb/blob/main/web/main.js"

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_native,node_browser,node_wasm,node_offline toneBlue
class node_cpu,node_bus,node_ppu,node_apu,node_timer toneAmber
class node_cart,node_config,node_state,node_savefiles,node_webstorage toneMint
class node_serial,node_printer,node_camera toneRose
class node_player,node_rom,node_webcam,node_audioout,node_display toneIndigo
```

## Components

### Hosts and controls

- [SDL host](https://github.com/victorgomes/gb/blob/main/src/main.c): `src/main.c`
- [Browser shell](https://github.com/victorgomes/gb/blob/main/web/main.js): `web/main.js`
- [WASM core](https://github.com/victorgomes/gb/blob/main/src/main.c): `src/main.c`
- [Offline shell](https://github.com/victorgomes/gb/blob/main/web/sw.js): `web/sw.js`

### Emulation core

- [SM83 CPU](https://github.com/victorgomes/gb/blob/main/src/cpu.c): `src/cpu.c`
- [System bus](https://github.com/victorgomes/gb/blob/main/src/mmu.c): `src/mmu.c`
- [Pixel renderer](https://github.com/victorgomes/gb/blob/main/src/ppu.c): `src/ppu.c`
- [Audio unit](https://github.com/victorgomes/gb/blob/main/src/apu.c): `src/apu.c`
- [Timer](https://github.com/victorgomes/gb/blob/main/src/timer.c): `src/timer.c`

### Cartridges and persistence

- [Cartridge mapper](https://github.com/victorgomes/gb/blob/main/src/cartridge.c): `src/cartridge.c`
- [Configuration](https://github.com/victorgomes/gb/blob/main/src/config.c): `src/config.c`
- [Save states](https://github.com/victorgomes/gb/blob/main/src/state.c): `src/state.c`
- [Battery saves](https://github.com/victorgomes/gb/blob/main/src/cartridge.c): `src/cartridge.c`
- [Browser storage](https://github.com/victorgomes/gb/blob/main/web/main.js): `web/main.js`

### Peripheral I/O

- [Serial link](https://github.com/victorgomes/gb/blob/main/src/serial.c): `src/serial.c`
- [Game Boy Printer](https://github.com/victorgomes/gb/blob/main/src/printer.c): `src/printer.c`
- [Camera device](https://github.com/victorgomes/gb/blob/main/src/camera.c): `src/camera.c`

### Other components

- **Player**
- **Game ROM**
- **Host camera**
- **Audio output**
- **Display**

## Connections

- Player → SDL host: controls
- Player → Browser shell: controls
- Game ROM → SDL host: loads
- Game ROM → Browser shell: loads
- SDL host → Configuration: loads settings
- SDL host → Cartridge mapper: loads cartridge
- SDL host → SM83 CPU: runs emulation
- Browser shell → WASM core: drives frames
- WASM core → SM83 CPU: runs emulation
- SM83 CPU → System bus: reads and writes
- System bus → Cartridge mapper: dispatches access
- System bus → Pixel renderer: advances timing
- System bus → Audio unit: advances timing
- System bus → Timer: advances timing
- System bus → Serial link: dispatches access
- Cartridge mapper → Battery saves: persists SRAM
- SDL host → Save states: saves snapshots
- Browser shell → Save states: saves snapshots
- Browser shell → Browser storage: reads and writes
- Save states → Browser storage: browser snapshots
- Pixel renderer → SDL host: framebuffer
- SDL host → Display: presents video
- Pixel renderer → Browser shell: framebuffer
- Browser shell → Display: draws video
- Audio unit → SDL host: audio samples
- SDL host → Audio output: plays audio
- Audio unit → Browser shell: audio samples
- Browser shell → Audio output: streams audio
- Serial link → Game Boy Printer: sends print data
- Game Boy Printer → SDL host: print output
- Cartridge mapper → Camera device: camera cartridge
- Camera device → Host camera: captures image
- SDL host → Offline shell: registers worker