# runningbrute/8051-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/runningbrute/8051-simulator
- Repository: https://github.com/runningbrute/8051-simulator

## Overview

This is a learning-oriented Intel 8051 simulator: a user supplies an assembly file, the application assembles it, resets and loads the simulated system, then repeatedly steps the CPU. The tree identifies assembler stages, CPU execution components, instruction modules, and memory/register modules, but their implementations were not sampled, so their internal wiring is omitted. The README documents the CPU-and-memory emulation scope; the only directly evidenced runtime calls are those in `src/main.cpp`.

Main entry points: [`src/main.cpp`](https://github.com/runningbrute/8051-simulator/blob/main/src/main.cpp) (Application Entry), [`src/system.cppm`](https://github.com/runningbrute/8051-simulator/blob/main/src/system.cppm) (Simulated System), [`src/logger.cppm`](https://github.com/runningbrute/8051-simulator/blob/main/src/logger.cppm) (Application Logger), [`src/assembler/assembler.cppm`](https://github.com/runningbrute/8051-simulator/blob/main/src/assembler/assembler.cppm) (Assembler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_entry["Application Entry<br/>[main.cpp]"]
  node_logger["Application Logger<br/>[logger.cppm]"]
end

subgraph group_assembly["Assembly"]
  node_assembler["Assembler<br/>[assembler.cppm]"]
  node_tokenizer["Tokenizer<br/>[tokenizer.cppm]"]
  node_parser["Parser<br/>[parser.cppm]"]
  node_encoder["Encoder<br/>[encoder.cppm]"]
end

subgraph group_execution["CPU Execution"]
  node_cpu["CPU Core<br/>[cpu.cppm]"]
  node_fetcher["Instruction Fetcher<br/>[cpu_fetcher.cppm]"]
  node_dispatcher["Instruction Dispatcher"]
  node_context["CPU Context<br/>[cpu_context.cppm]"]
  node_cpu_alu["CPU ALU<br/>[cpu_alu.cppm]"]
  node_alu_instructions["ALU Instructions<br/>[alu.cppm]"]
  node_data_instructions["Data Instructions<br/>[data.cppm]"]
end

subgraph group_hardware["Hardware State"]
  node_system["Simulated System<br/>[system.cppm]"]
  node_cpu_registers["CPU Registers<br/>[cpu_registers.cppm]"]
  node_memory[("Memory<br/>[memory.cppm]")]
  node_memory_bus["Memory Bus<br/>[memory_bus.cppm]"]
  node_registers["Registers<br/>[registers.cppm]"]
  node_io["I/O<br/>[io.cppm]"]
end

node_user(("Program User"))

node_user -->|"provides program"| node_entry
node_entry -->|"starts logging"| node_logger
node_entry -->|"assembles file"| node_assembler
node_entry -->|"resets and loads"| node_system
node_entry -->|"steps CPU"| node_system

click node_entry "https://github.com/runningbrute/8051-simulator/blob/main/src/main.cpp"
click node_logger "https://github.com/runningbrute/8051-simulator/blob/main/src/logger.cppm"
click node_assembler "https://github.com/runningbrute/8051-simulator/blob/main/src/assembler/assembler.cppm"
click node_tokenizer "https://github.com/runningbrute/8051-simulator/blob/main/src/assembler/tokenizer.cppm"
click node_parser "https://github.com/runningbrute/8051-simulator/blob/main/src/assembler/parser.cppm"
click node_encoder "https://github.com/runningbrute/8051-simulator/blob/main/src/assembler/encoder.cppm"
click node_system "https://github.com/runningbrute/8051-simulator/blob/main/src/system.cppm"
click node_cpu "https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu.cppm"
click node_fetcher "https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu_fetcher.cppm"
click node_dispatcher "https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu_dispatcher.cppm"
click node_context "https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu_context.cppm"
click node_cpu_alu "https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu_alu.cppm"
click node_cpu_registers "https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu_registers.cppm"
click node_alu_instructions "https://github.com/runningbrute/8051-simulator/blob/main/src/instructions/alu.cppm"
click node_data_instructions "https://github.com/runningbrute/8051-simulator/blob/main/src/instructions/data.cppm"
click node_memory "https://github.com/runningbrute/8051-simulator/blob/main/src/memory.cppm"
click node_memory_bus "https://github.com/runningbrute/8051-simulator/blob/main/src/memory_bus.cppm"
click node_registers "https://github.com/runningbrute/8051-simulator/blob/main/src/registers.cppm"
click node_io "https://github.com/runningbrute/8051-simulator/blob/main/src/io.cppm"

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_logger,node_user toneBlue
class node_assembler,node_tokenizer,node_parser,node_encoder toneAmber
class node_cpu,node_fetcher,node_dispatcher,node_context,node_cpu_alu,node_alu_instructions,node_data_instructions toneMint
class node_system,node_cpu_registers,node_memory,node_memory_bus,node_registers,node_io toneRose
```

## Components

### Application

- [Application Entry](https://github.com/runningbrute/8051-simulator/blob/main/src/main.cpp): `src/main.cpp`
- [Application Logger](https://github.com/runningbrute/8051-simulator/blob/main/src/logger.cppm): `src/logger.cppm`

### Assembly

- [Assembler](https://github.com/runningbrute/8051-simulator/blob/main/src/assembler/assembler.cppm): `src/assembler/assembler.cppm`
- [Tokenizer](https://github.com/runningbrute/8051-simulator/blob/main/src/assembler/tokenizer.cppm): `src/assembler/tokenizer.cppm`
- [Parser](https://github.com/runningbrute/8051-simulator/blob/main/src/assembler/parser.cppm): `src/assembler/parser.cppm`
- [Encoder](https://github.com/runningbrute/8051-simulator/blob/main/src/assembler/encoder.cppm): `src/assembler/encoder.cppm`

### CPU Execution

- [CPU Core](https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu.cppm): `src/cpu/cpu.cppm`
- [Instruction Fetcher](https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu_fetcher.cppm): `src/cpu/cpu_fetcher.cppm`
- [Instruction Dispatcher](https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu_dispatcher.cppm): `src/cpu/cpu_dispatcher.cppm`
- [CPU Context](https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu_context.cppm): `src/cpu/cpu_context.cppm`
- [CPU ALU](https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu_alu.cppm): `src/cpu/cpu_alu.cppm`
- [ALU Instructions](https://github.com/runningbrute/8051-simulator/blob/main/src/instructions/alu.cppm): `src/instructions/alu.cppm`
- [Data Instructions](https://github.com/runningbrute/8051-simulator/blob/main/src/instructions/data.cppm): `src/instructions/data.cppm`

### Hardware State

- [Simulated System](https://github.com/runningbrute/8051-simulator/blob/main/src/system.cppm): `src/system.cppm`
- [CPU Registers](https://github.com/runningbrute/8051-simulator/blob/main/src/cpu/cpu_registers.cppm): `src/cpu/cpu_registers.cppm`
- [Memory](https://github.com/runningbrute/8051-simulator/blob/main/src/memory.cppm): `src/memory.cppm`
- [Memory Bus](https://github.com/runningbrute/8051-simulator/blob/main/src/memory_bus.cppm): `src/memory_bus.cppm`
- [Registers](https://github.com/runningbrute/8051-simulator/blob/main/src/registers.cppm): `src/registers.cppm`
- [I/O](https://github.com/runningbrute/8051-simulator/blob/main/src/io.cppm): `src/io.cppm`

### Other components

- **Program User**

## Connections

- Program User → Application Entry: provides program (evidence: `README.md`)
- Application Entry → Application Logger: starts logging (evidence: `src/main.cpp`)
- Application Entry → Assembler: assembles file (evidence: `src/main.cpp`)
- Application Entry → Simulated System: resets and loads (evidence: `src/main.cpp`)
- Application Entry → Simulated System: steps CPU (evidence: `src/main.cpp`)