# pxlman/vole-machine-simulator architecture

> Architecture diagram of the GitHub repository pxlman/vole-machine-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pxlman/vole-machine-simulator
- Repository: https://github.com/pxlman/vole-machine-simulator

## Overview

##### Project type and purpose
- This is a desktop application written in C++/Qt6 – a graphical, interactive “vole machine” (educational CPU) simulator.
- The README confirms it’s a monolithic Qt GUI program that models CPU internals (ALU, CU, registers, memory) and exposes them in a MainWindow.

##### File structure
- Top‐level Qt project file (vole.pro), qmake build system, main.cpp, and a “machine” folder of core classes.
- “machine/” contains ALU.h, CPU.h, CU.h, Machine.h, Memory.h, Register.h.
- UI files: mainwindow.ui, mainwindow.h/.cpp, resources.qrc, stylesheet.qss.
- Utility headers: MainMachine.h (likely a facade), UiFunctions.h.
- Images folder and run script (for launching).

##### README for additional insights
- Core features: load instructions, step/auto-run, view PC/IR, registers, memory, ASCII output, tooltips, speed control.

a. Main components
- UI Layer (Qt MainWindow + .ui + stylesheet + resources)
- Controller/Facade (MainMachine, UiFunctions)
- Machine Core (Machine class orchestrating CPU, CU, ALU, Memory, Register)
- Data Stores (Memory array, Register file)
- File I/O Module (instruction loader)
b. Relationships & interactions
- User clicks or menu actions → Qt signals/slots → Controller (MainMachine)
- Controller invokes Machine::loadProgram() or Machine::step()/runAll()
- Machine coordinates:
- CU decodes IR → CU tells ALU/Memory/Registers what to do
- ALU executes arithmetic/logical operations
- Memory/Registers updated accordingly
- Machine updates PC, IR
- After each step/update → signals back to UI to refresh tables, PC/IR display, ASCII output
c. Architectural patterns & principles
- MVC-style separation: Qt UI (View) ↔ MainMachine (Controller) ↔ Machine Core (Model)
- Single-process, event-driven via Qt’s signals/slots
- Modular hardware components (each in its own class) for clarity and testability
d. Key technologies & frameworks
- C++17, Qt6 (Widgets), qmake build
- .ui XML for layout, resources.qrc for bundling images/styles
- QTableView or custom widgets for memory/register display

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Entry
    subgraph "Application Entry"
        MainCPP["main.cpp"] 
        ProFile["vole.pro"] 
        RunScript["run"]
    end

    %% UI Layer
    subgraph "UI Layer"
        MainWindowUI["mainwindow.ui"]
        MainWindowH["mainwindow.h"]
        MainWindowCPP["mainwindow.cpp"]
        Stylesheet["stylesheet.qss"]
        Resources["resources.qrc"]
        Images["images/"]
    end

    %% Controller/Facade
    subgraph "Controller/Facade"
        MainMachine["MainMachine"]
        UiFunctions["UiFunctions"]
    end

    %% File I/O Module
    FileIO["File I/O\n(instruction loader)"]

    %% Machine Core
    subgraph "Machine Core"
        Machine["Machine"]
        CPU["CPU"]
        CU["CU"]
        ALU["ALU"]
        Memory["Memory"]
        Register["Register"]
    end

    %% UI updates
    subgraph "UI Update Loop"
        UIUpdate["UI Refresh\n(signals/slots)"]
    end

    %% Relationships
    MainCPP -->|"launches"| MainWindowCPP
    MainWindowCPP -->|"loads UI"| MainWindowUI
    MainWindowCPP -->|"applies stylesheet"| Stylesheet
    MainWindowCPP -->|"loads resources"| Resources

    MainWindowCPP -->|"user actions"| MainMachine
    MainMachine -->|"invoke loadProgram()"| Machine
    MainMachine -->|"invoke step()/runAll()"| Machine

    FileIO -->|"load instructions"| Machine

    Machine -->|"fetch/decode"| CPU
    CPU -->|"decode logic"| CU
    CU -->|"execute op"| ALU
    CU -->|"read/write"| Memory
    CU -->|"read/write"| Register
    ALU -->|"results"| Register

    Machine -->|"update PC/IR"| UIUpdate
    UIUpdate -->|"refresh views"| MainWindowCPP

    MainMachine -->|"update UI"| UiFunctions
    UiFunctions -->|"emit signals"| UIUpdate

    %% Click Events
    click MainWindowUI "https://github.com/pxlman/vole-machine-simulator/blob/main/mainwindow.ui"
    click MainWindowH "https://github.com/pxlman/vole-machine-simulator/blob/main/mainwindow.h"
    click MainWindowCPP "https://github.com/pxlman/vole-machine-simulator/blob/main/mainwindow.cpp"
    click Stylesheet "https://github.com/pxlman/vole-machine-simulator/blob/main/stylesheet.qss"
    click Resources "https://github.com/pxlman/vole-machine-simulator/blob/main/resources.qrc"
    click Images "https://github.com/pxlman/vole-machine-simulator/tree/main/images/"
    click MainMachine "https://github.com/pxlman/vole-machine-simulator/blob/main/MainMachine.h"
    click UiFunctions "https://github.com/pxlman/vole-machine-simulator/blob/main/UiFunctions.h"
    click MainCPP "https://github.com/pxlman/vole-machine-simulator/blob/main/main.cpp"
    click ProFile "https://github.com/pxlman/vole-machine-simulator/blob/main/vole.pro"
    click RunScript "https://github.com/pxlman/vole-machine-simulator/tree/main/run"
    click Machine "https://github.com/pxlman/vole-machine-simulator/blob/main/machine/Machine.h"
    click CU "https://github.com/pxlman/vole-machine-simulator/blob/main/machine/CU.h"
    click ALU "https://github.com/pxlman/vole-machine-simulator/blob/main/machine/ALU.h"
    click CPU "https://github.com/pxlman/vole-machine-simulator/blob/main/machine/CPU.h"
    click Memory "https://github.com/pxlman/vole-machine-simulator/blob/main/machine/Memory.h"
    click Register "https://github.com/pxlman/vole-machine-simulator/blob/main/machine/Register.h"

    %% Styles
    classDef application fill:#F0F8FF,stroke:#333,stroke-width:1px
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef controller fill:#90EE90,stroke:#333,stroke-width:1px
    classDef core fill:#FFA500,stroke:#333,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external stroke-dasharray: 5 5,stroke:#333,fill:none

    class MainCPP,ProFile,RunScript application
    class MainWindowUI,MainWindowH,MainWindowCPP,Stylesheet,Resources,Images ui
    class MainMachine,UiFunctions controller
    class Machine,CPU,CU,ALU core
    class Memory,Register storage
    class FileIO external
```
