# lnpandy/nx2apple architecture

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

- Interactive diagram: https://gitdiagram.com/lnpandy/nx2apple
- Repository: https://github.com/lnpandy/nx2apple

## Overview

NX2Apple builds Switch-game applications for Apple devices, then provides a Mac library and an iOS/iPadOS shell for launching them. The principal workflow is selecting game inputs and a target, building and packaging the game, transferring or installing it, then launching it from a library. The repository also includes a Windows launcher and documented controller, cloud-save, settings, and touch-control capabilities. Relationships below follow README workflow statements and the shown source references; unsampled subsystems are represented by their tree paths without assuming internal calls.

Main entry points: [`frontend/Sources/NXModel/BuildStore.swift`](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXModel/BuildStore.swift) (Build orchestration), [`frontend-ios/Sources/ShellHost/GameCatalogue.swift`](https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Sources/ShellHost/GameCatalogue.swift) (Shell game library), [`frontend-ios/Shell/App/ShellApp.swift`](https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Shell/App/ShellApp.swift) (iOS shell app), [`frontend/Sources/NXCore/BuildArchive.swift`](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/BuildArchive.swift) (Build output)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop launchers"]
  node_maclauncher["Mac launcher UI<br/>[LauncherView.swift]"]
  node_windowslauncher["Windows launcher<br/>[ui.py]"]
end

subgraph group_build["Build and engine"]
  node_buildstore["Build orchestration<br/>[BuildStore.swift]"]
  node_buildqueue["Build queue<br/>[BuildQueue.swift]"]
  node_gameinputs["Game inputs<br/>[GameFolder.swift]"]
  node_engine["Engine selection"]
  node_engineupdate["Engine updates"]
  node_process["Build processes"]
  node_macbuilder["Mac game builder"]
  node_s2builder["Switch 2 builder<br/>[S2ArmBuilder.swift]"]
  node_output["Build output<br/>[BuildArchive.swift]"]
  node_deviceinstall["Device install<br/>[ShellInstall.swift]"]
end

subgraph group_library["Game libraries"]
  node_maclibrary[("Mac game library<br/>[Library.swift]")]
end

subgraph group_shell["iOS shell"]
  node_shellapp["iOS shell app<br/>[ShellApp.swift]"]
  node_shelllibrary[("Shell game library")]
  node_launchplan["Engine launch plan"]
end

subgraph group_play["Play capabilities"]
  node_gameplay["Native gameplay<br/>[ShellEngine.h]"]
  node_controllers["Controller support"]
  node_touch["Touch controls<br/>[TouchLayout.swift]"]
  node_saves["Cloud saves"]
  node_mods["Per-game mods<br/>[GameMods.swift]"]
end

node_player(("Player"))

node_player -->|"chooses target"| node_maclauncher
node_player -->|"builds games"| node_windowslauncher
node_maclauncher -.->|"configures builds"| node_buildstore
node_windowslauncher -.->|"configures builds"| node_buildstore
node_buildstore -->|"uses inputs"| node_gameinputs
node_buildstore -->|"queues builds"| node_buildqueue
node_buildstore -->|"selects engine"| node_engine
node_engine -->|"checks updates"| node_engineupdate
node_buildstore -->|"builds Mac games"| node_macbuilder
node_buildstore -->|"builds Switch 2"| node_s2builder
node_buildstore -.->|"runs processes"| node_process
node_macbuilder -.->|"packages game"| node_output
node_s2builder -.->|"packages game"| node_output
node_buildstore -.->|"installs shell"| node_deviceinstall
node_player -->|"manages games"| node_maclibrary
node_output -->|"adds built game"| node_maclibrary
node_output -->|"copies game"| node_deviceinstall
node_deviceinstall -->|"installs app"| node_shellapp
node_shellapp -.->|"shows games"| node_shelllibrary
node_player -->|"selects game"| node_shelllibrary
node_shelllibrary -.->|"prepares launch"| node_launchplan
node_launchplan -->|"configures engine"| node_gameplay
node_shellapp -.->|"accepts input"| node_controllers
node_shellapp -.->|"offers controls"| node_touch
node_shelllibrary -.->|"syncs saves"| node_saves
node_shelllibrary -.->|"loads mods"| node_mods

click node_maclauncher "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NX2Apple/LauncherView.swift"
click node_windowslauncher "https://github.com/lnpandy/nx2apple/blob/main/frontend-qt/nspb_qt/ui.py"
click node_buildstore "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXModel/BuildStore.swift"
click node_buildqueue "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/BuildQueue.swift"
click node_gameinputs "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/GameFolder.swift"
click node_engine "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXModel/EngineSyncStore.swift"
click node_engineupdate "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/EngineUpdater.swift"
click node_process "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/ProcessRunner.swift"
click node_macbuilder "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/MacNativeGamesBuilder.swift"
click node_s2builder "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/S2ArmBuilder.swift"
click node_output "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/BuildArchive.swift"
click node_deviceinstall "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/ShellInstall.swift"
click node_maclibrary "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NX2Apple/Library.swift"
click node_shellapp "https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Shell/App/ShellApp.swift"
click node_shelllibrary "https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Sources/ShellHost/GameCatalogue.swift"
click node_launchplan "https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift"
click node_gameplay "https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Shell/App/ShellEngine.h"
click node_controllers "https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Sources/ShellControllers/GamepadAdapter.swift"
click node_touch "https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Sources/ShellUI/TouchLayout.swift"
click node_saves "https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/CloudSaveSync.swift"
click node_mods "https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Sources/ShellHost/GameMods.swift"

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_maclauncher,node_windowslauncher toneBlue
class node_buildstore,node_buildqueue,node_gameinputs,node_engine,node_engineupdate,node_process,node_macbuilder,node_s2builder,node_output,node_deviceinstall toneAmber
class node_maclibrary toneMint
class node_shellapp,node_shelllibrary,node_launchplan toneRose
class node_gameplay,node_controllers,node_touch,node_saves,node_mods,node_player toneIndigo
```

## Components

### Desktop launchers

- [Mac launcher UI](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NX2Apple/LauncherView.swift): `frontend/Sources/NX2Apple/LauncherView.swift`
- [Windows launcher](https://github.com/lnpandy/nx2apple/blob/main/frontend-qt/nspb_qt/ui.py): `frontend-qt/nspb_qt/ui.py`

### Build and engine

- [Build orchestration](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXModel/BuildStore.swift): `frontend/Sources/NXModel/BuildStore.swift`
- [Build queue](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/BuildQueue.swift): `frontend/Sources/NXCore/BuildQueue.swift`
- [Game inputs](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/GameFolder.swift): `frontend/Sources/NXCore/GameFolder.swift`
- [Engine selection](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXModel/EngineSyncStore.swift): `frontend/Sources/NXModel/EngineSyncStore.swift`
- [Engine updates](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/EngineUpdater.swift): `frontend/Sources/NXCore/EngineUpdater.swift`
- [Build processes](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/ProcessRunner.swift): `frontend/Sources/NXCore/ProcessRunner.swift`
- [Mac game builder](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/MacNativeGamesBuilder.swift): `frontend/Sources/NXCore/MacNativeGamesBuilder.swift`
- [Switch 2 builder](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/S2ArmBuilder.swift): `frontend/Sources/NXCore/S2ArmBuilder.swift`
- [Build output](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/BuildArchive.swift): `frontend/Sources/NXCore/BuildArchive.swift`
- [Device install](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/ShellInstall.swift): `frontend/Sources/NXCore/ShellInstall.swift`

### Game libraries

- [Mac game library](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NX2Apple/Library.swift): `frontend/Sources/NX2Apple/Library.swift`

### iOS shell

- [iOS shell app](https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Shell/App/ShellApp.swift): `frontend-ios/Shell/App/ShellApp.swift`
- [Shell game library](https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Sources/ShellHost/GameCatalogue.swift): `frontend-ios/Sources/ShellHost/GameCatalogue.swift`
- [Engine launch plan](https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift): `frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift`

### Play capabilities

- [Native gameplay](https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Shell/App/ShellEngine.h): `frontend-ios/Shell/App/ShellEngine.h`
- [Controller support](https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Sources/ShellControllers/GamepadAdapter.swift): `frontend-ios/Sources/ShellControllers/GamepadAdapter.swift`
- [Touch controls](https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Sources/ShellUI/TouchLayout.swift): `frontend-ios/Sources/ShellUI/TouchLayout.swift`
- [Cloud saves](https://github.com/lnpandy/nx2apple/blob/main/frontend/Sources/NXCore/CloudSaveSync.swift): `frontend/Sources/NXCore/CloudSaveSync.swift`
- [Per-game mods](https://github.com/lnpandy/nx2apple/blob/main/frontend-ios/Sources/ShellHost/GameMods.swift): `frontend-ios/Sources/ShellHost/GameMods.swift`

### Other components

- **Player**

## Connections

- Player → Mac launcher UI: chooses target (evidence: `README.md`)
- Player → Windows launcher: builds games (evidence: `README.md`)
- Mac launcher UI → Build orchestration: configures builds
- Windows launcher → Build orchestration: configures builds
- Build orchestration → Game inputs: uses inputs (evidence: `frontend/Sources/NXModel/BuildStore.swift`)
- Build orchestration → Build queue: queues builds (evidence: `frontend/Sources/NXModel/BuildStore.swift`)
- Build orchestration → Engine selection: selects engine (evidence: `frontend/Sources/NXModel/BuildStore.swift`)
- Engine selection → Engine updates: checks updates (evidence: `frontend/Sources/NXModel/EngineSyncStore.swift`)
- Build orchestration → Mac game builder: builds Mac games (evidence: `frontend/Sources/NXModel/BuildStore.swift`)
- Build orchestration → Switch 2 builder: builds Switch 2 (evidence: `frontend/Sources/NXModel/BuildStore.swift`)
- Build orchestration → Build processes: runs processes (evidence: `frontend/Sources/NXModel/BuildStore.swift`)
- Mac game builder → Build output: packages game
- Switch 2 builder → Build output: packages game
- Build orchestration → Device install: installs shell
- Player → Mac game library: manages games (evidence: `README.md`)
- Build output → Mac game library: adds built game (evidence: `README.md`)
- Build output → Device install: copies game (evidence: `README.md`)
- Device install → iOS shell app: installs app (evidence: `README.md`)
- iOS shell app → Shell game library: shows games
- Player → Shell game library: selects game (evidence: `README.md`)
- Shell game library → Engine launch plan: prepares launch
- Engine launch plan → Native gameplay: configures engine (evidence: `frontend-ios/Sources/ShellHost/EngineLaunchPlan.swift`)
- iOS shell app → Controller support: accepts input
- iOS shell app → Touch controls: offers controls
- Shell game library → Cloud saves: syncs saves
- Shell game library → Per-game mods: loads mods
