# alex5402/newblackbox architecture

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

- Interactive diagram: https://gitdiagram.com/alex5402/newblackbox
- Repository: https://github.com/alex5402/newblackbox

## Overview

BlackBox is an Android userspace virtualization engine for installing and running isolated app instances without installing their APKs on the host. The principal workflow is to register an app package, resolve virtual package metadata, allocate a sandbox process, and launch the app through Android compatibility and proxy mechanisms. The repository also includes a management app, fake-location and Google Mobile Services screens, device-spoofing hooks, and a reflection layer. Edges are limited to README claims and relationships visible in the supplied excerpts or SOURCE INDEX; many implementation details were not sampled.

Main entry points: [`Bcore/src/main/java/top/niunaijun/blackbox/BlackBoxCore.java`](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/BlackBoxCore.java) (Core facade), [`Bcore/src/main/java/top/niunaijun/blackbox/core/system/BProcessManagerService.java`](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/BProcessManagerService.java) (Process management), [`app/src/main/java/top/niunaijun/blackboxa/view/fake/FakeManagerActivity.kt`](https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/view/fake/FakeManagerActivity.kt) (Fake location UI), [`Bcore/src/main/java/top/niunaijun/blackbox/core/system/pm/BPackageManagerService.java`](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/pm/BPackageManagerService.java) (Package management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Host management app"]
  node_manager_ui["App management UI<br/>[AppsFragment.kt]"]
  node_app_manager["App manager<br/>[AppManager.kt]"]
  node_fake_ui["Fake location UI"]
  node_fake_repo["Location repository"]
  node_gms_ui["GMS manager UI"]
  node_gms_repo["GMS repository<br/>[GmsRepository.kt]"]
end

subgraph group_virtual_core["Virtual app runtime"]
  node_core_api["Core facade<br/>[BlackBoxCore.java]"]
  node_package_service["Package management"]
  node_process_service["Process management"]
  node_process_record["Process record<br/>[ProcessRecord.java]"]
  node_environment["Sandbox environment<br/>[BEnvironment.java]"]
  node_app_lifecycle["Activity management"]
  node_virtual_storage["Virtual storage"]
end

subgraph group_android_compat["Android compatibility"]
  node_framework_shims["Framework shims"]
  node_native_hooks["Native hooks"]
  node_reflection["Reflection access"]
end

subgraph group_extensions["Virtual features"]
  node_location_service["Fake location service"]
  node_device_spoof["Device spoofing<br/>[VirtualSpoof.cpp]"]
  node_gms_core["GMS support<br/>[GmsCore.java]"]
end

node_user(("Device user"))

node_user -->|"manages apps"| node_manager_ui
node_manager_ui -.->|"requests app actions"| node_app_manager
node_user -->|"sets location"| node_fake_ui
node_fake_ui -.->|"updates location"| node_fake_repo
node_fake_ui -->|"configures location"| node_location_service
node_user -.->|"manages GMS"| node_gms_ui
node_gms_ui -->|"loads GMS data"| node_gms_repo
node_app_manager -.->|"uses engine"| node_core_api
node_core_api -.->|"queries packages"| node_package_service
node_package_service -->|"starts or kills"| node_process_service
node_process_service -->|"resolves app info"| node_package_service
node_process_service -->|"tracks process"| node_process_record
node_process_service -->|"initializes sandbox"| node_environment
node_core_api -->|"coordinates activities"| node_app_lifecycle
node_core_api -.->|"exposes storage"| node_virtual_storage
node_framework_shims -.->|"uses reflected APIs"| node_reflection
node_native_hooks -.->|"intercepts runtime"| node_framework_shims
node_core_api -->|"spoofs device data"| node_device_spoof
node_core_api -->|"supports fake GPS"| node_location_service
node_core_api -.->|"supports GMS"| node_gms_core

click node_manager_ui "https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/view/apps/AppsFragment.kt"
click node_app_manager "https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/app/AppManager.kt"
click node_fake_ui "https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/view/fake/FakeManagerActivity.kt"
click node_fake_repo "https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/data/FakeLocationRepository.kt"
click node_gms_ui "https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/view/gms/GmsManagerActivity.kt"
click node_gms_repo "https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/data/GmsRepository.kt"
click node_core_api "https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/BlackBoxCore.java"
click node_package_service "https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/pm/BPackageManagerService.java"
click node_process_service "https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/BProcessManagerService.java"
click node_process_record "https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/ProcessRecord.java"
click node_environment "https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/env/BEnvironment.java"
click node_app_lifecycle "https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/am/BActivityManagerService.java"
click node_virtual_storage "https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/os/BStorageManagerService.java"
click node_framework_shims "https://github.com/alex5402/newblackbox/tree/main/Bcore/src/main/java/black/android"
click node_native_hooks "https://github.com/alex5402/newblackbox/tree/main/Bcore/src/main/cpp/Hook"
click node_reflection "https://github.com/alex5402/newblackbox/tree/main/black-reflection/src/main/java/top/niunaijun/blackreflection"
click node_location_service "https://github.com/alex5402/newblackbox/tree/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/location"
click node_device_spoof "https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/cpp/Utils/VirtualSpoof.cpp"
click node_gms_core "https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/GmsCore.java"

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_manager_ui,node_app_manager,node_fake_ui,node_fake_repo,node_gms_ui,node_gms_repo,node_user toneBlue
class node_core_api,node_package_service,node_process_service,node_process_record,node_environment,node_app_lifecycle,node_virtual_storage toneAmber
class node_framework_shims,node_native_hooks,node_reflection toneMint
class node_location_service,node_device_spoof,node_gms_core toneRose
```

## Components

### Host management app

- [App management UI](https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/view/apps/AppsFragment.kt): `app/src/main/java/top/niunaijun/blackboxa/view/apps/AppsFragment.kt`
- [App manager](https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/app/AppManager.kt): `app/src/main/java/top/niunaijun/blackboxa/app/AppManager.kt`
- [Fake location UI](https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/view/fake/FakeManagerActivity.kt): `app/src/main/java/top/niunaijun/blackboxa/view/fake/FakeManagerActivity.kt`
- [Location repository](https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/data/FakeLocationRepository.kt): `app/src/main/java/top/niunaijun/blackboxa/data/FakeLocationRepository.kt`
- [GMS manager UI](https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/view/gms/GmsManagerActivity.kt): `app/src/main/java/top/niunaijun/blackboxa/view/gms/GmsManagerActivity.kt`
- [GMS repository](https://github.com/alex5402/newblackbox/blob/main/app/src/main/java/top/niunaijun/blackboxa/data/GmsRepository.kt): `app/src/main/java/top/niunaijun/blackboxa/data/GmsRepository.kt`

### Virtual app runtime

- [Core facade](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/BlackBoxCore.java): `Bcore/src/main/java/top/niunaijun/blackbox/BlackBoxCore.java`
- [Package management](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/pm/BPackageManagerService.java): `Bcore/src/main/java/top/niunaijun/blackbox/core/system/pm/BPackageManagerService.java`
- [Process management](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/BProcessManagerService.java): `Bcore/src/main/java/top/niunaijun/blackbox/core/system/BProcessManagerService.java`
- [Process record](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/ProcessRecord.java): `Bcore/src/main/java/top/niunaijun/blackbox/core/system/ProcessRecord.java`
- [Sandbox environment](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/env/BEnvironment.java): `Bcore/src/main/java/top/niunaijun/blackbox/core/env/BEnvironment.java`
- [Activity management](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/am/BActivityManagerService.java): `Bcore/src/main/java/top/niunaijun/blackbox/core/system/am/BActivityManagerService.java`
- [Virtual storage](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/os/BStorageManagerService.java): `Bcore/src/main/java/top/niunaijun/blackbox/core/system/os/BStorageManagerService.java`

### Android compatibility

- [Framework shims](https://github.com/alex5402/newblackbox/tree/main/Bcore/src/main/java/black/android): `Bcore/src/main/java/black/android`
- [Native hooks](https://github.com/alex5402/newblackbox/tree/main/Bcore/src/main/cpp/Hook): `Bcore/src/main/cpp/Hook`
- [Reflection access](https://github.com/alex5402/newblackbox/tree/main/black-reflection/src/main/java/top/niunaijun/blackreflection): `black-reflection/src/main/java/top/niunaijun/blackreflection`

### Virtual features

- [Fake location service](https://github.com/alex5402/newblackbox/tree/main/Bcore/src/main/java/top/niunaijun/blackbox/core/system/location): `Bcore/src/main/java/top/niunaijun/blackbox/core/system/location`
- [Device spoofing](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/cpp/Utils/VirtualSpoof.cpp): `Bcore/src/main/cpp/Utils/VirtualSpoof.cpp`
- [GMS support](https://github.com/alex5402/newblackbox/blob/main/Bcore/src/main/java/top/niunaijun/blackbox/core/GmsCore.java): `Bcore/src/main/java/top/niunaijun/blackbox/core/GmsCore.java`

### Other components

- **Device user**

## Connections

- Device user → App management UI: manages apps (evidence: `README.md`)
- App management UI → App manager: requests app actions
- Device user → Fake location UI: sets location (evidence: `README.md`)
- Fake location UI → Location repository: updates location
- Fake location UI → Fake location service: configures location (evidence: `app/src/main/java/top/niunaijun/blackboxa/view/fake/FakeManagerActivity.kt`)
- Device user → GMS manager UI: manages GMS
- GMS manager UI → GMS repository: loads GMS data (evidence: `app/src/main/java/top/niunaijun/blackboxa/view/gms/GmsManagerActivity.kt`)
- App manager → Core facade: uses engine (evidence: `app/src/main/java/top/niunaijun/blackboxa/app/AppManager.kt`)
- Core facade → Package management: queries packages (evidence: `Bcore/src/main/java/top/niunaijun/blackbox/core/system/pm/BPackageManagerService.java`)
- Package management → Process management: starts or kills (evidence: `Bcore/src/main/java/top/niunaijun/blackbox/core/system/pm/BPackageManagerService.java`)
- Process management → Package management: resolves app info (evidence: `Bcore/src/main/java/top/niunaijun/blackbox/core/system/BProcessManagerService.java`)
- Process management → Process record: tracks process (evidence: `Bcore/src/main/java/top/niunaijun/blackbox/core/system/BProcessManagerService.java`)
- Process management → Sandbox environment: initializes sandbox (evidence: `Bcore/src/main/java/top/niunaijun/blackbox/core/system/BProcessManagerService.java`)
- Core facade → Activity management: coordinates activities (evidence: `Bcore/src/main/java/top/niunaijun/blackbox/BlackBoxCore.java`)
- Core facade → Virtual storage: exposes storage (evidence: `Bcore/src/main/java/top/niunaijun/blackbox/core/system/os/BStorageManagerService.java`)
- Framework shims → Reflection access: uses reflected APIs (evidence: `Bcore/src/main/java/black/android/os/storage/StorageManager.java`)
- Native hooks → Framework shims: intercepts runtime
- Core facade → Device spoofing: spoofs device data (evidence: `README.md`)
- Core facade → Fake location service: supports fake GPS (evidence: `README.md`)
- Core facade → GMS support: supports GMS (evidence: `Bcore/src/main/java/top/niunaijun/blackbox/BlackBoxCore.java`)
