# ergoadams/arbne architecture

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

- Interactive diagram: https://gitdiagram.com/ergoadams/arbne
- Repository: https://github.com/ergoadams/arbne

## Overview

##### Main components
- Emulator (driver): The central hub that likely initializes and connects all hardware emulation modules.
- CPU (cpu.py): Emulates the processor responsible for executing the game/program instructions.
- PPU (ppu.py): Handles graphics, including background rendering and sprite management.
- Bus (bus.py): Interconnects the CPU, PPU, and other memory modules, managing read/write operations.
- Cartridge (cartridge.py): Simulates the game cartridge from which ROM data is loaded. It might also contain additional ROM/RAM regions.
- Mapper (mapper.py): Handles memory mapping, allowing support for different cartridge mapping hardware.
- (Optional) Additional components may include aspects such as debugging support or a test harness (referenced in the README TODOs).

##### Their interactions
- The Emulator module coordinates the initialization and running of emulation cycles, triggering updates in the CPU and PPU.
- The CPU communicates with both the Cartridge (via the Bus) to fetch instructions and data, and with the Mapper to translate addresses.
- The PPU reads from the Cartridge and through the Mapper for graphics data, and processes background and sprite rendering.
- The Bus sits in the middle, facilitating bidirectional data transfer between the CPU, PPU, and Cartridge.
- The Mapper acts as a translation layer for memory addresses, affecting both CPU and PPU reads for correct ROM/RAM mapping.

##### Architectural patterns and design principles
- Modularity: Each major hardware component is encapsulated in its own module/file, allowing isolation and independent testing.
- Emulation Loop: The Emulator likely maintains an emulation loop that simulates clock cycles, coordinating updates across CPU, PPU, and bus activities.
- Data Flow Abstraction: Communication flows via the bus and address mapping (handled by the mapper) reflect clear separation of concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    E["Emulator (driver)\nCoordinates initialization and emulation cycle"]:::process
    CPU["CPU – Emulates processor instructions"]:::process
    PPU["PPU – Handles graphics rendering and sprites"]:::process
    Bus["Bus – Manages memory read/write operations"]:::bus
    Cart["Cartridge – Loads NES ROM data"]:::support
    Map["Mapper – Performs address translation"]:::support

    E -->|"initializes"| CPU
    E -->|"initializes"| PPU

    CPU <-->|"communicates"| Bus
    PPU <-->|"communicates"| Bus

    Bus <-->|"data transfer"| Cart
    Bus <-->|"data transfer"| Map

    Cart -->|"translates"| Map

    click E "https://github.com/ergoadams/arbne/blob/master/emulator.py"
    click CPU "https://github.com/ergoadams/arbne/blob/master/cpu.py"
    click PPU "https://github.com/ergoadams/arbne/blob/master/ppu.py"
    click Bus "https://github.com/ergoadams/arbne/blob/master/bus.py"
    click Cart "https://github.com/ergoadams/arbne/blob/master/cartridge.py"
    click Map "https://github.com/ergoadams/arbne/blob/master/mapper.py"

    classDef process fill:#cfe2f3,stroke:#0b5394,stroke-width:2px;
    classDef bus fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef support fill:#fff2cc,stroke:#bf9000,stroke-width:2px;
```
