# cr4t3/neodymium architecture

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

- Interactive diagram: https://gitdiagram.com/cr4t3/neodymium
- Repository: https://github.com/cr4t3/neodymium

## Overview

Neodymium is an 8-bit virtual machine. Its user workflow is to launch the executable with a binary program, which validates and loads the file into machine memory before running the CPU. The machine also provides an in-RAM stack and a GLFW-backed virtual screen. The excerpts show the loader, RAM operations, instruction handling, and screen drawing; they do not expose the complete CPU run loop or how it updates the screen, so those links are omitted.

Main entry points: [`src/main.cpp`](https://github.com/cr4t3/neodymium/blob/main/src/main.cpp) (CLI Loader), [`src/modules/cpu.cpp`](https://github.com/cr4t3/neodymium/blob/main/src/modules/cpu.cpp) (CPU), [`src/modules/ram.cpp`](https://github.com/cr4t3/neodymium/blob/main/src/modules/ram.cpp) (RAM), [`src/modules/stack.cpp`](https://github.com/cr4t3/neodymium/blob/main/src/modules/stack.cpp) (In-RAM Stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Program Entry"]
  node_main["CLI Loader<br/>[main.cpp]"]
end

subgraph group_machine["Virtual Machine"]
  node_cpu["CPU<br/>[cpu.cpp]"]
  node_ram[("RAM<br/>[ram.cpp]")]
  node_stack[("In-RAM Stack<br/>[stack.cpp]")]
  node_screen["Virtual Screen<br/>[screen.cpp]"]
end

subgraph group_support["Runtime Support"]
  node_errors["Error Handling<br/>[errors.cpp]"]
  node_casts["Byte Conversions<br/>[casts.cpp]"]
  node_types["VM Types<br/>[def.h]"]
end

node_user(("VM User"))
node_binary["Program Binary"]
node_glfw["GLFW"]

node_user -->|"runs"| node_main
node_binary -->|"provides input"| node_main
node_main -->|"creates"| node_cpu
node_main -->|"loads bytes"| node_ram
node_main -->|"raises errors"| node_errors
node_cpu -->|"reads and writes"| node_ram
node_cpu -->|"pushes and pops"| node_stack
node_cpu -->|"raises errors"| node_errors
node_ram -->|"converts bytes"| node_casts
node_stack -->|"converts bytes"| node_casts
node_screen -->|"uses windowing"| node_glfw

click node_main "https://github.com/cr4t3/neodymium/blob/main/src/main.cpp"
click node_cpu "https://github.com/cr4t3/neodymium/blob/main/src/modules/cpu.cpp"
click node_ram "https://github.com/cr4t3/neodymium/blob/main/src/modules/ram.cpp"
click node_stack "https://github.com/cr4t3/neodymium/blob/main/src/modules/stack.cpp"
click node_screen "https://github.com/cr4t3/neodymium/blob/main/src/modules/screen.cpp"
click node_errors "https://github.com/cr4t3/neodymium/blob/main/src/modules/errors.cpp"
click node_casts "https://github.com/cr4t3/neodymium/blob/main/src/modules/casts.cpp"
click node_types "https://github.com/cr4t3/neodymium/blob/main/src/modules/def.h"

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_main,node_user toneBlue
class node_cpu,node_ram,node_stack,node_screen toneAmber
class node_errors,node_casts,node_types toneMint
class node_binary,node_glfw toneIndigo
```

## Components

### Program Entry

- [CLI Loader](https://github.com/cr4t3/neodymium/blob/main/src/main.cpp): `src/main.cpp`

### Virtual Machine

- [CPU](https://github.com/cr4t3/neodymium/blob/main/src/modules/cpu.cpp): `src/modules/cpu.cpp`
- [RAM](https://github.com/cr4t3/neodymium/blob/main/src/modules/ram.cpp): `src/modules/ram.cpp`
- [In-RAM Stack](https://github.com/cr4t3/neodymium/blob/main/src/modules/stack.cpp): `src/modules/stack.cpp`
- [Virtual Screen](https://github.com/cr4t3/neodymium/blob/main/src/modules/screen.cpp): `src/modules/screen.cpp`

### Runtime Support

- [Error Handling](https://github.com/cr4t3/neodymium/blob/main/src/modules/errors.cpp): `src/modules/errors.cpp`
- [Byte Conversions](https://github.com/cr4t3/neodymium/blob/main/src/modules/casts.cpp): `src/modules/casts.cpp`
- [VM Types](https://github.com/cr4t3/neodymium/blob/main/src/modules/def.h): `src/modules/def.h`

### Other components

- **VM User**
- **Program Binary**
- **GLFW**

## Connections

- VM User → CLI Loader: runs (evidence: `README.MD`)
- Program Binary → CLI Loader: provides input (evidence: `src/main.cpp`)
- CLI Loader → CPU: creates (evidence: `src/main.cpp`)
- CLI Loader → RAM: loads bytes (evidence: `src/main.cpp`)
- CLI Loader → Error Handling: raises errors (evidence: `src/main.cpp`)
- CPU → RAM: reads and writes (evidence: `src/modules/cpu.cpp`)
- CPU → In-RAM Stack: pushes and pops (evidence: `src/modules/cpu.cpp`)
- CPU → Error Handling: raises errors (evidence: `src/modules/cpu.cpp`)
- RAM → Byte Conversions: converts bytes (evidence: `src/modules/ram.cpp`)
- In-RAM Stack → Byte Conversions: converts bytes (evidence: `src/modules/stack.cpp`)
- Virtual Screen → GLFW: uses windowing (evidence: `src/modules/screen.cpp`)
