# frost-phoenix/chip-8 architecture

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

- Interactive diagram: https://gitdiagram.com/frost-phoenix/chip-8
- Repository: https://github.com/frost-phoenix/chip-8

## Overview

##### Project Type and Purpose
- This is a single-binary emulator/interpreter in C for the Chip-8 virtual machine.
- It supports two “frontends” (CLI or GUI), a core CPU+memory interpreter, basic debugger, timers, input handling, and uses Raylib for graphics in GUI mode.

##### Main Components
a. Core Emulator Module (“chip8”)
– Implements the Chip-8 fetch-decode-execute cycle
– Houses memory (4KB), registers (V0–VF), index register, PC, stack, timers
b. Common Utilities (“common”)
– Shared data structures, helper functions (e.g., buffer management)
c. Frontends
– CLI Frontend (“cli”): handles terminal I/O, keyboard mapping, ASCII display
– GUI Frontend (“gui”): uses Raylib to render pixel buffer, handle events, scaling, grid overlay
d. Application Launcher (“main”)
– Parses command-line args, selects CLI vs GUI vs Debug mode, sets IPS, loads ROM file
e. External Dependencies
– Raylib (graphics & input)
– GNU Make / Nix build environment
f. Resources
– ROM loader (reads .ch8 files from rom/ directory)
g. Debugger (in core or CLI mode)

##### Relationships & Data Flow
1. User → main: passes ROM path + options
2. main → common: allocate & initialize Chip-8 state
3. main → rom loader: load binary into memory
4. main → selected frontend (CLI or GUI): enter run loop
5. Frontend → core emulator: each cycle, call chip8_emulate()
6. Core → memory/registers/timers: update state
7. Core → display buffer in common
8. Frontend ← display buffer: render (terminal or Raylib window)
9. Frontend → input subsystem → core (key press/release)
10. Timers (delay & sound) tick at each cycle (part of core loop)
11. Debug mode: CLI monitors opcodes/state for logging or stepping

##### Architectural Patterns & Principles
- Layered Architecture
– Bottom layer: Chip-8 core (pure logic—no I/O calls)
– Middle layer: Common utilities & data structures
– Top layer: Frontends (CLI/GUI) and CLI-only debugger
- Separation of Concerns
– Core logic is decoupled from I/O (easy to add new frontends)
- Modular C Code
– src/chip8.c, src/common.c, src/cli.c, src/gui.c, src/main.c
– include/ headers define module APIs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% System Context
    User["User"]:::external
    User -->|"passes ROM path + options"| Main

    subgraph "Application Launcher"
        Main["Main"]:::io
    end

    Main -->|"allocate & initialize state"| Common
    Main -->|"select frontend/debug mode"| CLI
    Main -->|"select frontend/debug mode"| GUI
    Main -->|"enter debug mode"| Debugger
    Main -->|"load ROM binary"| RomLoader

    subgraph "Resources"
        RomLoader["ROM Loader"]:::io
    end

    RomLoader -->|"binary data"| Memory

    %% Core Layer
    subgraph "Core Emulator Module"
        Core["Chip-8 Core"]:::core
        Memory["Memory (4KB)"]:::storage
        Registers["Registers V0–VF"]:::core
        Index["Index Register"]:::core
        Stack["Stack"]:::core
        Timers["Timers (delay & sound)"]:::core
        FetchDecodeExec["Fetch→Decode→Execute"]:::core
        DisplayBuffer["Display Buffer"]:::storage
    end

    Common["Common Utilities"]:::core

    Core -->|"uses helpers"| Common
    Core -->|"reads/writes"| Memory
    Core -->|"reads/writes"| Registers
    Core -->|"push/pop"| Stack
    Core -->|"update"| Timers
    Core -->|"produce"| DisplayBuffer
    Core -->|"cycle"| FetchDecodeExec
    FetchDecodeExec -->|"tick timers"| Timers

    %% Frontends & Debugger
    subgraph "Frontends"
        CLI["CLI Frontend"]:::io
        GUI["GUI Frontend"]:::io
        Debugger["Debugger"]:::io
    end

    Input["Keyboard Input"]:::external
    Input -->|"key events"| CLI
    Input -->|"key events"| GUI

    CLI -->|"call chip8_emulate() each cycle"| Core
    GUI -->|"call chip8_emulate() each cycle"| Core
    Debugger -->|"monitor state/opcodes"| Core

    CLI -->|"render ASCII buffer"| DisplayBuffer
    GUI -->|"read pixel buffer"| DisplayBuffer

    GUI -->|"render via Raylib"| Raylib
    CLI -->|"output to terminal"| FS

    %% External Dependencies
    subgraph "External Dependencies"
        FS["File System"]:::external
        Raylib["Raylib"]:::external
    end

    %% Build Environment
    subgraph "Build Environment"
        Makefile["Makefile"]:::external
        Nix["default.nix"]:::external
    end

    %% Click Events
    click Core "https://github.com/frost-phoenix/chip-8/blob/main/src/chip8.c"
    click Common "https://github.com/frost-phoenix/chip-8/blob/main/src/common.c"
    click CLI "https://github.com/frost-phoenix/chip-8/blob/main/src/cli.c"
    click GUI "https://github.com/frost-phoenix/chip-8/blob/main/src/gui.c"
    click Main "https://github.com/frost-phoenix/chip-8/blob/main/src/main.c"
    click RomLoader "https://github.com/frost-phoenix/chip-8/tree/main/rom/"
    click Debugger "https://github.com/frost-phoenix/chip-8/blob/main/src/cli.c"
    click Makefile "https://github.com/frost-phoenix/chip-8/tree/main/makefile"
    click Nix "https://github.com/frost-phoenix/chip-8/blob/main/default.nix"

    %% Styles
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef io fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#fbe,stroke:#333,stroke-width:1px
    classDef storage fill:#ffb,stroke:#333,stroke-width:1px
```
