# rck1439/c8emu architecture

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

- Interactive diagram: https://gitdiagram.com/rck1439/c8emu
- Repository: https://github.com/rck1439/c8emu

## Overview

c8emu is a desktop Chip-8 interpreter. The user supplies a ROM, then the client runs an event/update/render loop: Chip8 coordinates ROM loading, emulation, keypad input and drawing; the renderer presents the display and optional debug overlay. CPU execution, RAM, ROM, and call-stack responsibilities are shown separately. The README documents the QWER keypad mapping and F3 overlay. Some subsystem links rely on source-index references or README statements because not all implementation excerpts were provided.

Main entry points: [`src/Emulator/Chip8.cpp`](https://github.com/rck1439/c8emu/blob/main/src/Emulator/Chip8.cpp) (Chip-8 coordinator), [`src/Emulator/CPU.cpp`](https://github.com/rck1439/c8emu/blob/main/src/Emulator/CPU.cpp) (CPU execution), [`src/Client/Client.cpp`](https://github.com/rck1439/c8emu/blob/main/src/Client/Client.cpp) (Client loop), [`src/Renderer/Renderer.cpp`](https://github.com/rck1439/c8emu/blob/main/src/Renderer/Renderer.cpp) (Renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop client"]
  node_entry["Application entry<br/>[EntryPoint.cpp]"]
  node_client["Client loop<br/>[Client.cpp]"]
  node_config["Window configuration<br/>[Config.hpp]"]
end

subgraph group_emu["Chip-8 emulation"]
  node_chip8["Chip-8 coordinator<br/>[Chip8.cpp]"]
  node_rom["ROM loader<br/>[ROM.cpp]"]
  node_ram[("Memory and font<br/>[RAM.hpp]")]
  node_cpu["CPU execution<br/>[CPU.cpp]"]
  node_instructions["Opcode definitions<br/>[Instructions.cpp]"]
  node_callstack[("Call stack<br/>[CallStack.cpp]")]
  node_keyboard["Keypad mapping<br/>[Keyboard.hpp]"]
  node_spec["Chip-8 specification<br/>[Spec.hpp]"]
end

subgraph group_render["Display and diagnostics"]
  node_renderer["Renderer<br/>[Renderer.cpp]"]
  node_overlay["Debug overlay<br/>[DebugOverlay.hpp]"]
end

subgraph group_foundation["Core support"]
  node_buffer["Byte buffer<br/>[Buffer.hpp]"]
  node_font["Overlay font data"]
  node_random["Random values<br/>[Random.hpp]"]
  node_debug["Logging and errors<br/>[Debug.hpp]"]
  node_types["Shared types<br/>[Types.hpp]"]
end

node_user(("ROM user"))
node_sfml["SFML"]

node_user -->|"starts with ROM"| node_entry
node_entry -->|"creates"| node_client
node_client -->|"uses settings"| node_config
node_client -->|"loads and updates"| node_chip8
node_client -->|"initializes and draws"| node_renderer
node_client -->|"handles window events"| node_sfml
node_chip8 -->|"loads ROM"| node_rom
node_chip8 -->|"updates CPU"| node_cpu
node_chip8 -->|"owns memory"| node_ram
node_chip8 -->|"maps key events"| node_keyboard
node_chip8 -->|"draws display"| node_renderer
node_cpu -->|"reads and writes"| node_ram
node_cpu -->|"dispatches opcodes"| node_instructions
node_cpu -->|"uses stack"| node_callstack
node_cpu -->|"generates random values"| node_random
node_ram -->|"loads ROM data"| node_rom
node_rom -->|"stores bytes"| node_buffer
node_renderer -->|"renders overlay"| node_overlay
node_renderer -->|"uses font data"| node_font
node_renderer -->|"renders graphics"| node_sfml
node_cpu -->|"uses constants"| node_spec
node_ram -->|"uses memory layout"| node_spec
node_debug -->|"uses types"| node_types

click node_entry "https://github.com/rck1439/c8emu/blob/main/src/EntryPoint.cpp"
click node_client "https://github.com/rck1439/c8emu/blob/main/src/Client/Client.cpp"
click node_config "https://github.com/rck1439/c8emu/blob/main/src/Client/Config.hpp"
click node_chip8 "https://github.com/rck1439/c8emu/blob/main/src/Emulator/Chip8.cpp"
click node_rom "https://github.com/rck1439/c8emu/blob/main/src/Emulator/ROM.cpp"
click node_ram "https://github.com/rck1439/c8emu/blob/main/src/Emulator/RAM.hpp"
click node_cpu "https://github.com/rck1439/c8emu/blob/main/src/Emulator/CPU.cpp"
click node_instructions "https://github.com/rck1439/c8emu/blob/main/src/Emulator/Instructions.cpp"
click node_callstack "https://github.com/rck1439/c8emu/blob/main/src/Emulator/CallStack.cpp"
click node_keyboard "https://github.com/rck1439/c8emu/blob/main/src/Emulator/Keyboard.hpp"
click node_spec "https://github.com/rck1439/c8emu/blob/main/src/Emulator/Spec.hpp"
click node_renderer "https://github.com/rck1439/c8emu/blob/main/src/Renderer/Renderer.cpp"
click node_overlay "https://github.com/rck1439/c8emu/blob/main/src/Renderer/DebugOverlay.hpp"
click node_buffer "https://github.com/rck1439/c8emu/blob/main/src/Core/Buffer.hpp"
click node_font "https://github.com/rck1439/c8emu/blob/main/src/Core/NintendoNESFont.hpp"
click node_random "https://github.com/rck1439/c8emu/blob/main/src/Core/Random.hpp"
click node_debug "https://github.com/rck1439/c8emu/blob/main/src/Core/Debug.hpp"
click node_types "https://github.com/rck1439/c8emu/blob/main/src/Core/Types.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_entry,node_client,node_config,node_user toneBlue
class node_chip8,node_rom,node_ram,node_cpu,node_instructions,node_callstack,node_keyboard,node_spec toneAmber
class node_renderer,node_overlay toneMint
class node_buffer,node_font,node_random,node_debug,node_types toneRose
class node_sfml toneIndigo
```

## Components

### Desktop client

- [Application entry](https://github.com/rck1439/c8emu/blob/main/src/EntryPoint.cpp): `src/EntryPoint.cpp`
- [Client loop](https://github.com/rck1439/c8emu/blob/main/src/Client/Client.cpp): `src/Client/Client.cpp`
- [Window configuration](https://github.com/rck1439/c8emu/blob/main/src/Client/Config.hpp): `src/Client/Config.hpp`

### Chip-8 emulation

- [Chip-8 coordinator](https://github.com/rck1439/c8emu/blob/main/src/Emulator/Chip8.cpp): `src/Emulator/Chip8.cpp`
- [ROM loader](https://github.com/rck1439/c8emu/blob/main/src/Emulator/ROM.cpp): `src/Emulator/ROM.cpp`
- [Memory and font](https://github.com/rck1439/c8emu/blob/main/src/Emulator/RAM.hpp): `src/Emulator/RAM.hpp`
- [CPU execution](https://github.com/rck1439/c8emu/blob/main/src/Emulator/CPU.cpp): `src/Emulator/CPU.cpp`
- [Opcode definitions](https://github.com/rck1439/c8emu/blob/main/src/Emulator/Instructions.cpp): `src/Emulator/Instructions.cpp`
- [Call stack](https://github.com/rck1439/c8emu/blob/main/src/Emulator/CallStack.cpp): `src/Emulator/CallStack.cpp`
- [Keypad mapping](https://github.com/rck1439/c8emu/blob/main/src/Emulator/Keyboard.hpp): `src/Emulator/Keyboard.hpp`
- [Chip-8 specification](https://github.com/rck1439/c8emu/blob/main/src/Emulator/Spec.hpp): `src/Emulator/Spec.hpp`

### Display and diagnostics

- [Renderer](https://github.com/rck1439/c8emu/blob/main/src/Renderer/Renderer.cpp): `src/Renderer/Renderer.cpp`
- [Debug overlay](https://github.com/rck1439/c8emu/blob/main/src/Renderer/DebugOverlay.hpp): `src/Renderer/DebugOverlay.hpp`

### Core support

- [Byte buffer](https://github.com/rck1439/c8emu/blob/main/src/Core/Buffer.hpp): `src/Core/Buffer.hpp`
- [Overlay font data](https://github.com/rck1439/c8emu/blob/main/src/Core/NintendoNESFont.hpp): `src/Core/NintendoNESFont.hpp`
- [Random values](https://github.com/rck1439/c8emu/blob/main/src/Core/Random.hpp): `src/Core/Random.hpp`
- [Logging and errors](https://github.com/rck1439/c8emu/blob/main/src/Core/Debug.hpp): `src/Core/Debug.hpp`
- [Shared types](https://github.com/rck1439/c8emu/blob/main/src/Core/Types.hpp): `src/Core/Types.hpp`

### Other components

- **ROM user**
- **SFML**

## Connections

- ROM user → Application entry: starts with ROM (evidence: `README.md`)
- Application entry → Client loop: creates (evidence: `src/EntryPoint.cpp`)
- Client loop → Window configuration: uses settings (evidence: `src/Client/Client.cpp`)
- Client loop → Chip-8 coordinator: loads and updates (evidence: `src/Client/Client.cpp`)
- Client loop → Renderer: initializes and draws (evidence: `src/Client/Client.cpp`)
- Client loop → SFML: handles window events (evidence: `src/Client/Client.cpp`)
- Chip-8 coordinator → ROM loader: loads ROM (evidence: `src/Emulator/Chip8.cpp`)
- Chip-8 coordinator → CPU execution: updates CPU
- Chip-8 coordinator → Memory and font: owns memory
- Chip-8 coordinator → Keypad mapping: maps key events (evidence: `src/Emulator/Chip8.cpp`)
- Chip-8 coordinator → Renderer: draws display (evidence: `src/Emulator/Chip8.cpp`)
- CPU execution → Memory and font: reads and writes (evidence: `src/Emulator/CPU.cpp`)
- CPU execution → Opcode definitions: dispatches opcodes (evidence: `src/Emulator/CPU.cpp`)
- CPU execution → Call stack: uses stack
- CPU execution → Random values: generates random values (evidence: `src/Emulator/CPU.cpp`)
- Memory and font → ROM loader: loads ROM data
- ROM loader → Byte buffer: stores bytes
- Renderer → Debug overlay: renders overlay
- Renderer → Overlay font data: uses font data (evidence: `src/Renderer/Renderer.cpp`)
- Renderer → SFML: renders graphics
- CPU execution → Chip-8 specification: uses constants
- Memory and font → Chip-8 specification: uses memory layout (evidence: `src/Emulator/RAM.hpp`)
- Logging and errors → Shared types: uses types (evidence: `src/Core/Debug.hpp`)
