# luizdepra/r8 architecture

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

- Interactive diagram: https://gitdiagram.com/luizdepra/r8
- Repository: https://github.com/luizdepra/r8

## Overview

##### Project type and purpose
- This is a single‐process, systems‐level project: a CHIP-8 interpreter/emulator implemented in Rust.
- It consists of two crates:
- r8 (the CLI/executable)
- r8lib (the reusable library containing the core emulator logic)

##### File structure
- Top-level: Cargo.toml, Makefile, CI workflows, README, LICENSE.
- r8/
- src/main.rs – entry point and high-level glue
- src/args.rs – command-line parsing
- src/interpreter.rs – orchestrates the run loop
- src/sound.rs – audio back-end
- src/error.rs – error types
- r8lib/
- src/lib.rs – public API (Emulator, Machine)
- src/keyboard.rs – keyboard input abstraction
- src/machine.rs – machine state (memory, registers, stack, timers, display buffer)
- src/operations/… – one file per CHIP-8 opcode handler

##### README
- Confirms: “A simple implementation of a CHIP-8 interpreter made with Rust.”

##### Main components and their interactions
a. CLI Layer (r8 crate)
– Arg parser → configuration (ROM path, speed, debug flags)
– Instantiates Emulator from r8lib
– Delegates to Interpreter.run() loop
b. Interpreter Loop (r8/src/interpreter.rs)
– Repeatedly: fetch opcode from Machine.memory → dispatch to appropriate op handler → update timers → poll keyboard → render display → emit sound events
c. Core Emulator (r8lib)
– Machine: holds registers, memory, stack, display buffer, delay/sound timers
– Keyboard: exposes current key state to Machine
– Operations module: one dispatcher that calls individual opcode implementations
– Sound: triggered when sound timer > 0 (hooks into r8/src/sound.rs)
d. External Dependencies
– CLI arguments: structopt/clap (in args.rs)
– Terminal or SDL2 for rendering? (not shown in tree; if present, include it)
– Rust standard library

##### Architectural patterns and design principles
- Separation of concerns: CLI vs core logic
- Modular opcode handlers (each opcode lives in its own file)
- Clear library API (r8lib) suitable for embedding in other Rust projects
- Single‐threaded event loop emulating CPU cycles

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Executable Crate
    subgraph "r8 (Executable CLI Crate)"
        direction TB
        ArgParser["Arg Parser"]:::cli
        ErrorDefs["Error Definitions"]:::cli
        Main["Main Entry Point"]:::cli
        Interpreter["Interpreter Loop"]:::core
        SoundInterface["Sound Interface"]:::io
    end

    %% Emulator Library Crate
    subgraph "r8lib (Reusable Emulator Library)"
        direction TB
        PublicAPI["Public API"]:::core
        Machine["Machine State"]:::core
        Keyboard["Keyboard Abstraction"]:::io
        OpsDispatcher["Operations Dispatcher"]:::core
        subgraph "Opcode Handlers"
            direction TB
            Op00e0["Clear Display (00E0)"]:::core
            Op00ee["Return from Subroutine (00EE)"]:::core
            Op1nnn["Jump (1nnn)"]:::core
            Op2nnn["Call Subroutine (2nnn)"]:::core
            Op3xkk["Skip if Equal (3xkk)"]:::core
            Op4xkk["Skip if Not Equal (4xkk)"]:::core
            Op5xy0["Skip if Registers Equal (5xy0)"]:::core
            Op6xkk["Set Register (6xkk)"]:::core
            Op7xkk["Add to Register (7xkk)"]:::core
            Op8xy0["Register Ops (8xy0–8xye)"]:::core
            Op9xy0["Skip if Registers Not Equal (9xy0)"]:::core
            OpAnnn["Set I Register (Annn)"]:::core
            OpBnnn["Jump with Offset (Bnnn)"]:::core
            OpCxkk["Random & Mask (Cxkk)"]:::core
            OpDxyn["Draw Sprite (Dxyn)"]:::core
            Opex9e["Skip if Key Pressed (Ex9E)"]:::core
            Opexa1["Skip if Not Pressed (ExA1)"]:::core
            OpFx07["Get Delay Timer (Fx07)"]:::core
            OpFx15["Set Delay Timer (Fx15)"]:::core
            OpFx18["Set Sound Timer (Fx18)"]:::core
            OpFx1e["Add I Register (Fx1E)"]:::core
            OpFx29["Set I to Sprite (Fx29)"]:::core
            OpFx33["Binary Coded Decimal (Fx33)"]:::core
            OpFx55["Store Registers (Fx55)"]:::core
            OpFx65["Load Registers (Fx65)"]:::core
            OpInvalid["Invalid Opcode Handler"]:::core
        end
    end

    %% Relationships
    ArgParser -->|"config"| Main
    Main -->|"start"| Interpreter
    Main -->|"Emulator API"| PublicAPI
    Interpreter -->|"fetch_opcode()"| Machine
    Interpreter -->|"poll()"| Keyboard
    Interpreter -->|"play_sound"| SoundInterface
    Interpreter -->|"invoke"| OpsDispatcher
    Machine -->|"decode"| OpsDispatcher
    OpsDispatcher -->|"calls"| Op00e0
    OpsDispatcher -->|"calls"| Op00ee
    OpsDispatcher -->|"calls"| Op1nnn
    OpsDispatcher -->|"calls"| Op2nnn
    OpsDispatcher -->|"calls"| Op3xkk
    OpsDispatcher -->|"calls"| Op4xkk
    OpsDispatcher -->|"calls"| Op5xy0
    OpsDispatcher -->|"calls"| Op6xkk
    OpsDispatcher -->|"calls"| Op7xkk
    OpsDispatcher -->|"calls"| Op8xy0
    OpsDispatcher -->|"calls"| Op9xy0
    OpsDispatcher -->|"calls"| OpAnnn
    OpsDispatcher -->|"calls"| OpBnnn
    OpsDispatcher -->|"calls"| OpCxkk
    OpsDispatcher -->|"calls"| OpDxyn
    OpsDispatcher -->|"calls"| Opex9e
    OpsDispatcher -->|"calls"| Opexa1
    OpsDispatcher -->|"calls"| OpFx07
    OpsDispatcher -->|"calls"| OpFx15
    OpsDispatcher -->|"calls"| OpFx18
    OpsDispatcher -->|"calls"| OpFx1e
    OpsDispatcher -->|"calls"| OpFx29
    OpsDispatcher -->|"calls"| OpFx33
    OpsDispatcher -->|"calls"| OpFx55
    OpsDispatcher -->|"calls"| OpFx65
    OpsDispatcher -->|"calls"| OpInvalid
    Op00e0 -->|"mutate"| Machine
    Op00ee -->|"mutate"| Machine
    %% ... similar machine return arrows omitted for brevity
    classDef cli fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef core fill:#a2d0f5,stroke:#333,stroke-width:1px
    classDef io fill:#f5d0a2,stroke:#333,stroke-width:1px

    %% Click Events
    click ArgParser "https://github.com/luizdepra/r8/blob/main/r8/src/args.rs"
    click ErrorDefs "https://github.com/luizdepra/r8/blob/main/r8/src/error.rs"
    click Main "https://github.com/luizdepra/r8/blob/main/r8/src/main.rs"
    click Interpreter "https://github.com/luizdepra/r8/blob/main/r8/src/interpreter.rs"
    click SoundInterface "https://github.com/luizdepra/r8/blob/main/r8/src/sound.rs"
    click PublicAPI "https://github.com/luizdepra/r8/blob/main/r8lib/src/lib.rs"
    click Machine "https://github.com/luizdepra/r8/blob/main/r8lib/src/machine.rs"
    click Keyboard "https://github.com/luizdepra/r8/blob/main/r8lib/src/keyboard.rs"
    click OpsDispatcher "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/mod.rs"
    click Op00e0 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/op00e0.rs"
    click Op00ee "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/op00ee.rs"
    click Op1nnn "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/op1nnn.rs"
    click Op2nnn "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/op2nnn.rs"
    click Op3xkk "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/op3xkk.rs"
    click Op4xkk "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/op4xkk.rs"
    click Op5xy0 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/op5xy0.rs"
    click Op6xkk "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/op6xkk.rs"
    click Op7xkk "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/op7xkk.rs"
    click Op8xy0 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/op8xy0.rs"
    click Op9xy0 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/op9xy0.rs"
    click OpAnnn "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opannn.rs"
    click OpBnnn "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opbnnn.rs"
    click OpCxkk "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opcxkk.rs"
    click OpDxyn "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opdxyn.rs"
    click Opex9e "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opex9e.rs"
    click Opexa1 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opexa1.rs"
    click OpFx07 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opfx07.rs"
    click OpFx15 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opfx15.rs"
    click OpFx18 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opfx18.rs"
    click OpFx1e "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opfx1e.rs"
    click OpFx29 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opfx29.rs"
    click OpFx33 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opfx33.rs"
    click OpFx55 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opfx55.rs"
    click OpFx65 "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opfx65.rs"
    click OpInvalid "https://github.com/luizdepra/r8/blob/main/r8lib/src/operations/opinvalid.rs"
```
