# omarandlorraine/fake6502 architecture

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

- Interactive diagram: https://gitdiagram.com/omarandlorraine/fake6502
- Repository: https://github.com/omarandlorraine/fake6502

## Overview

##### Project type and purpose
- This is an open‐source C library and test harness that emulates a 6502‐style CPU (with NMOS, 2A03, and added CMOS support).

##### File structure
- Top-level files:
- fake6502.c / fake6502.h – the emulator core
- tests.c – the command-line test harness
- Makefile – build and test targets
- .github/workflows/c-cpp.yml – CI pipeline definition
- No “frontend/backend” split; this is a single library + harness.
- Build targets: compile emulator into an object or static library, link tests, run coverage.

##### README for insights
- Describes core modifications: passing a CPUState pointer for multiple concurrent emulators.
- Notes on supported CPU variants (6502, 2A03, CMOS extension).
- Mentions ~90% test coverage of documented NMOS instructions and the fact that this repo is “dead.”

##### Main components and their interactions
a. Emulator Core Module
- fake6502.c / .h implement:
– CPUState struct (registers, flags, memory pointer)
– Fetch–Decode–Execute loop
– Opcode implementations for each variant (NMOS, 2A03, CMOS)
b. CPU State Abstraction
- A data structure passed into core functions allowing multiple instances
c. Test Harness (tests.c)
- Instantiates one or more CPUState instances
- Loads test vectors, steps the emulator, asserts expected register/memory state
d. Build System & CI
- Makefile targets: “all”, “test”, “coverage”
- GitHub Actions workflow: checkout, build, run tests, collect coverage
e. External Dependencies
- Standard C library only (no third-party libraries)

##### Architectural patterns and design principles
- Modular core + state separation for reentrancy and concurrency
- Data-driven opcode table dispatch in fake6502.c
- Thin harness layer encapsulates test logic and assertions
- Continuous integration ensures regression safety

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs and modules
    subgraph "Emulator Core Module"
        direction TB
        EC["fake6502.c/.h"]:::library
        subgraph "Opcode Dispatch"
            direction TB
            NMOS["NMOS Handlers"]:::library
            A2["2A03 Handlers"]:::library
            CMOS["CMOS Handlers"]:::library
        end
    end

    CS["CPUState Struct\n(fake6502.h)"]:::data
    TH["Test Harness\n(tests.c)"]:::library
    BS["Build System\n(Makefile)"]:::script
    CI["CI Pipeline\n(.github/workflows/c-cpp.yml)"]:::script
    STD["Standard C Library"]:::external

    %% Connections
    TH -->|"invokes step() & loads state"| EC
    EC -->|"reads/writes registers & memory"| CS
    BS -->|"compiles emulator & tests"| EC
    BS -->|"compiles emulator & tests"| TH
    CI -->|"runs Make targets"| BS
    EC -.->|"uses"| STD

    %% Click Events
    click EC "https://github.com/omarandlorraine/fake6502/blob/master/fake6502.c"
    click EC "https://github.com/omarandlorraine/fake6502/blob/master/fake6502.h"
    click CS "https://github.com/omarandlorraine/fake6502/blob/master/fake6502.h"
    click NMOS "https://github.com/omarandlorraine/fake6502/blob/master/fake6502.c"
    click A2 "https://github.com/omarandlorraine/fake6502/blob/master/fake6502.c"
    click CMOS "https://github.com/omarandlorraine/fake6502/blob/master/fake6502.c"
    click TH "https://github.com/omarandlorraine/fake6502/blob/master/tests.c"
    click BS "https://github.com/omarandlorraine/fake6502/tree/master/Makefile"
    click CI "https://github.com/omarandlorraine/fake6502/blob/master/.github/workflows/c-cpp.yml"

    %% Styles
    classDef library fill:#a2d2ff,stroke:#333,stroke-width:1px
    classDef data fill:#caffbf,stroke:#333,stroke-width:1px
    classDef script fill:#ffe066,stroke:#333,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
