# benahmed-adam/8chip8 architecture

> Architecture diagram of the GitHub repository benahmed-adam/8chip8, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benahmed-adam/8chip8
- Repository: https://github.com/benahmed-adam/8chip8

## Overview

8Chip8 is a Chip-8 emulator whose user workflow is to supply a ROM path, load it into emulator memory, execute instructions in a timed loop, and see the resulting display; keyboard state and timer-driven beeps support gameplay. The emulator core also implements the instruction set and built-in font. Source excerpts show the main runtime calls and data transfers; ROM examples are present under roms/, but the executable accepts a path supplied at launch.

Main entry points: [`src/main.cpp`](https://github.com/benahmed-adam/8chip8/blob/main/src/main.cpp) (Emulator loop), [`src/chip8.hpp`](https://github.com/benahmed-adam/8chip8/blob/main/src/chip8.hpp) (Chip-8 state), [`src/beep.hpp`](https://github.com/benahmed-adam/8chip8/blob/main/src/beep.hpp) (Beeper), [`src/chip8.cpp`](https://github.com/benahmed-adam/8chip8/blob/main/src/chip8.cpp) (ROM loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Runtime app"]
  node_loop["Emulator loop<br/>[main.cpp]"]
  node_input["Keyboard input<br/>[main.cpp]"]
end

subgraph group_core["Emulator core"]
  node_chip8["Chip-8 state<br/>[chip8.hpp]"]
  node_loader["ROM loader<br/>[chip8.cpp]"]
  node_interpreter["Opcode interpreter<br/>[chip8.cpp]"]
end

subgraph group_io["Runtime I/O"]
  node_video["Display renderer<br/>[main.cpp]"]
  node_beeper["Beeper<br/>[beep.hpp]"]
end

node_user(("ROM user"))
node_rom["ROM file"]
node_raylib["Raylib devices"]

node_user -->|"provides path"| node_loop
node_loop -->|"loads ROM"| node_loader
node_rom -->|"ROM bytes"| node_loader
node_loop -->|"executes cycles"| node_interpreter
node_input -->|"sets key state"| node_chip8
node_loop -->|"polls keys"| node_input
node_loop -->|"renders flagged frame"| node_video
node_chip8 -->|"supplies display"| node_video
node_loop -->|"updates tone state"| node_beeper
node_beeper -->|"uses audio device"| node_raylib
node_video -->|"uses graphics"| node_raylib

click node_loop "https://github.com/benahmed-adam/8chip8/blob/main/src/main.cpp"
click node_input "https://github.com/benahmed-adam/8chip8/blob/main/src/main.cpp"
click node_video "https://github.com/benahmed-adam/8chip8/blob/main/src/main.cpp"
click node_chip8 "https://github.com/benahmed-adam/8chip8/blob/main/src/chip8.hpp"
click node_loader "https://github.com/benahmed-adam/8chip8/blob/main/src/chip8.cpp"
click node_interpreter "https://github.com/benahmed-adam/8chip8/blob/main/src/chip8.cpp"
click node_beeper "https://github.com/benahmed-adam/8chip8/blob/main/src/beep.hpp"

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_loop,node_input,node_user toneBlue
class node_chip8,node_loader,node_interpreter toneAmber
class node_video,node_beeper toneMint
class node_rom,node_raylib toneIndigo
```

## Components

### Runtime app

- [Emulator loop](https://github.com/benahmed-adam/8chip8/blob/main/src/main.cpp): `src/main.cpp`
- [Keyboard input](https://github.com/benahmed-adam/8chip8/blob/main/src/main.cpp): `src/main.cpp`

### Emulator core

- [Chip-8 state](https://github.com/benahmed-adam/8chip8/blob/main/src/chip8.hpp): `src/chip8.hpp`
- [ROM loader](https://github.com/benahmed-adam/8chip8/blob/main/src/chip8.cpp): `src/chip8.cpp`
- [Opcode interpreter](https://github.com/benahmed-adam/8chip8/blob/main/src/chip8.cpp): `src/chip8.cpp`

### Runtime I/O

- [Display renderer](https://github.com/benahmed-adam/8chip8/blob/main/src/main.cpp): `src/main.cpp`
- [Beeper](https://github.com/benahmed-adam/8chip8/blob/main/src/beep.hpp): `src/beep.hpp`

### Other components

- **ROM user**
- **ROM file**
- **Raylib devices**

## Connections

- ROM user → Emulator loop: provides path (evidence: `README.md`)
- Emulator loop → ROM loader: loads ROM (evidence: `src/main.cpp`)
- ROM file → ROM loader: ROM bytes (evidence: `src/chip8.cpp`)
- Emulator loop → Opcode interpreter: executes cycles (evidence: `src/main.cpp`)
- Keyboard input → Chip-8 state: sets key state (evidence: `src/main.cpp`)
- Emulator loop → Keyboard input: polls keys (evidence: `src/main.cpp`)
- Emulator loop → Display renderer: renders flagged frame (evidence: `src/main.cpp`)
- Chip-8 state → Display renderer: supplies display (evidence: `src/main.cpp`)
- Emulator loop → Beeper: updates tone state (evidence: `src/main.cpp`)
- Beeper → Raylib devices: uses audio device (evidence: `src/beep.hpp`)
- Display renderer → Raylib devices: uses graphics (evidence: `src/main.cpp`)
