# obaraemmanuel/nes architecture

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

- Interactive diagram: https://gitdiagram.com/obaraemmanuel/nes
- Repository: https://github.com/obaraemmanuel/nes

## Overview

##### Main Components
a. Core Emulator Engine (Native C code)
- CPU6502 module (cpu6502.c/.h)
- PPU module (ppu.c/.h)
- APU module (apu.c/.h)
- MMU & Mapper subsystem (mmu.c/.h + src/mappers/*.c)
- Graphics & Audio output helpers (gfx.c/.h, biquad.c/.h)
- Input handlers (controller.c/.h, touchpad.c/.h, gamepad.c/.h)
- Utility & debug modules (utils.c/.h, debugtools.c/.h, trace.c)
- Main orchestrator (main.c, emulator.c/.h)

b. Native Library & Build System
- CMakeLists.txt (defines how native code builds into libnes.so)
- external/SDL & external/SDL_ttf (third-party libraries)

c. SDL / JNI Bridge
- org.libsdl.app package (SDL.java, SDLActivity.java, SDLSurface, etc.)
- Provides JNI glue:
– JNI calls from Java → native engine entry point
– Framebuffer render via SDL_Surface → Android Surface
– Audio callback wiring via SDLAudioManager
– Input events forwarded to native (HIDDeviceManager → controller.c)

d. Android Front-End App
- Gradle build (android/app/build.gradle, settings.gradle)
- UI Activities:
– MainActivity (ROM browser UI, RecyclerView with NESItemAdapter)
– EmulatorActivity (launches SDLActivity behind the scenes to run emulation)
- UI Layouts & Resources (res/layout/*.xml, drawable/, values/, mipmap/)
- Asset management (assets folder for bundled items)

##### Relationships & Data Flows
- ROM Selection Flow:
MainActivity UI → user taps a ROM → Java filepicker → path passed to EmulatorActivity.
- Emulation Startup:
EmulatorActivity → invokes SDLActivity (native SDL) → JNI init → native main.c reads ROM.
- Input Flow:
Android touch/gamepad events (EmulatorActivity → SDLInputConnection/HIDDeviceManager) → controller.c.
- Rendering & Audio Flow:
native PPU generates pixel buffer → SDL_Surface → SDLSurface → Android SurfaceView.
native APU audio buffer → SDLAudioManager → Android AudioTrack.
- Mapper & Memory:
CPU & PPU request memory reads/writes → MMU routes to ROM/RAM or mapper logic.

##### Architectural Patterns & Principles
- Layered Architecture: clear separation between Core Engine, SDL Bridge, and Android UI.
- Modular C design: one module per hardware component (CPU, PPU, APU, MMU, Mappers).
- Externalization of platform specifics: SDL abstracts cross-platform I/O.
- Build-time separation: CMake for native, Gradle for Android, coordinated via Android NDK plugin.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Android Front-End App Layer
    subgraph "Android Front-End App"
        direction TB
        MainAct["MainActivity"]:::android
        EmulatorAct["EmulatorActivity"]:::android
        NESAdapter["NESItemAdapter / Holder / Model"]:::android
        UILayouts["UI Layouts (XML)"]:::android
        Resources["Resources (drawable/values/mipmap)"]:::android
        Assets["Assets Folder"]:::android
        GradleBuild["Gradle Build (build.gradle / settings.gradle)"]:::android
    end

    %% SDL / JNI Bridge Layer
    subgraph "SDL / JNI Bridge"
        direction TB
        SDLJava["SDL.java"]:::jni
        SDLActivity["SDLActivity.java"]:::jni
        SDLSurface["SDLSurface.java"]:::jni
        SDLAudio["SDLAudioManager.java"]:::jni
        SDLInputConn["SDLInputConnection.java"]:::jni
        HIDDevMgr["HIDDeviceManager.java"]:::jni
    end

    %% Core Emulator Engine Layer
    subgraph "Core Emulator Engine (Native C)"
        direction TB
        MainCore["main.c / emulator.c"]:::core
        CPU6502["cpu6502.c / h"]:::core
        PPU["ppu.c / h"]:::core
        APU["apu.c / h"]:::core
        MMU["mmu.c / h\nmappers/*.c / mapper.h"]:::core
        GFX["gfx.c / h\nbiquad.c / h"]:::core
        Input["controller.c / h\ntouchpad.c / h\ngamepad.c / h"]:::core
        Utils["utils.c / h\ndebugtools.c / h\ntrace.c"]:::core
        CMake["CMakeLists.txt"]:::external
        SDL_ext["external/SDL"]:::external
        SDL_ttf["external/SDL_ttf"]:::external
    end

    %% Android App flows
    MainAct -->|"select ROM"| EmulatorAct
    EmulatorAct -->|"launch SDLActivity"| SDLActivity
    EmulatorAct -->|"use NESItemAdapter"| NESAdapter
    MainAct --> UILayouts
    MainAct --> Resources
    MainAct --> Assets
    MainAct --> GradleBuild

    %% JNI Bridge flows
    SDLActivity -->|"JNI SDL_main"| MainCore
    SDLActivity --> SDLSurface
    SDLActivity --> SDLAudio
    SDLActivity --> SDLInputConn
    SDLInputConn --> HIDDevMgr
    HIDDevMgr --> Input

    %% Core Engine internal
    MainCore --> CPU6502
    MainCore --> PPU
    MainCore --> APU
    MainCore --> MMU
    CPU6502 --> MMU
    PPU --> MMU
    PPU --> GFX
    APU --> GFX
    APU --> Utils
    MainCore --> Utils
    MainCore --> Input

    %% External libs and build
    CMake --> SDL_ext
    CMake --> SDL_ttf
    CMake --> MainCore

    %% Rendering & Audio flows
    PPU -->|"renderFrame()"| SDLSurface
    APU -->|"onAudioCallback()"| SDLAudio

    %% Click Events
    click CPU6502 "https://github.com/obaraemmanuel/nes/blob/master/src/cpu6502.c"
    click CPU6502 "https://github.com/obaraemmanuel/nes/blob/master/src/cpu6502.h"
    click PPU "https://github.com/obaraemmanuel/nes/blob/master/src/ppu.c"
    click PPU "https://github.com/obaraemmanuel/nes/blob/master/src/ppu.h"
    click APU "https://github.com/obaraemmanuel/nes/blob/master/src/apu.c"
    click APU "https://github.com/obaraemmanuel/nes/blob/master/src/apu.h"
    click MMU "https://github.com/obaraemmanuel/nes/blob/master/src/mmu.c"
    click MMU "https://github.com/obaraemmanuel/nes/blob/master/src/mmu.h"
    click MMU "https://github.com/obaraemmanuel/nes/blob/master/src/mappers/mapper.h"
    click GFX "https://github.com/obaraemmanuel/nes/blob/master/src/gfx.c"
    click GFX "https://github.com/obaraemmanuel/nes/blob/master/src/gfx.h"
    click GFX "https://github.com/obaraemmanuel/nes/blob/master/src/biquad.c"
    click GFX "https://github.com/obaraemmanuel/nes/blob/master/src/biquad.h"
    click Input "https://github.com/obaraemmanuel/nes/blob/master/src/controller.c"
    click Input "https://github.com/obaraemmanuel/nes/blob/master/src/controller.h"
    click Input "https://github.com/obaraemmanuel/nes/blob/master/src/touchpad.c"
    click Input "https://github.com/obaraemmanuel/nes/blob/master/src/touchpad.h"
    click Input "https://github.com/obaraemmanuel/nes/blob/master/src/gamepad.c"
    click Input "https://github.com/obaraemmanuel/nes/blob/master/src/gamepad.h"
    click Utils "https://github.com/obaraemmanuel/nes/blob/master/src/utils.c"
    click Utils "https://github.com/obaraemmanuel/nes/blob/master/src/utils.h"
    click Utils "https://github.com/obaraemmanuel/nes/blob/master/src/debugtools.c"
    click Utils "https://github.com/obaraemmanuel/nes/blob/master/src/debugtools.h"
    click Utils "https://github.com/obaraemmanuel/nes/blob/master/src/trace.c"
    click MainCore "https://github.com/obaraemmanuel/nes/blob/master/src/main.c"
    click MainCore "https://github.com/obaraemmanuel/nes/blob/master/src/emulator.c"
    click MainCore "https://github.com/obaraemmanuel/nes/blob/master/src/emulator.h"
    click CMake "https://github.com/obaraemmanuel/nes/blob/master/CMakeLists.txt"
    click SDL_ext "https://github.com/obaraemmanuel/nes/tree/master/external/SDL"
    click SDL_ttf "https://github.com/obaraemmanuel/nes/tree/master/external/SDL_ttf"
    click SDLJava "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/java/org/libsdl/app/SDL.java"
    click SDLActivity "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/java/org/libsdl/app/SDLActivity.java"
    click SDLSurface "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/java/org/libsdl/app/SDLSurface.java"
    click SDLAudio "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/java/org/libsdl/app/SDLAudioManager.java"
    click SDLInputConn "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/java/org/libsdl/app/SDLInputConnection.java"
    click HIDDevMgr "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/java/org/libsdl/app/HIDDeviceManager.java"
    click MainAct "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/java/com/barracoder/android/MainActivity.java"
    click EmulatorAct "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/java/com/barracoder/android/EmulatorActivity.java"
    click NESAdapter "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/java/com/barracoder/android/NESItemAdapter.java"
    click NESAdapter "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/java/com/barracoder/android/NESItemHolder.java"
    click NESAdapter "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/java/com/barracoder/android/NESItemModel.java"
    click UILayouts "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/res/layout/activity_main.xml"
    click UILayouts "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/res/layout/activity_emulator.xml"
    click UILayouts "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/res/layout/content_main.xml"
    click UILayouts "https://github.com/obaraemmanuel/nes/blob/master/android/app/src/main/res/layout/game_item.xml"
    click Resources "https://github.com/obaraemmanuel/nes/tree/master/android/app/src/main/res/drawable/"
    click Resources "https://github.com/obaraemmanuel/nes/tree/master/android/app/src/main/res/values/"
    click Resources "https://github.com/obaraemmanuel/nes/tree/master/android/app/src/main/res/mipmap/"
    click Assets "https://github.com/obaraemmanuel/nes/tree/master/android/app/src/main/assets/"
    click GradleBuild "https://github.com/obaraemmanuel/nes/blob/master/android/app/build.gradle"
    click GradleBuild "https://github.com/obaraemmanuel/nes/blob/master/android/settings.gradle"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef jni fill:#90EE90,stroke:#333,stroke-width:1px
    classDef android fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
