# victorsanchesdealmeida/gba-emulator-for-android architecture

> Architecture diagram of the GitHub repository victorsanchesdealmeida/gba-emulator-for-android, 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/victorsanchesdealmeida/gba-emulator-for-android
- Repository: https://github.com/victorsanchesdealmeida/gba-emulator-for-android

## Overview

GBA Emulator is a Game Boy Advance player: the user selects a ROM, the app supplies its bundled BIOS, and the native Rust core runs the game and returns video/audio while accepting button input. The README documents automatic cartridge-save restoration and persistence. The sampled excerpts establish the emulator’s peripheral and BIOS behavior; some UI-to-native details and peripheral wiring are documented but not shown in full, so the graph omits uncertain call links.

Main entry points: [`core/src/emulator/mod.rs`](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/emulator/mod.rs) (Frame runner), [`src/app/index.tsx`](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/src/app/index.tsx) (Game screen), [`native/ffi/src/lib.rs`](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/native/ffi/src/lib.rs) (Rust FFI), [`modules/gba-emulator/android/src/main/java/expo/modules/gbaemulator/GbaEmulatorModule.kt`](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/modules/gba-emulator/android/src/main/java/expo/modules/gbaemulator/GbaEmulatorModule.kt) (Android module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Expo app"]
  node_app["Game screen<br/>[index.tsx]"]
end

subgraph group_native["Native interface"]
  node_native_module["JS module"]
  node_native_view["Emulator view"]
  node_android_module["Android module"]
  node_android_view["Android view<br/>[GbaEmulatorView.kt]"]
  node_jni["JNI bridge<br/>[GbaNative.kt]"]
  node_ffi["Rust FFI<br/>[lib.rs]"]
end

subgraph group_core["Emulation core"]
  node_emulator["Frame runner<br/>[mod.rs]"]
  node_bus["Memory bus<br/>[bus.rs]"]
end

subgraph group_hardware["GBA hardware"]
  node_cpu["ARM7TDMI CPU<br/>[mod.rs]"]
  node_bios["BIOS emulation<br/>[mod.rs]"]
  node_cartridge["Cartridge<br/>[cartridge.rs]"]
  node_saves[("Save memory<br/>[mod.rs]")]
  node_ppu["Graphics<br/>[mod.rs]"]
  node_apu["Audio<br/>[mod.rs]"]
  node_dma["DMA channels<br/>[mod.rs]"]
  node_timers["Timers<br/>[mod.rs]"]
  node_interrupts["Interrupt controller<br/>[mod.rs]"]
  node_joypad["Joypad<br/>[mod.rs]"]
end

node_player(("Player"))
node_rom["ROM file"]
node_bios_asset["Bundled BIOS"]
node_save_files[("Save files")]

node_player -->|"operates"| node_app
node_player -->|"chooses"| node_rom
node_rom -->|"loads"| node_app
node_bios_asset -->|"supplies BIOS"| node_app
node_app -->|"controls session"| node_native_module
node_app -->|"renders view"| node_native_view
node_native_view -->|"hosts view"| node_android_view
node_native_module -->|"invokes"| node_android_module
node_android_module -->|"calls native"| node_jni
node_jni -->|"dispatches"| node_ffi
node_ffi -->|"runs frames"| node_emulator
node_emulator -->|"steps"| node_cpu
node_cpu -->|"reads and writes"| node_bus
node_emulator -->|"ticks hardware"| node_bus
node_bus -->|"accesses ROM"| node_cartridge
node_cartridge -->|"uses save type"| node_saves
node_emulator -->|"handles SWI and IRQ"| node_bios
node_emulator -->|"advances"| node_ppu
node_emulator -->|"advances"| node_timers
node_emulator -->|"ticks and samples"| node_apu
node_emulator -->|"dispatches transfers"| node_dma
node_emulator -->|"checks pending IRQ"| node_interrupts
node_emulator -->|"sends button events"| node_joypad
node_ppu -->|"requests events"| node_interrupts
node_timers -->|"requests overflow"| node_interrupts
node_dma -->|"requests completion"| node_interrupts
node_ffi -->|"reads frame output"| node_ppu
node_ffi -->|"samples audio"| node_apu
node_ffi -->|"loads and exports data"| node_saves
node_save_files -->|"read and written by"| node_android_module
node_android_module -->|"persists saves"| node_save_files
node_app -->|"derives save path"| node_save_files

click node_app "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/src/app/index.tsx"
click node_native_module "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/modules/gba-emulator/src/GbaEmulatorModule.ts"
click node_native_view "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/modules/gba-emulator/src/GbaEmulatorView.tsx"
click node_android_module "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/modules/gba-emulator/android/src/main/java/expo/modules/gbaemulator/GbaEmulatorModule.kt"
click node_android_view "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/modules/gba-emulator/android/src/main/java/expo/modules/gbaemulator/GbaEmulatorView.kt"
click node_jni "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/modules/gba-emulator/android/src/main/java/expo/modules/gbaemulator/GbaNative.kt"
click node_ffi "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/native/ffi/src/lib.rs"
click node_emulator "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/emulator/mod.rs"
click node_bus "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/memory/bus.rs"
click node_cpu "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/cpu/mod.rs"
click node_bios "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/bios/mod.rs"
click node_cartridge "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/cartridge/cartridge.rs"
click node_saves "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/cartridge/save/mod.rs"
click node_ppu "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/ppu/mod.rs"
click node_apu "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/apu/mod.rs"
click node_dma "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/dma/mod.rs"
click node_timers "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/timer/mod.rs"
click node_interrupts "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/interrupts/mod.rs"
click node_joypad "https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/joypad/mod.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_app toneBlue
class node_native_module,node_native_view,node_android_module,node_android_view,node_jni,node_ffi,node_save_files toneAmber
class node_emulator,node_bus toneMint
class node_cpu,node_bios,node_cartridge,node_saves,node_ppu,node_apu,node_dma,node_timers,node_interrupts,node_joypad toneRose
class node_player,node_rom,node_bios_asset toneIndigo
```

## Components

### Expo app

- [Game screen](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/src/app/index.tsx): `src/app/index.tsx`

### Native interface

- [JS module](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/modules/gba-emulator/src/GbaEmulatorModule.ts): `modules/gba-emulator/src/GbaEmulatorModule.ts`
- [Emulator view](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/modules/gba-emulator/src/GbaEmulatorView.tsx): `modules/gba-emulator/src/GbaEmulatorView.tsx`
- [Android module](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/modules/gba-emulator/android/src/main/java/expo/modules/gbaemulator/GbaEmulatorModule.kt): `modules/gba-emulator/android/src/main/java/expo/modules/gbaemulator/GbaEmulatorModule.kt`
- [Android view](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/modules/gba-emulator/android/src/main/java/expo/modules/gbaemulator/GbaEmulatorView.kt): `modules/gba-emulator/android/src/main/java/expo/modules/gbaemulator/GbaEmulatorView.kt`
- [JNI bridge](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/modules/gba-emulator/android/src/main/java/expo/modules/gbaemulator/GbaNative.kt): `modules/gba-emulator/android/src/main/java/expo/modules/gbaemulator/GbaNative.kt`
- [Rust FFI](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/native/ffi/src/lib.rs): `native/ffi/src/lib.rs`

### Emulation core

- [Frame runner](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/emulator/mod.rs): `core/src/emulator/mod.rs`
- [Memory bus](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/memory/bus.rs): `core/src/memory/bus.rs`

### GBA hardware

- [ARM7TDMI CPU](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/cpu/mod.rs): `core/src/cpu/mod.rs`
- [BIOS emulation](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/bios/mod.rs): `core/src/bios/mod.rs`
- [Cartridge](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/cartridge/cartridge.rs): `core/src/cartridge/cartridge.rs`
- [Save memory](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/cartridge/save/mod.rs): `core/src/cartridge/save/mod.rs`
- [Graphics](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/ppu/mod.rs): `core/src/ppu/mod.rs`
- [Audio](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/apu/mod.rs): `core/src/apu/mod.rs`
- [DMA channels](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/dma/mod.rs): `core/src/dma/mod.rs`
- [Timers](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/timer/mod.rs): `core/src/timer/mod.rs`
- [Interrupt controller](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/interrupts/mod.rs): `core/src/interrupts/mod.rs`
- [Joypad](https://github.com/victorsanchesdealmeida/gba-emulator-for-android/blob/master/core/src/joypad/mod.rs): `core/src/joypad/mod.rs`

### Other components

- **Player**
- **ROM file**
- **Bundled BIOS**
- **Save files**

## Connections

- Player → Game screen: operates
- Player → ROM file: chooses
- ROM file → Game screen: loads
- Bundled BIOS → Game screen: supplies BIOS
- Game screen → JS module: controls session
- Game screen → Emulator view: renders view
- Emulator view → Android view: hosts view
- JS module → Android module: invokes
- Android module → JNI bridge: calls native
- JNI bridge → Rust FFI: dispatches
- Rust FFI → Frame runner: runs frames
- Frame runner → ARM7TDMI CPU: steps
- ARM7TDMI CPU → Memory bus: reads and writes
- Frame runner → Memory bus: ticks hardware
- Memory bus → Cartridge: accesses ROM
- Cartridge → Save memory: uses save type
- Frame runner → BIOS emulation: handles SWI and IRQ
- Frame runner → Graphics: advances
- Frame runner → Timers: advances
- Frame runner → Audio: ticks and samples
- Frame runner → DMA channels: dispatches transfers
- Frame runner → Interrupt controller: checks pending IRQ
- Frame runner → Joypad: sends button events
- Graphics → Interrupt controller: requests events
- Timers → Interrupt controller: requests overflow
- DMA channels → Interrupt controller: requests completion
- Rust FFI → Graphics: reads frame output
- Rust FFI → Audio: samples audio
- Rust FFI → Save memory: loads and exports data
- Save files → Android module: read and written by
- Android module → Save files: persists saves
- Game screen → Save files: derives save path