# kksimp/mac.apk architecture

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

- Interactive diagram: https://gitdiagram.com/kksimp/mac.apk
- Repository: https://github.com/kksimp/mac.apk

## Overview

Mac.apk installs Android packages as Mac app bundles, then launches their Android code as native macOS processes. The runtime combines an Android framework reimplementation with native execution, ARM translation, and macOS-facing window and graphics support; apps use the Mac GPU and appear as ordinary Mac windows. The graph follows documented product stages and the sampled runtime entry point. Several runtime subsystems are represented at directory level because their implementation was not excerpted; edges between them are omitted where the evidence does not establish a call.

Main entry points: [`runtime/src/main.cpp`](https://github.com/kksimp/mac.apk/blob/main/runtime/src/main.cpp) (Runtime entry), [`runtime/java/android`](https://github.com/kksimp/mac.apk/tree/main/runtime/java/android) (Android framework), [`launcher/InstallCore.swift`](https://github.com/kksimp/mac.apk/blob/main/launcher/InstallCore.swift) (APK installer), [`runtime/java/android/app/Activity.java`](https://github.com/kksimp/mac.apk/blob/main/runtime/java/android/app/Activity.java) (Activity lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_install["Install and launch"]
  node_launcher["Mac app"]
  node_installer["APK installer<br/>[InstallCore.swift]"]
  node_bundler["App bundler"]
  node_installhelper["Install helper"]
  node_appbundle["Installed Mac app"]
end

subgraph group_runtime["Android runtime"]
  node_framework["Android framework"]
  node_activity["Activity lifecycle<br/>[Activity.java]"]
  node_context["Android services<br/>[Context.java]"]
  node_intent["Intent messaging<br/>[Intent.java]"]
  node_ui["Views and windows"]
  node_fragments["Fragment manager"]
  node_looper["Looper and handlers<br/>[Looper.java]"]
  node_sharedstorage["Shared storage<br/>[SharedStorage.java]"]
  node_appdata[("App data")]
end

subgraph group_execution["Native execution"]
  node_runtimeentry["Runtime entry<br/>[main.cpp]"]
  node_unpacker["APK unpacker<br/>[apk_unpacker.cpp]"]
  node_jvm["JVM loader<br/>[jvm_loader.h]"]
  node_armloader["Native loader<br/>[apk_native_exec.h]"]
  node_translator["ARM32 translator<br/>[arm32rc_driver.cpp]"]
  node_elf["ELF reader<br/>[elf_reader.cpp]"]
end

subgraph group_host["macOS integration"]
  node_nativebridge["Cocoa bridge<br/>[cocoa_bridge.h]"]
  node_gles["Graphics bridge<br/>[gles_bridge.h]"]
  node_macos(("macOS and GPU"))
end

node_user(("Mac user"))

node_user -->|"opens"| node_launcher
node_user -->|"selects APK"| node_installer
node_launcher -.->|"installs"| node_installer
node_installer -.->|"delegates to"| node_installhelper
node_installer -.->|"creates bundle"| node_bundler
node_bundler -->|"produces"| node_appbundle
node_appbundle -->|"launches"| node_runtimeentry
node_runtimeentry -->|"uses"| node_unpacker
node_runtimeentry -->|"loads"| node_jvm
node_runtimeentry -->|"uses"| node_nativebridge
node_runtimeentry -->|"uses"| node_armloader
node_runtimeentry -->|"starts app runtime"| node_framework
node_framework -->|"provides lifecycle"| node_activity
node_framework -->|"provides services"| node_context
node_framework -->|"provides messaging"| node_intent
node_activity -->|"attaches content"| node_ui
node_activity -->|"manages fragments"| node_fragments
node_fragments -->|"adds views"| node_ui
node_fragments -->|"posts work"| node_looper
node_context -.->|"uses storage"| node_sharedstorage
node_armloader -.->|"translates ARM32"| node_translator
node_translator -.->|"reads ELF"| node_elf
node_runtimeentry -->|"uses"| node_gles
node_nativebridge -->|"bridges to"| node_macos
node_gles -->|"renders via GPU"| node_macos
node_sharedstorage -->|"maps app files"| node_appdata

click node_launcher "https://github.com/kksimp/mac.apk/blob/main/launcher/MacApkLauncherApp.swift"
click node_installer "https://github.com/kksimp/mac.apk/blob/main/launcher/InstallCore.swift"
click node_bundler "https://github.com/kksimp/mac.apk/blob/main/launcher/BundleGenerator.swift"
click node_installhelper "https://github.com/kksimp/mac.apk/blob/main/launcher/InstallHelperMain.swift"
click node_runtimeentry "https://github.com/kksimp/mac.apk/blob/main/runtime/src/main.cpp"
click node_unpacker "https://github.com/kksimp/mac.apk/blob/main/runtime/src/apk_unpacker.cpp"
click node_jvm "https://github.com/kksimp/mac.apk/blob/main/runtime/include/macapk/jvm_loader.h"
click node_framework "https://github.com/kksimp/mac.apk/tree/main/runtime/java/android"
click node_activity "https://github.com/kksimp/mac.apk/blob/main/runtime/java/android/app/Activity.java"
click node_context "https://github.com/kksimp/mac.apk/blob/main/runtime/java/android/content/Context.java"
click node_intent "https://github.com/kksimp/mac.apk/blob/main/runtime/java/android/content/Intent.java"
click node_ui "https://github.com/kksimp/mac.apk/tree/main/runtime/java/android/view"
click node_fragments "https://github.com/kksimp/mac.apk/blob/main/runtime/java/android/app/FragmentManagerImpl.java"
click node_looper "https://github.com/kksimp/mac.apk/blob/main/runtime/java/android/os/Looper.java"
click node_sharedstorage "https://github.com/kksimp/mac.apk/blob/main/runtime/java/com/macapk/loader/SharedStorage.java"
click node_armloader "https://github.com/kksimp/mac.apk/blob/main/runtime/include/macapk/apk_native_exec.h"
click node_translator "https://github.com/kksimp/mac.apk/blob/main/runtime/translator/src/arm32rc/arm32rc_driver.cpp"
click node_elf "https://github.com/kksimp/mac.apk/blob/main/runtime/translator/src/elf_reader.cpp"
click node_nativebridge "https://github.com/kksimp/mac.apk/blob/main/runtime/include/macapk/cocoa_bridge.h"
click node_gles "https://github.com/kksimp/mac.apk/blob/main/runtime/include/macapk/gles_bridge.h"

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_launcher,node_installer,node_bundler,node_installhelper,node_appbundle,node_user toneBlue
class node_framework,node_activity,node_context,node_intent,node_ui,node_fragments,node_looper,node_sharedstorage,node_appdata toneAmber
class node_runtimeentry,node_unpacker,node_jvm,node_armloader,node_translator,node_elf toneMint
class node_nativebridge,node_gles,node_macos toneRose
```

## Components

### Install and launch

- [Mac app](https://github.com/kksimp/mac.apk/blob/main/launcher/MacApkLauncherApp.swift): `launcher/MacApkLauncherApp.swift`
- [APK installer](https://github.com/kksimp/mac.apk/blob/main/launcher/InstallCore.swift): `launcher/InstallCore.swift`
- [App bundler](https://github.com/kksimp/mac.apk/blob/main/launcher/BundleGenerator.swift): `launcher/BundleGenerator.swift`
- [Install helper](https://github.com/kksimp/mac.apk/blob/main/launcher/InstallHelperMain.swift): `launcher/InstallHelperMain.swift`
- **Installed Mac app**

### Android runtime

- [Android framework](https://github.com/kksimp/mac.apk/tree/main/runtime/java/android): `runtime/java/android`
- [Activity lifecycle](https://github.com/kksimp/mac.apk/blob/main/runtime/java/android/app/Activity.java): `runtime/java/android/app/Activity.java`
- [Android services](https://github.com/kksimp/mac.apk/blob/main/runtime/java/android/content/Context.java): `runtime/java/android/content/Context.java`
- [Intent messaging](https://github.com/kksimp/mac.apk/blob/main/runtime/java/android/content/Intent.java): `runtime/java/android/content/Intent.java`
- [Views and windows](https://github.com/kksimp/mac.apk/tree/main/runtime/java/android/view): `runtime/java/android/view`
- [Fragment manager](https://github.com/kksimp/mac.apk/blob/main/runtime/java/android/app/FragmentManagerImpl.java): `runtime/java/android/app/FragmentManagerImpl.java`
- [Looper and handlers](https://github.com/kksimp/mac.apk/blob/main/runtime/java/android/os/Looper.java): `runtime/java/android/os/Looper.java`
- [Shared storage](https://github.com/kksimp/mac.apk/blob/main/runtime/java/com/macapk/loader/SharedStorage.java): `runtime/java/com/macapk/loader/SharedStorage.java`
- **App data**

### Native execution

- [Runtime entry](https://github.com/kksimp/mac.apk/blob/main/runtime/src/main.cpp): `runtime/src/main.cpp`
- [APK unpacker](https://github.com/kksimp/mac.apk/blob/main/runtime/src/apk_unpacker.cpp): `runtime/src/apk_unpacker.cpp`
- [JVM loader](https://github.com/kksimp/mac.apk/blob/main/runtime/include/macapk/jvm_loader.h): `runtime/include/macapk/jvm_loader.h`
- [Native loader](https://github.com/kksimp/mac.apk/blob/main/runtime/include/macapk/apk_native_exec.h): `runtime/include/macapk/apk_native_exec.h`
- [ARM32 translator](https://github.com/kksimp/mac.apk/blob/main/runtime/translator/src/arm32rc/arm32rc_driver.cpp): `runtime/translator/src/arm32rc/arm32rc_driver.cpp`
- [ELF reader](https://github.com/kksimp/mac.apk/blob/main/runtime/translator/src/elf_reader.cpp): `runtime/translator/src/elf_reader.cpp`

### macOS integration

- [Cocoa bridge](https://github.com/kksimp/mac.apk/blob/main/runtime/include/macapk/cocoa_bridge.h): `runtime/include/macapk/cocoa_bridge.h`
- [Graphics bridge](https://github.com/kksimp/mac.apk/blob/main/runtime/include/macapk/gles_bridge.h): `runtime/include/macapk/gles_bridge.h`
- **macOS and GPU**

### Other components

- **Mac user**

## Connections

- Mac user → Mac app: opens (evidence: `README.md`)
- Mac user → APK installer: selects APK (evidence: `README.md`)
- Mac app → APK installer: installs
- APK installer → Install helper: delegates to
- APK installer → App bundler: creates bundle
- App bundler → Installed Mac app: produces (evidence: `README.md`)
- Installed Mac app → Runtime entry: launches (evidence: `README.md`)
- Runtime entry → APK unpacker: uses (evidence: `runtime/src/main.cpp`)
- Runtime entry → JVM loader: loads (evidence: `runtime/src/main.cpp`)
- Runtime entry → Cocoa bridge: uses (evidence: `runtime/src/main.cpp`)
- Runtime entry → Native loader: uses (evidence: `runtime/src/main.cpp`)
- Runtime entry → Android framework: starts app runtime (evidence: `README.md`)
- Android framework → Activity lifecycle: provides lifecycle (evidence: `runtime/java/android/app/Activity.java`)
- Android framework → Android services: provides services (evidence: `runtime/java/android/content/Context.java`)
- Android framework → Intent messaging: provides messaging (evidence: `runtime/java/android/content/Intent.java`)
- Activity lifecycle → Views and windows: attaches content (evidence: `runtime/java/android/app/Activity.java`)
- Activity lifecycle → Fragment manager: manages fragments (evidence: `runtime/java/android/app/FragmentManagerImpl.java`)
- Fragment manager → Views and windows: adds views (evidence: `runtime/java/android/app/FragmentManagerImpl.java`)
- Fragment manager → Looper and handlers: posts work (evidence: `runtime/java/android/app/FragmentManagerImpl.java`)
- Android services → Shared storage: uses storage
- Native loader → ARM32 translator: translates ARM32
- ARM32 translator → ELF reader: reads ELF
- Runtime entry → Graphics bridge: uses (evidence: `runtime/src/main.cpp`)
- Cocoa bridge → macOS and GPU: bridges to (evidence: `README.md`)
- Graphics bridge → macOS and GPU: renders via GPU (evidence: `README.md`)
- Shared storage → App data: maps app files (evidence: `runtime/java/com/macapk/loader/SharedStorage.java`)