# starbuck7410/computerproject architecture

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

- Interactive diagram: https://gitdiagram.com/starbuck7410/computerproject
- Repository: https://github.com/starbuck7410/computerproject

## Overview

1. **Overall shape**
   - This repo is a small toolchain plus emulator for a custom ISA called **SIMP**.
   - The main execution flow is: **source program** → **assembler or Brainfuck-to-SIMP translator** → **SIMP simulator/emulator** → optional **interactive X11-based UI**.

2. **Assembler subsystem (`Assembler/`)**
   - This is the standalone assembler for SIMP assembly files.
   - `main.c` is the entry point, with support code in `extras.c` and opcode/lookup-table logic in `luts.c`.
   - The assembler’s responsibility is to turn `.asm` programs into the binary/artifact format that the simulator consumes.

3. **Simulator subsystem (`Simulator/`)**
   - This is the core emulator for the ISA.
   - It is split into CPU-like stages and platform services: `fetch.c`, `decode.c`, `execute_instruction.c`, `execute_disk.c`, `irq2_check.c`, `memory.c`, and `extra.c`.
   - That split suggests a fairly explicit processor model: instruction fetch/decode/execute, memory access, disk/device execution, and interrupt checking.

4. **Hardware-model boundaries inside the simulator**
   - The simulator is not just a generic interpreter; it appears to model separate concerns such as:
     - **instruction flow**,
     - **memory subsystem**,
     - **disk I/O / device behavior**,
     - **interrupt handling**.
   - This is important for architecture diagrams because the simulator behaves like a virtual machine with peripheral/state boundaries rather than a single monolithic loop.

5. **Brainfuck toolchain (`bf-simp/`)**
   - This is a higher-level compiler/translator layer that converts **Brainfuck** programs into SIMP assembly.
   - `main.c`, `instructions.c`, and `functions.h` form the translator/runtime, while `procs.asm` appears to be shared support code emitted or linked into the generated SIMP program.
   - The pipeline here is: **`.bf` input → SIMP assembly output → assembler → simulator**.

6. **Program examples (`assembly-programs/` and `bf-programs/`)**
   - `assembly-programs/` contains several representative SIMP assembly apps: `fib`, `binom`, `mulmat`, `circle`, `terminal`, `disktest`, `test`.
   - `bf-programs/` contains Brainfuck examples such as `calc` and `parrot`.
   - These folders are important because they demonstrate the expected inputs and the kinds of workloads the ISA/emulator is meant to support.

7. **Orchestration scripts at the repo root**
   - The root-level executables/scripts `nass`, `assemble`, `compile`, and `simulate` are the user-facing entry points.
   - From the README, `nass` is the main wrapper: it can assemble and run a program in one step, optionally compile Brainfuck first, and clean generated artifacts.
   - These scripts glue the subsystems together and define the normal developer/runtime flow.

8. **Interactive/runtime environment**
   - The README notes that the updated simulator uses **X11** for interactive parts.
   - This means the runtime is Linux-oriented and includes a graphical/terminal-like emulator experience rather than just batch execution.
   - That GUI boundary belongs to the simulator side, not the assembler.

9. **Documentation and project context**
   - `DOCUMENTATION.md` is the authoritative design document for the custom ISA and emulator behavior.
   - The README indicates the repo evolved from a university assignment into a more complete “interactive emulator” project.
   - For diagramming, the docs likely define the ISA semantics, but the code structure shows the implementation split above.

10. **Data flow summary**
   - **Assembly path:** `.asm` → `Assembler` → simulator input → `Simulator`
   - **Brainfuck path:** `.bf` → `bf-simp` → generated SIMP assembly → `Assembler` → `Simulator`
   - **Program artifacts/examples** sit on the side as inputs and test cases, while the root scripts manage the end-to-end pipeline.

11. **Practical architecture boundary**
   - The repo is essentially two core engines plus a compiler frontend:
     - **Frontend:** assembler and Brainfuck translator
     - **Execution engine:** SIMP simulator with memory/device/interrupt modeling
     - **Samples and tooling:** scripts, example programs, docs
   - The key architectural distinction is between **translation** and **emulation**, with the simulator providing the actual machine behavior.

Main entry points: [`Simulator/main.c`](https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/main.c) (Simulator), [`Assembler/main.c`](https://github.com/starbuck7410/computerproject/blob/interactive/Assembler/main.c) (Assembler), [`bf-simp/main.c`](https://github.com/starbuck7410/computerproject/blob/interactive/bf-simp/main.c) (BF translator), [`nass`](https://github.com/starbuck7410/computerproject/tree/interactive/nass) (nass)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Translation"]
  node_node_assembler_main["Assembler<br/>asm frontend<br/>[main.c]"]
  node_node_assembler_luts["Op tables<br/>opcode tables<br/>[luts.c]"]
  node_node_assembler_extras["Asm utils<br/>assembler helpers<br/>[extras.c]"]
  node_node_bfsimp_main["BF translator<br/>bf frontend<br/>[main.c]"]
  node_node_bfsimp_instr["BF mapping<br/>codegen<br/>[instructions.c]"]
  node_node_bfsimp_procs["Support asm<br/>runtime asm<br/>[procs.asm]"]
end

subgraph group_group_simulator["Emulation"]
  node_node_sim_main["Simulator<br/>vm runtime<br/>[main.c]"]
  node_node_sim_fetch["Fetch<br/>cpu stage<br/>[fetch.c]"]
  node_node_sim_decode["Decode<br/>cpu stage<br/>[decode.c]"]
  node_node_sim_exec["Execute<br/>cpu stage"]
  node_node_sim_disk["Disk I/O<br/>device model<br/>[execute_disk.c]"]
  node_node_sim_irq["Interrupts<br/>irq handling<br/>[irq2_check.c]"]
  node_node_sim_memory["Memory<br/>[memory.c]"]
  node_node_sim_extra["VM helpers<br/>runtime helpers<br/>[extra.c]"]
end

subgraph group_group_samples["Examples"]
  node_node_asm_examples["ASM apps<br/>sample programs"]
  node_node_bf_examples["BF apps<br/>sample programs"]
end

subgraph group_group_root["Scripts"]
  node_node_docs["Docs<br/>[DOCUMENTATION.md]"]
  node_node_nass["nass<br/>orchestrator"]
  node_node_assemble["assemble<br/>script"]
  node_node_compile["compile<br/>script"]
  node_node_simulate["simulate<br/>script"]
end

node_node_bfsimp_main -->|"translates"| node_node_bfsimp_instr
node_node_bfsimp_main -.->|"emits/links"| node_node_bfsimp_procs
node_node_bf_examples -.->|"input"| node_node_bfsimp_main
node_node_bfsimp_main -->|"produces asm"| node_node_assembler_main
node_node_assembler_main -->|"uses"| node_node_assembler_luts
node_node_assembler_main -->|"uses"| node_node_assembler_extras
node_node_asm_examples -.->|"input"| node_node_assembler_main
node_node_assembler_main -->|"produces input for"| node_node_sim_main
node_node_sim_main -->|"drives"| node_node_sim_fetch
node_node_sim_main -->|"drives"| node_node_sim_decode
node_node_sim_main -->|"drives"| node_node_sim_exec
node_node_sim_main -->|"uses"| node_node_sim_memory
node_node_sim_main -->|"uses"| node_node_sim_disk
node_node_sim_main -->|"checks"| node_node_sim_irq
node_node_sim_main -->|"uses"| node_node_sim_extra
node_node_nass -->|"wraps"| node_node_assemble
node_node_nass -->|"wraps"| node_node_compile
node_node_nass -->|"wraps"| node_node_simulate
node_node_assemble -->|"calls"| node_node_assembler_main
node_node_compile -->|"calls"| node_node_bfsimp_main
node_node_simulate -->|"calls"| node_node_sim_main
node_node_docs -.->|"describes"| node_node_nass
node_node_docs -.->|"describes"| node_node_sim_main

click node_node_assembler_main "https://github.com/starbuck7410/computerproject/blob/interactive/Assembler/main.c"
click node_node_assembler_luts "https://github.com/starbuck7410/computerproject/blob/interactive/Assembler/luts.c"
click node_node_assembler_extras "https://github.com/starbuck7410/computerproject/blob/interactive/Assembler/extras.c"
click node_node_bfsimp_main "https://github.com/starbuck7410/computerproject/blob/interactive/bf-simp/main.c"
click node_node_bfsimp_instr "https://github.com/starbuck7410/computerproject/blob/interactive/bf-simp/instructions.c"
click node_node_bfsimp_procs "https://github.com/starbuck7410/computerproject/blob/interactive/bf-simp/procs.asm"
click node_node_sim_main "https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/main.c"
click node_node_sim_fetch "https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/fetch.c"
click node_node_sim_decode "https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/decode.c"
click node_node_sim_exec "https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/execute_instruction.c"
click node_node_sim_disk "https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/execute_disk.c"
click node_node_sim_irq "https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/irq2_check.c"
click node_node_sim_memory "https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/memory.c"
click node_node_sim_extra "https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/extra.c"
click node_node_asm_examples "https://github.com/starbuck7410/computerproject/tree/interactive/assembly-programs"
click node_node_bf_examples "https://github.com/starbuck7410/computerproject/tree/interactive/bf-programs"
click node_node_docs "https://github.com/starbuck7410/computerproject/blob/interactive/DOCUMENTATION.md"
click node_node_nass "https://github.com/starbuck7410/computerproject/tree/interactive/nass"
click node_node_assemble "https://github.com/starbuck7410/computerproject/tree/interactive/assemble"
click node_node_compile "https://github.com/starbuck7410/computerproject/tree/interactive/compile"
click node_node_simulate "https://github.com/starbuck7410/computerproject/tree/interactive/simulate"

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_node_assembler_main,node_node_assembler_luts,node_node_assembler_extras,node_node_bfsimp_main,node_node_bfsimp_instr,node_node_bfsimp_procs toneBlue
class node_node_sim_main,node_node_sim_fetch,node_node_sim_decode,node_node_sim_exec,node_node_sim_disk,node_node_sim_irq,node_node_sim_memory,node_node_sim_extra toneAmber
class node_node_asm_examples,node_node_bf_examples toneMint
class node_node_docs,node_node_nass,node_node_assemble,node_node_compile,node_node_simulate toneRose
```

## Components

### Translation

Assembly and Brainfuck-to-SIMP frontend tools.

- [Assembler](https://github.com/starbuck7410/computerproject/blob/interactive/Assembler/main.c): asm frontend · Entry point for assembling SIMP source programs. · `Assembler/main.c`
- [Op tables](https://github.com/starbuck7410/computerproject/blob/interactive/Assembler/luts.c): opcode tables · Opcode and lookup-table support for the assembler. · `Assembler/luts.c`
- [Asm utils](https://github.com/starbuck7410/computerproject/blob/interactive/Assembler/extras.c): assembler helpers · Auxiliary assembler support routines. · `Assembler/extras.c`
- [BF translator](https://github.com/starbuck7410/computerproject/blob/interactive/bf-simp/main.c): bf frontend · Converts Brainfuck programs into SIMP assembly. · `bf-simp/main.c`
- [BF mapping](https://github.com/starbuck7410/computerproject/blob/interactive/bf-simp/instructions.c): codegen · Brainfuck instruction translation and emission logic. · `bf-simp/instructions.c`
- [Support asm](https://github.com/starbuck7410/computerproject/blob/interactive/bf-simp/procs.asm): runtime asm · Shared SIMP assembly support used by translated Brainfuck programs. · `bf-simp/procs.asm`

### Emulation

SIMP execution engine and machine-state services.

- [Simulator](https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/main.c): vm runtime · Top-level SIMP emulator entry point. · `Simulator/main.c`
- [Fetch](https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/fetch.c): cpu stage · Instruction fetch stage for the virtual CPU. · `Simulator/fetch.c`
- [Decode](https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/decode.c): cpu stage · Instruction decode stage for SIMP execution. · `Simulator/decode.c`
- [Execute](https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/execute_instruction.c): cpu stage · Core instruction execution logic. · `Simulator/execute_instruction.c`
- [Disk I/O](https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/execute_disk.c): device model · Disk and device behavior for the simulator. · `Simulator/execute_disk.c`
- [Interrupts](https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/irq2_check.c): irq handling · IRQ2 and interrupt-condition checking. · `Simulator/irq2_check.c`
- [Memory](https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/memory.c): memory model · Virtual memory subsystem and state access. · `Simulator/memory.c`
- [VM helpers](https://github.com/starbuck7410/computerproject/blob/interactive/Simulator/extra.c): runtime helpers · Additional simulator support routines. · `Simulator/extra.c`

### Examples

Representative SIMP and Brainfuck programs.

- [ASM apps](https://github.com/starbuck7410/computerproject/tree/interactive/assembly-programs): sample programs · Representative SIMP assembly programs such as fib, binom, mulmat, circle, terminal, and disktest. · `assembly-programs`
- [BF apps](https://github.com/starbuck7410/computerproject/tree/interactive/bf-programs): sample programs · Brainfuck example programs such as calc and parrot. · `bf-programs`

### Scripts

Root-level orchestration entry points.

- [Docs](https://github.com/starbuck7410/computerproject/blob/interactive/DOCUMENTATION.md): design docs · Project README and ISA documentation. · `DOCUMENTATION.md`
- [nass](https://github.com/starbuck7410/computerproject/tree/interactive/nass): orchestrator · Main wrapper that assembles, optionally translates Brainfuck, runs, and cleans artifacts. · `nass`
- [assemble](https://github.com/starbuck7410/computerproject/tree/interactive/assemble): script · Script for assembling SIMP source into simulator-ready artifacts. · `assemble`
- [compile](https://github.com/starbuck7410/computerproject/tree/interactive/compile): script · Script for compiling Brainfuck input through the SIMP toolchain. · `compile`
- [simulate](https://github.com/starbuck7410/computerproject/tree/interactive/simulate): script · Script for running the simulator on prepared SIMP artifacts. · `simulate`

## Connections

- BF translator → BF mapping: translates · Brainfuck source is lowered into SIMP assembly through translation rules.
- BF translator → Support asm: emits/links · Generated Brainfuck programs rely on shared SIMP support code.
- BF apps → BF translator: input · Brainfuck sample programs exercise the translator.
- BF translator → Assembler: produces asm · Translator output is passed to the assembler as SIMP source.
- Assembler → Op tables: uses · Assembler relies on opcode and lookup tables.
- Assembler → Asm utils: uses · Assembler entry point depends on helper routines.
- ASM apps → Assembler: input · Assembly examples are direct inputs to the assembler.
- Assembler → Simulator: produces input for · Assembled artifacts are executed by the simulator.
- Simulator → Fetch: drives · The simulator runtime starts with instruction fetch.
- Simulator → Decode: drives · Fetched instructions are decoded by the VM pipeline.
- Simulator → Execute: drives · Decoded instructions flow into the execution engine.
- Simulator → Memory: uses · Execution reads and writes virtual memory state.
- Simulator → Disk I/O: uses · Simulator models disk/device behavior as a separate boundary.
- Simulator → Interrupts: checks · Interrupt conditions are checked during execution.
- Simulator → VM helpers: uses · Additional runtime support is provided by helper routines.
- nass → assemble: wraps · Root wrapper invokes assembly tooling.
- nass → compile: wraps · Root wrapper can compile Brainfuck through the toolchain.
- nass → simulate: wraps · Root wrapper can launch the simulator on generated artifacts.
- assemble → Assembler: calls · Assembly script delegates to the assembler.
- compile → BF translator: calls · Compile script delegates to the Brainfuck translator.
- simulate → Simulator: calls · Simulation script delegates to the emulator.
- Docs → nass: describes · Documentation defines the intended end-to-end workflow.
- Docs → Simulator: describes · Documentation covers the ISA and emulator behavior.
