# ilcde/nandstudio-native architecture

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

- Interactive diagram: https://gitdiagram.com/ilcde/nandstudio-native
- Repository: https://github.com/ilcde/nandstudio-native

## Overview

NandStudio is a native C++/Qt Quick Nand2Tetris workspace. Its main workflow is to edit course files, build or load them into the relevant tool, run a simulator or test script, and inspect results. The graph highlights the GUI coordinator, course-language tools, simulators, workspace storage, and result views. The README documents additional editor and workspace capabilities; sampled excerpts do not expose every Studio-to-tool call, so subsystem links reflect documented workflow rather than uninspected implementation details.

Main entry points: [`src/app/studio.cpp`](https://github.com/ilcde/nandstudio-native/blob/main/src/app/studio.cpp) (Studio coordinator), [`src/script.cpp`](https://github.com/ilcde/nandstudio-native/blob/main/src/script.cpp) (Test script runner), [`src/app/ConsolePane.qml`](https://github.com/ilcde/nandstudio-native/blob/main/src/app/ConsolePane.qml) (Console and inspectors), [`src/app/Main.qml`](https://github.com/ilcde/nandstudio-native/blob/main/src/app/Main.qml) (Qt Quick UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Workspace interface"]
  node_gui["Qt Quick UI<br/>[Main.qml]"]
  node_studio["Studio coordinator<br/>[studio.cpp]"]
  node_editor["Editor services"]
  node_console["Console and inspectors<br/>[ConsolePane.qml]"]
end

subgraph group_languages["Language tools"]
  node_assembler["Assembler and CPU<br/>[core.cpp]"]
  node_jack["Jack compiler<br/>[jack.cpp]"]
  node_vmtranslate["VM translator<br/>[vm_translate.cpp]"]
end

subgraph group_runtime["Simulation runtime"]
  node_hardware["HDL simulator<br/>[hdl.cpp]"]
  node_vm["VM runtime<br/>[vm.cpp]"]
  node_testscript["Test script runner<br/>[script.cpp]"]
end

subgraph group_workspace["Workspace services"]
  node_storage["Workspace storage<br/>[storage.cpp]"]
  node_coursefiles["Course starters<br/>[README.md]"]
end

node_learner(("Learner"))
node_filesystem[("Local and provider storage")]

node_learner -->|"uses"| node_gui
node_gui -->|"dispatches"| node_studio
node_gui -->|"edits with"| node_editor
node_studio -->|"manages workspace"| node_storage
node_storage -->|"reads and writes"| node_filesystem
node_storage -->|"copies starters"| node_coursefiles
node_studio -->|"builds Jack"| node_jack
node_studio -->|"translates VM"| node_vmtranslate
node_studio -->|"builds ASM"| node_assembler
node_studio -->|"loads and evaluates HDL"| node_hardware
node_studio -->|"runs VM"| node_vm
node_studio -->|"runs test scripts"| node_testscript
node_testscript -->|"drives hardware"| node_hardware
node_testscript -->|"drives VM"| node_vm
node_testscript -->|"drives CPU"| node_assembler
node_studio -->|"presents results"| node_console
node_hardware -->|"supplies state"| node_console
node_vm -->|"supplies state"| node_console
node_assembler -->|"supplies state"| node_console

click node_gui "https://github.com/ilcde/nandstudio-native/blob/main/src/app/Main.qml"
click node_studio "https://github.com/ilcde/nandstudio-native/blob/main/src/app/studio.cpp"
click node_editor "https://github.com/ilcde/nandstudio-native/blob/main/src/app/editor_services.cpp"
click node_console "https://github.com/ilcde/nandstudio-native/blob/main/src/app/ConsolePane.qml"
click node_assembler "https://github.com/ilcde/nandstudio-native/blob/main/src/core.cpp"
click node_jack "https://github.com/ilcde/nandstudio-native/blob/main/src/jack.cpp"
click node_vmtranslate "https://github.com/ilcde/nandstudio-native/blob/main/src/vm_translate.cpp"
click node_hardware "https://github.com/ilcde/nandstudio-native/blob/main/src/hdl.cpp"
click node_vm "https://github.com/ilcde/nandstudio-native/blob/main/src/vm.cpp"
click node_testscript "https://github.com/ilcde/nandstudio-native/blob/main/src/script.cpp"
click node_storage "https://github.com/ilcde/nandstudio-native/blob/main/src/app/storage.cpp"
click node_coursefiles "https://github.com/ilcde/nandstudio-native/blob/main/resources/starters/README.md"

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_gui,node_studio,node_editor,node_console toneBlue
class node_assembler,node_jack,node_vmtranslate,node_filesystem toneAmber
class node_hardware,node_vm,node_testscript toneMint
class node_storage,node_coursefiles toneRose
class node_learner toneIndigo
```

## Components

### Workspace interface

- [Qt Quick UI](https://github.com/ilcde/nandstudio-native/blob/main/src/app/Main.qml): `src/app/Main.qml`
- [Studio coordinator](https://github.com/ilcde/nandstudio-native/blob/main/src/app/studio.cpp): `src/app/studio.cpp`
- [Editor services](https://github.com/ilcde/nandstudio-native/blob/main/src/app/editor_services.cpp): `src/app/editor_services.cpp`
- [Console and inspectors](https://github.com/ilcde/nandstudio-native/blob/main/src/app/ConsolePane.qml): `src/app/ConsolePane.qml`

### Language tools

- [Assembler and CPU](https://github.com/ilcde/nandstudio-native/blob/main/src/core.cpp): `src/core.cpp`
- [Jack compiler](https://github.com/ilcde/nandstudio-native/blob/main/src/jack.cpp): `src/jack.cpp`
- [VM translator](https://github.com/ilcde/nandstudio-native/blob/main/src/vm_translate.cpp): `src/vm_translate.cpp`

### Simulation runtime

- [HDL simulator](https://github.com/ilcde/nandstudio-native/blob/main/src/hdl.cpp): `src/hdl.cpp`
- [VM runtime](https://github.com/ilcde/nandstudio-native/blob/main/src/vm.cpp): `src/vm.cpp`
- [Test script runner](https://github.com/ilcde/nandstudio-native/blob/main/src/script.cpp): `src/script.cpp`

### Workspace services

- [Workspace storage](https://github.com/ilcde/nandstudio-native/blob/main/src/app/storage.cpp): `src/app/storage.cpp`
- [Course starters](https://github.com/ilcde/nandstudio-native/blob/main/resources/starters/README.md): `resources/starters/README.md`

### Other components

- **Learner**
- **Local and provider storage**

## Connections

- Learner → Qt Quick UI: uses
- Qt Quick UI → Studio coordinator: dispatches
- Qt Quick UI → Editor services: edits with
- Studio coordinator → Workspace storage: manages workspace
- Workspace storage → Local and provider storage: reads and writes
- Workspace storage → Course starters: copies starters
- Studio coordinator → Jack compiler: builds Jack
- Studio coordinator → VM translator: translates VM
- Studio coordinator → Assembler and CPU: builds ASM
- Studio coordinator → HDL simulator: loads and evaluates HDL
- Studio coordinator → VM runtime: runs VM
- Studio coordinator → Test script runner: runs test scripts
- Test script runner → HDL simulator: drives hardware
- Test script runner → VM runtime: drives VM
- Test script runner → Assembler and CPU: drives CPU
- Studio coordinator → Console and inspectors: presents results
- HDL simulator → Console and inspectors: supplies state
- VM runtime → Console and inspectors: supplies state
- Assembler and CPU → Console and inspectors: supplies state