# n1ark/gbc-emulator architecture

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

- Interactive diagram: https://gitdiagram.com/n1ark/gbc-emulator
- Repository: https://github.com/n1ark/gbc-emulator

## Overview

##### Main Components
- Frontend: Represented by the src/frontend folder. This includes:
- The application’s entry point and React components (GameInput, Screen, Drawer, etc.).
- Helpers such as the AudioPlayer, ConfigContext, and ImageFilter utilities.
- Emulator Core: Found in src/emulator.
- The central emulation system (System.ts) that likely ties together the CPU, Memory, Timer, Interrupts, and I/O.
- CPU (CPU.ts) and peripheral components (Memory, Timer, Interrupts).
- PPU (with submodules like ColorController, VRAMController, OAM) which handle graphics and display.
- APU (with its SoundChannel classes) to emulate audio.
- MBC modules (MBC.ts, MBC1, MBC2, MBC3, MBC5, and NoMBC) and support for game cartridges.
- Testing Assets and ROMs: The public/tests directory contains a rich set of test ROMs categorized by functionality (acid tests, CPU, APU, etc.), which support emulator verification.
- Build & Configuration: The root-level configuration files (package.json, vite.config.ts, tsconfig.json) and index.html instantiate the web app’s environment.

##### Relationships and Interactions
- Frontend-to-Emulator Integration:
- The frontend collects user inputs (via GameInput, KeybindingInput, etc.) and forwards these to the emulator core.
- It also receives output data (video, audio) generated by the emulator.
- Emulator Core Interactions:
- The System.ts module acts as the conductor, coordinating between the CPU, PPU, APU, and other components like Memory.
- The CPU drives the instruction cycles and uses the MBC implementations to handle different cartridge memory schemes.
- The PPU and its controllers (VRAMController, ColorController, OAM) collaborate to render video output.
- The APU (with distinct sound channels) manages audio processing.
- Testing & Validation:
- The public/tests directory serves as a collection of ROM-based test cases that trigger specific paths within the emulator (e.g., testing CPU instructions, interrupt timings, DMA routines, etc.).

##### Architectural Patterns and Design Principles
- Modularity and Separation of Concerns:
- The clear separation between emulator subsystems (CPU, PPU, APU, memory management) aids in isolated development and testing.
- The frontend, as a distinct layer, communicates with the emulator core via defined interfaces or callbacks.
- Layered Architecture:
- With the hardware emulation logic in a “backend-like” layer (even though it runs in the browser) and UI components in the frontend, the system adheres to design principles similar to MVC or MVVM.
- Use of Typescript and React:
- Type safety across modules supports clear contracts between components.
- React-based state management in the frontend ensures that user interactions are handled efficiently.

##### Relevant Technologies, Frameworks, and Libraries
- TypeScript for type safety across emulator and frontend modules.
- React (TSX) for the user interface.
- Vite as the build tool enabling fast development cycles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend"
        A["Frontend (React UI)"]:::frontend
        B["App Entry (main)"]:::frontend
        subgraph "Components"
            C["GameInput"]:::frontend
            D["Screen"]:::frontend
            E["Drawer"]:::frontend
            F["Alerts"]:::frontend
            G["KeybindingInput"]:::frontend
            H["Other Components"]:::frontend
        end
        subgraph "Helpers"
            I["AudioPlayer"]:::frontend
            J["ConfigContext"]:::frontend
            K["ImageFilter Utilities"]:::frontend
            L["useKeys Hook"]:::frontend
        end
        A --> B
        B --> C
        C --> D
        D --> E
        E --> F
        F --> G
        G --> H
        A --> I
        I --> J
        J --> K
        K --> L
    end

    subgraph "Emulator Core"
        M["System"]:::emulator
        subgraph "CPU & Memory"
            M1["CPU"]:::emulator
            M2["Memory"]:::emulator
            M3["WRAM"]:::emulator
        end
        subgraph "Timer & Interrupts"
            M4["Timer"]:::emulator
            M5["Interrupts"]:::emulator
            M6["Register"]:::emulator
        end
        subgraph "PPU (Graphics)"
            M7["PPU"]:::emulator
            M8["VRAM Controller"]:::emulator
            M9["Color Controller"]:::emulator
            M10["OAM"]:::emulator
        end
        subgraph "APU (Audio)"
            M11["APU"]:::emulator
            subgraph "Sound Channels"
                M12["SoundChannel"]:::emulator
                M13["SoundChannel1"]:::emulator
                M14["SoundChannel2"]:::emulator
                M15["SoundChannel3"]:::emulator
                M16["SoundChannel4"]:::emulator
            end
        end
        subgraph "Cartridge & MBC"
            M17["GameCartridge"]:::emulator
            M18["MBC Interface"]:::emulator
            M19["MBC1"]:::emulator
            M20["MBC2"]:::emulator
            M21["MBC3"]:::emulator
            M22["MBC5"]:::emulator
            M23["NoMBC"]:::emulator
        end
        subgraph "I/O"
            M24["GameBoyInput"]:::emulator
            M25["JoypadInput"]:::emulator
            M26["GameBoyOutput"]:::emulator
        end

        M --> M1
        M --> M2
        M2 --> M3
        M --> M4
        M4 --> M5
        M5 --> M6
        M --> M7
        M7 --> M8
        M7 --> M9
        M7 --> M10
        M --> M11
        M11 --> M12
        M11 --> M13
        M11 --> M14
        M11 --> M15
        M11 --> M16
        M --> M17
        M17 --> M18
        M18 --> M19
        M18 --> M20
        M18 --> M21
        M18 --> M22
        M18 --> M23
        M --> M24
        M24 --> M25
        M --> M26

        %% Frontend interacts with Emulator Core
        C -->|"input"| M
        M7 -->|"video"| D
        M11 -->|"audio"| C
    end

    subgraph "Testing & Build"
        T1["Test ROMs"]:::testing
        T2["Build Config Files"]:::testing
        T3["HTML Entry Point"]:::testing
    end

    %% Frontend Output Rendering
    D -->|"rendersVideo"| A
    C -->|"receivesAudio"| A

    %% Click Events for Frontend
    click A "https://github.com/n1ark/gbc-emulator/tree/main/src/frontend"
    click B "https://github.com/n1ark/gbc-emulator/blob/main/src/frontend/main.tsx"
    click C "https://github.com/n1ark/gbc-emulator/blob/main/src/frontend/components/GameInput.tsx"
    click D "https://github.com/n1ark/gbc-emulator/blob/main/src/frontend/components/Screen.tsx"
    click E "https://github.com/n1ark/gbc-emulator/blob/main/src/frontend/components/Drawer/Drawer.tsx"
    click F "https://github.com/n1ark/gbc-emulator/blob/main/src/frontend/components/Alerts.tsx"
    click G "https://github.com/n1ark/gbc-emulator/blob/main/src/frontend/components/KeybindingInput.tsx"
    click I "https://github.com/n1ark/gbc-emulator/blob/main/src/frontend/helpers/AudioPlayer.ts"
    click J "https://github.com/n1ark/gbc-emulator/blob/main/src/frontend/helpers/ConfigContext.tsx"
    click K "https://github.com/n1ark/gbc-emulator/blob/main/src/frontend/helpers/ImageFilter/Base.ts"
    click L "https://github.com/n1ark/gbc-emulator/blob/main/src/frontend/helpers/useKeys.ts"

    %% Click Events for Emulator Core
    click M "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/System.ts"
    click M1 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/CPU.ts"
    click M2 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/Memory.ts"
    click M3 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/WRAM.ts"
    click M4 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/Timer.ts"
    click M5 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/Interrupts.ts"
    click M6 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/Register.ts"
    click M7 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/ppu/PPU.ts"
    click M8 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/ppu/VRAMController.ts"
    click M9 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/ppu/ColorController.ts"
    click M10 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/ppu/OAM.ts"
    click M11 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/apu/APU.ts"
    click M12 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/apu/SoundChannel.ts"
    click M13 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/apu/SoundChannel1.ts"
    click M14 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/apu/SoundChannel2.ts"
    click M15 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/apu/SoundChannel3.ts"
    click M16 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/apu/SoundChannel4.ts"
    click M17 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/GameCartridge.ts"
    click M18 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/mbc/MBC.ts"
    click M19 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/mbc/MBC1.ts"
    click M20 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/mbc/MBC2.ts"
    click M21 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/mbc/MBC3.ts"
    click M22 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/mbc/MBC5.ts"
    click M23 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/mbc/NoMBC.ts"
    click M24 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/GameBoyInput.ts"
    click M25 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/JoypadInput.ts"
    click M26 "https://github.com/n1ark/gbc-emulator/blob/main/src/emulator/GameBoyOutput.ts"

    %% Click Events for Testing & Build
    click T1 "https://github.com/n1ark/gbc-emulator/tree/main/public/tests"
    click T2 "https://github.com/n1ark/gbc-emulator/blob/main/package.json"
    click T3 "https://github.com/n1ark/gbc-emulator/blob/main/index.html"

    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef emulator fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef testing fill:#FFD700,stroke:#000,stroke-width:2px;
```
