# 0xc-dev/stackemulator architecture

> Architecture diagram of the GitHub repository 0xc-dev/stackemulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0xc-dev/stackemulator
- Repository: https://github.com/0xc-dev/stackemulator

## Overview

StackEmulate is an interactive x86-64 assembly learning TUI. A learner edits or loads source, assembles it, then steps, reverses, or runs the code in an isolated CPU emulator while inspecting code, registers, and stack state. The README also documents bundled example cycling and file open/save. The sampled code supports the main assembly and execution links; some UI refresh and file-action details are omitted, so those links are grounded in the README or visible app wiring.

Main entry points: [`stackemu/app.py`](https://github.com/0xc-dev/stackemulator/blob/main/stackemu/app.py) (TUI controller), [`stackemu/assembler.py`](https://github.com/0xc-dev/stackemulator/blob/main/stackemu/assembler.py) (Assembler), [`stackemu/emulator.py`](https://github.com/0xc-dev/stackemulator/blob/main/stackemu/emulator.py) (CPU emulator), [`stackemu/asm_editor.py`](https://github.com/0xc-dev/stackemulator/blob/main/stackemu/asm_editor.py) (Assembly editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Source input"]
  node_app["TUI controller<br/>[app.py]"]
  node_editor["Assembly editor<br/>[asm_editor.py]"]
  node_source_files["Assembly files"]
end

subgraph group_assembly["Assembly"]
  node_assembler["Assembler<br/>[assembler.py]"]
  node_keystone["Keystone"]
  node_capstone["Capstone"]
end

subgraph group_execution["Execution"]
  node_emulator["CPU emulator<br/>[emulator.py]"]
  node_unicorn["Unicorn engine"]
end

subgraph group_views["Visualizers"]
  node_code_view["Code view<br/>[widgets.py]"]
  node_register_view["Register view<br/>[widgets.py]"]
  node_stack_view["Stack view<br/>[widgets.py]"]
end

node_learner(("Learner"))

node_learner -->|"uses controls"| node_app
node_app -->|"shows editor"| node_editor
node_app -->|"loads examples"| node_source_files
node_app -->|"assembles source"| node_assembler
node_editor -->|"detects syntax"| node_assembler
node_assembler -->|"encodes instructions"| node_keystone
node_assembler -->|"maps instructions"| node_capstone
node_assembler -->|"uses code base"| node_emulator
node_app -->|"loads and controls"| node_emulator
node_emulator -->|"executes code"| node_unicorn
node_app -->|"updates display"| node_code_view
node_app -->|"composes pane"| node_register_view
node_app -->|"composes pane"| node_stack_view
node_code_view -->|"uses line map"| node_assembler
node_stack_view -->|"renders snapshots"| node_emulator
node_register_view -->|"renders snapshots"| node_emulator

click node_app "https://github.com/0xc-dev/stackemulator/blob/main/stackemu/app.py"
click node_editor "https://github.com/0xc-dev/stackemulator/blob/main/stackemu/asm_editor.py"
click node_source_files "https://github.com/0xc-dev/stackemulator/tree/main/examples"
click node_assembler "https://github.com/0xc-dev/stackemulator/blob/main/stackemu/assembler.py"
click node_emulator "https://github.com/0xc-dev/stackemulator/blob/main/stackemu/emulator.py"
click node_code_view "https://github.com/0xc-dev/stackemulator/blob/main/stackemu/widgets.py"
click node_register_view "https://github.com/0xc-dev/stackemulator/blob/main/stackemu/widgets.py"
click node_stack_view "https://github.com/0xc-dev/stackemulator/blob/main/stackemu/widgets.py"

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_app,node_editor,node_source_files toneBlue
class node_assembler,node_keystone,node_capstone toneAmber
class node_emulator,node_unicorn toneMint
class node_code_view,node_register_view,node_stack_view toneRose
class node_learner toneIndigo
```

## Components

### Source input

- [TUI controller](https://github.com/0xc-dev/stackemulator/blob/main/stackemu/app.py): `stackemu/app.py`
- [Assembly editor](https://github.com/0xc-dev/stackemulator/blob/main/stackemu/asm_editor.py): `stackemu/asm_editor.py`
- [Assembly files](https://github.com/0xc-dev/stackemulator/tree/main/examples): `examples`

### Assembly

- [Assembler](https://github.com/0xc-dev/stackemulator/blob/main/stackemu/assembler.py): `stackemu/assembler.py`
- **Keystone**
- **Capstone**

### Execution

- [CPU emulator](https://github.com/0xc-dev/stackemulator/blob/main/stackemu/emulator.py): `stackemu/emulator.py`
- **Unicorn engine**

### Visualizers

- [Code view](https://github.com/0xc-dev/stackemulator/blob/main/stackemu/widgets.py): `stackemu/widgets.py`
- [Register view](https://github.com/0xc-dev/stackemulator/blob/main/stackemu/widgets.py): `stackemu/widgets.py`
- [Stack view](https://github.com/0xc-dev/stackemulator/blob/main/stackemu/widgets.py): `stackemu/widgets.py`

### Other components

- **Learner**

## Connections

- Learner → TUI controller: uses controls (evidence: `README.md`)
- TUI controller → Assembly editor: shows editor (evidence: `stackemu/app.py`)
- TUI controller → Assembly files: loads examples (evidence: `stackemu/app.py`)
- TUI controller → Assembler: assembles source (evidence: `stackemu/app.py`)
- Assembly editor → Assembler: detects syntax (evidence: `stackemu/asm_editor.py`)
- Assembler → Keystone: encodes instructions (evidence: `stackemu/assembler.py`)
- Assembler → Capstone: maps instructions (evidence: `stackemu/assembler.py`)
- Assembler → CPU emulator: uses code base (evidence: `stackemu/assembler.py`)
- TUI controller → CPU emulator: loads and controls (evidence: `stackemu/app.py`)
- CPU emulator → Unicorn engine: executes code (evidence: `stackemu/emulator.py`)
- TUI controller → Code view: updates display (evidence: `stackemu/app.py`)
- TUI controller → Register view: composes pane (evidence: `stackemu/app.py`)
- TUI controller → Stack view: composes pane (evidence: `stackemu/app.py`)
- Code view → Assembler: uses line map (evidence: `stackemu/widgets.py`)
- Stack view → CPU emulator: renders snapshots (evidence: `stackemu/widgets.py`)
- Register view → CPU emulator: renders snapshots (evidence: `stackemu/widgets.py`)