# bpluta/pwnground architecture

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

- Interactive diagram: https://gitdiagram.com/bpluta/pwnground
- Repository: https://github.com/bpluta/pwnground

## Overview

##### Main Components
- Overall division between two high-level modules:
- User Interface Module
- Virtual Machine (Emulation & Simulation Engine)
- Supporting libraries or utilities (e.g., Extensions, Utilities) that provide helper functions and common functionality.
- Within the Virtual Machine module, highlight the following subcomponents:
- Binary Executable (handling Mach-O files, binary assembler, static linker)
- Instruction Set (contains various ARM64 instruction implementations, builders, executors, and string builders)
- Operating System Simulator (includes dynamic linker, syscall handling, process spawning, shell interpreter, and system components)
- Virtual Memory (simulating virtual memory blocks, mapped sections, and pages)

##### Confirm the Components via the File Structure
- The “UserInterface” directory contains:
- Components: including inspectors, instructions, pickers, and other UI elements.
- Scenes: different views for various playground levels (e.g., BufferOverflowLevelScene, ExploitingLevelScene) and a main PwngroundScene.
- Interactors: managing interactions between UI and underlying simulation logic.
- Setup and ViewHelpers: that initialize the playground and provide utility functions related to UI.
- The “Virtual Machine” directory is subdivided into:
- “Binary Executable” (with files for assembling and parsing Mach-O binaries)
- “Instruction Set” (implementation of various ARM64 instructions and their executors)
- “Operating System” (simulated XNU kernel functions, syscalls, and standard input/output handling)
- “Virtual Memory” (implements simulation of memory management)
- Additional support is provided by “Extensions” (helper functions extending Swift’s standards types) and “Utilities” (common reusable code).

##### How the Components Interact
- Data Flow and Control:
- The UI (built with SwiftUI and Combine) captures user input and displays debugging visuals.
- Interactors (inside the UI layer) mediate between user actions and underlying simulation logic, triggering changes in the Virtual Machine.
- The Virtual Machine emulates the execution of ARM64 instructions, processing user-built exploits and updating simulated memory/register states.
- Results such as register changes, memory mapping, and debug logs are then passed back to the UI to update visuals.
- User actions → UI Components → Interactors → Virtual Machine Core (subdivided into Instruction Set, Operating System, Virtual Memory)
- Virtual Machine Core → Output (debugger, live visual feedback) → UI Views

##### Architectural Patterns & Design Principles
- Separation of concerns: Clearly separate interactive UI from the emulation core.
- Modular design: The Virtual Machine is structurally subdivided into focused submodules (Instruction Set, OS, Memory) that mimic real system components.
- Use of SwiftUI’s declarative UI patterns combined with Combine’s reactive programming for event handling.
- The design also simulates real system hierarchy—from bit-level CPU instruction execution to kernel-level system process simulation (even though it is a simplified simulator).

## Diagram (Mermaid)

```mermaid
graph TD
    User["User"]:::external
    UI_Module["User Interface Module"]:::ui
    VM_Module["Virtual Machine Module"]:::vm

    subgraph "User Interface"
        UI_Components["Components"]:::ui
        UI_Scenes["Scenes"]:::ui
        UI_Interactors["Interactors"]:::ui
        UI_Setup["Setup"]:::ui
        UI_ViewHelpers["ViewHelpers"]:::ui
    end

    subgraph "Virtual Machine"
        VM_Binary["Binary Executable"]:::vm
        VM_Instruction["Instruction Set"]:::vm
        VM_OS["Operating System Simulator"]:::vm
        VM_Memory["Virtual Memory"]:::vm
    end

    subgraph "Extensions & Utilities"
        EXT["Extensions"]:::extension
        UTIL["Utilities"]:::extension
    end

    %% Relationships
    User -->|"UserCommand"| UI_Module
    UI_Module -->|"Uses"| UI_Interactors
    UI_Interactors -->|"SimAction"| VM_Module
    VM_Module -->|"Provides"| VM_Binary
    VM_Binary -->|"BinaryData"| VM_Instruction
    VM_Instruction -->|"SyscallInteraction"| VM_OS
    VM_Instruction -->|"MemoryOps"| VM_Memory
    VM_Instruction -->|"UpdateVisuals"| UI_Scenes

    %% Utility/Helper dependencies (dashed lines)
    EXT ---|"Helper"| UI_Interactors
    EXT ---|"Helper"| VM_OS
    UTIL ---|"Helper"| VM_Instruction
    UTIL ---|"Helper"| VM_Memory

    %% Click Events
    click UI_Module "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/UserInterface"
    click UI_Components "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/UserInterface/Components"
    click UI_Scenes "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/UserInterface/Scenes"
    click UI_Interactors "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/UserInterface/Interactors"
    click UI_Setup "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/UserInterface/Setup"
    click UI_ViewHelpers "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/UserInterface/ViewHelpers"
    click VM_Module "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/Virtual Machine"
    click VM_Binary "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/Virtual Machine/Binary Executable"
    click VM_Instruction "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/Virtual Machine/Instruction Set"
    click VM_OS "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/Virtual Machine/Operating System"
    click VM_Memory "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/Virtual Machine/Virtual Memory"
    click EXT "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/Extensions"
    click UTIL "https://github.com/bpluta/pwnground/tree/main/Pwnground.swiftpm/Utilities"

    %% Styles
    classDef ui fill:#AEDFF7,stroke:#000,stroke-width:1px;
    classDef vm fill:#C7F9CC,stroke:#000,stroke-width:1px;
    classDef extension fill:#FFF5BA,stroke:#000,stroke-width:1px;
    classDef external fill:#FAD1A5,stroke:#000,stroke-dasharray: 5,stroke-width:2px;
```
