# script-sage/pixelify architecture

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

- Interactive diagram: https://gitdiagram.com/script-sage/pixelify
- Repository: https://github.com/script-sage/pixelify

## Overview

1. **What this repo is**
   - Pixelify is a **Magisk module** that modifies an Android system at boot to make non-Pixel devices behave like Pixels and unlock Pixel-only features.
   - The repository is split into three main parts: the **Magisk module payload**, a **Riru** native hook, and a **Zygisk** native hook.

2. **Build and packaging layer**
   - Root Gradle files (`build.gradle`, `module.gradle`, `settings.gradle`) coordinate the module and native components.
   - The `module/` directory is the flashable Magisk package layout, including `META-INF` installer metadata, shell scripts, property files, and bundled assets.
   - `module/build.sh` appears to assemble the distributable module ZIP from these pieces.

3. **Install-time control plane**
   - The install flow is driven by shell scripts in `module/`: `customize.sh`, `pixelify.sh`, `utils.sh`, `vars.sh`, and `service.sh`.
   - `module.prop`, `system.prop`, `spoof.prop`, `var.prop`, and `config.prop` define module metadata, system property overrides, spoofing targets, and feature toggles.
   - `sepolicy.rule` extends SELinux permissions so the module can touch system components that normal apps cannot.

4. **Boot/runtime behavior**
   - `service.sh` is the main boot-time entrypoint for applying changes after Android starts.
   - `service-uninstaller.sh` and `uninstall.sh` handle cleanup and rollback.
   - `module-uninstaller.prop` and `module-deviceconfig.txt` suggest the module maintains state about what was installed and which device profile was selected.

5. **Static system content bundled into the module**
   - `module/files/` contains the actual payloads Pixelify installs or mounts into the system view: APKs, boot animations, overlays, firmware descriptors, audio files, and tar archives.
   - Examples include Pixel Launcher and Pixel UI-related APKs, Device Personalization/Google app support pieces, bootanimation archives, and call-recording voice prompts.
   - `module/extras/` contains optional feature packs such as **Hotword** and **Now Playing** resources.

6. **System overlay and privileged app model**
   - The repo ships prebuilt overlays and privileged-app content under paths that mirror `/system`, `/product`, and `/system_ext`.
   - This is how Pixel UI features are enabled without shipping a full ROM: the module injects overlay APKs, priv-app APKs, XML permissions, and sysconfig whitelist files into the system namespace.
   - The “hotword” and “now playing” extras are especially structured around system permissions and privileged placement.

7. **Native runtime spoofing layer**
   - `riru/` and `zygisk/` are separate native modules that hook into the Android process runtime through Magisk’s two supported injection mechanisms.
   - Both contain C++ code and CMake build files; the Zygisk side uses `pixelify.cpp`, `module.h`, and shared logic in `tensor.cpp` / `tensor_2.cpp`.
   - This layer is responsible for **targeted spoofing** and dynamic behavior changes inside Google apps rather than globally altering every app.

8. **How the data flows**
   - At install time, the module copies or mounts system-facing assets and records configuration.
   - At boot, shell services apply properties, set up permissions, and stage files.
   - When Google apps launch, the Riru/Zygisk hooks selectively spoof device identity or feature flags so only those target packages see Pixel-like signals.
   - That targeted approach is important: the module tries to avoid breaking the rest of the OS by scoping spoofing mostly to Google components.

9. **External app and service boundaries**
   - The main external dependencies are **Google Play services**, **Google app**, **Google Photos**, **Google Dialer**, **Android System Intelligence**, **Pixel Launcher**, and related Google packages.
   - The README shows many features depend on Google-side downloads or account-state behavior, so the module’s behavior is partly gated by network fetches and Google app updates.
   - Some features also depend on Android version, device kernel support, or ROM-specific compatibility.

10. **Support tooling inside the repo**
   - `module/addon/` includes helper binaries such as `aapt`, `curl`, `dumpsys`, `keycheck`, and `sqlite3`.
   - These utilities imply the install scripts inspect APK metadata, query system state, download assets, and patch or validate settings/databases during installation.
   - This makes the module more than a simple file copier; it behaves like an installer/orchestrator.

11. **Feature submodules and optionality**
   - The README describes optional submodules for **Call Screening**, **Now Playing**, **Google Hotword**, **Unlimited Photos Backup**, and **Google Bootanimation**.
   - The architecture supports selective installation, which is reflected in the presence of separate extras, config files, and the “no volume keys” install path.
   - That modularity is a key diagram boundary: not all features are always present in one boot path.

12. **Operational logging and recovery**
   - The module writes logs and flags to `/sdcard/Pixelify/` according to the README, including flag logs and bootloop-related diagnostics.
   - This indicates a built-in troubleshooting path: install scripts and runtime logic can surface failures without requiring a full ROM flash.
   - The repo also contains an uninstaller path and recovery-oriented logic, which matters because many features are applied system-wide and need safe rollback.

Main entry points: [`module`](https://github.com/script-sage/pixelify/tree/master/module) (Module layout), [`module/service.sh`](https://github.com/script-sage/pixelify/blob/master/module/service.sh) (Boot service), [`module/files`](https://github.com/script-sage/pixelify/tree/master/module/files) (System payloads), [`zygisk/src/main/cpp/pixelify.cpp`](https://github.com/script-sage/pixelify/blob/master/zygisk/src/main/cpp/pixelify.cpp) (Zygisk hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_build["Build & packaging"]
  node_node_root_build["Gradle files<br/>build orchestration<br/>[build.gradle]"]
  node_node_module_gradle["Module build<br/>packaging config<br/>[module.gradle]"]
  node_node_settings["Settings<br/>project config<br/>[settings.gradle]"]
end

subgraph group_group_module["Magisk module"]
  node_node_module_zip["Module layout<br/>magisk package"]
  node_node_installer["Installer scripts<br/>shell control plane<br/>[customize.sh]"]
  node_node_service["Boot service<br/>boot entrypoint<br/>[service.sh]"]
  node_node_uninstall["Rollback path<br/>cleanup scripts<br/>[uninstall.sh]"]
  node_node_props["Module props<br/>property configs<br/>[module.prop]"]
  node_node_policy["SELinux rule<br/>policy extension<br/>[sepolicy.rule]"]
  node_node_payloads["System payloads<br/>bundled assets"]
  node_node_addon["Helper tools<br/>installer utilities"]
end

subgraph group_group_runtime["Runtime hooks"]
  node_node_riru["Riru hook<br/>native runtime<br/>[main.cpp]"]
  node_node_zygisk["Zygisk hook<br/>native runtime<br/>[pixelify.cpp]"]
  node_node_tensor["Shared spoofing<br/>native logic<br/>[tensor.cpp]"]
  node_node_tensor2["Target rules<br/>native logic<br/>[tensor_2.cpp]"]
end

subgraph group_group_extras["Feature packs"]
  node_node_hotword["Hotword pack<br/>optional feature"]
  node_node_hotword9["Hotword pack 9<br/>optional feature"]
  node_node_nowplaying["Now Playing<br/>optional feature"]
end

node_node_root_build -->|"builds"| node_node_module_gradle
node_node_root_build -->|"includes"| node_node_settings
node_node_module_gradle -->|"packages"| node_node_module_zip
node_node_module_zip -->|"contains"| node_node_installer
node_node_module_zip -->|"contains"| node_node_service
node_node_module_zip -->|"contains"| node_node_uninstall
node_node_module_zip -->|"defines"| node_node_props
node_node_module_zip -->|"extends"| node_node_policy
node_node_module_zip -->|"ships"| node_node_payloads
node_node_module_zip -->|"uses"| node_node_addon
node_node_module_zip -->|"optionally includes"| node_node_hotword
node_node_module_zip -->|"optionally includes"| node_node_hotword9
node_node_module_zip -->|"optionally includes"| node_node_nowplaying
node_node_installer -->|"invokes"| node_node_addon
node_node_service -->|"reads"| node_node_props
node_node_service -->|"mounts"| node_node_payloads
node_node_uninstall -->|"removes"| node_node_payloads
node_node_zygisk -->|"shares"| node_node_tensor
node_node_zygisk -->|"shares"| node_node_tensor2
node_node_riru -->|"reuses"| node_node_tensor
node_node_tensor -->|"coordinates"| node_node_tensor2
node_node_zygisk -.->|"complements"| node_node_service
node_node_riru -.->|"complements"| node_node_service
node_node_hotword -->|"adds"| node_node_payloads
node_node_nowplaying -->|"adds"| node_node_payloads

click node_node_root_build "https://github.com/script-sage/pixelify/blob/master/build.gradle"
click node_node_module_gradle "https://github.com/script-sage/pixelify/blob/master/module.gradle"
click node_node_settings "https://github.com/script-sage/pixelify/blob/master/settings.gradle"
click node_node_module_zip "https://github.com/script-sage/pixelify/tree/master/module"
click node_node_installer "https://github.com/script-sage/pixelify/blob/master/module/customize.sh"
click node_node_service "https://github.com/script-sage/pixelify/blob/master/module/service.sh"
click node_node_uninstall "https://github.com/script-sage/pixelify/blob/master/module/uninstall.sh"
click node_node_props "https://github.com/script-sage/pixelify/blob/master/module/module.prop"
click node_node_policy "https://github.com/script-sage/pixelify/blob/master/module/sepolicy.rule"
click node_node_payloads "https://github.com/script-sage/pixelify/tree/master/module/files"
click node_node_addon "https://github.com/script-sage/pixelify/tree/master/module/addon"
click node_node_hotword "https://github.com/script-sage/pixelify/tree/master/module/extras/hotword"
click node_node_hotword9 "https://github.com/script-sage/pixelify/tree/master/module/extras/hotword-9"
click node_node_nowplaying "https://github.com/script-sage/pixelify/tree/master/module/extras/nplaying"
click node_node_riru "https://github.com/script-sage/pixelify/blob/master/riru/src/main/cpp/main.cpp"
click node_node_zygisk "https://github.com/script-sage/pixelify/blob/master/zygisk/src/main/cpp/pixelify.cpp"
click node_node_tensor "https://github.com/script-sage/pixelify/blob/master/zygisk/src/main/cpp/tensor.cpp"
click node_node_tensor2 "https://github.com/script-sage/pixelify/blob/master/zygisk/src/main/cpp/tensor_2.cpp"

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_node_root_build,node_node_module_gradle,node_node_settings toneBlue
class node_node_module_zip,node_node_installer,node_node_service,node_node_uninstall,node_node_props,node_node_policy,node_node_payloads,node_node_addon toneAmber
class node_node_riru,node_node_zygisk,node_node_tensor,node_node_tensor2 toneMint
class node_node_hotword,node_node_hotword9,node_node_nowplaying toneRose
```

## Components

### Build & packaging

Gradle and packaging entry points that assemble the Magisk module and native hooks.

- [Gradle files](https://github.com/script-sage/pixelify/blob/master/build.gradle): build orchestration · Top-level Gradle entry points that coordinate module and native builds. · `build.gradle`
- [Module build](https://github.com/script-sage/pixelify/blob/master/module.gradle): packaging config · Module-specific Gradle configuration for the flashable package. · `module.gradle`
- [Settings](https://github.com/script-sage/pixelify/blob/master/settings.gradle): project config · Gradle project settings and included components. · `settings.gradle`

### Magisk module

Flashable module layout, install scripts, properties, and bundled system-facing payloads.

- [Module layout](https://github.com/script-sage/pixelify/tree/master/module): magisk package · Flashable Magisk module directory that carries installers, properties, scripts, and payloads. · `module`
- [Installer scripts](https://github.com/script-sage/pixelify/blob/master/module/customize.sh): shell control plane · Install-time logic and boot-time orchestration for setup, tuning, and cleanup. · `module/customize.sh`
- [Boot service](https://github.com/script-sage/pixelify/blob/master/module/service.sh): boot entrypoint · Main post-boot script that applies module changes on device startup. · `module/service.sh`
- [Rollback path](https://github.com/script-sage/pixelify/blob/master/module/uninstall.sh): cleanup scripts · Uninstall and service cleanup logic for removing module changes safely. · `module/uninstall.sh`
- [Module props](https://github.com/script-sage/pixelify/blob/master/module/module.prop): property configs · Metadata, property overrides, spoof targets, toggles, and install state files. · `module/module.prop`
- [SELinux rule](https://github.com/script-sage/pixelify/blob/master/module/sepolicy.rule): policy extension · Extra SELinux permissions required for system-level modification. · `module/sepolicy.rule`
- [System payloads](https://github.com/script-sage/pixelify/tree/master/module/files): bundled assets · Representative system-facing APKs, overlays, archives, and media injected by the module. · `module/files`
- [Helper tools](https://github.com/script-sage/pixelify/tree/master/module/addon): installer utilities · Bundled binaries used by scripts for inspection, downloads, validation, and database work. · `module/addon`

### Runtime hooks

Native injection layers that spoof behavior inside selected Google processes.

- [Riru hook](https://github.com/script-sage/pixelify/blob/master/riru/src/main/cpp/main.cpp): native runtime · Riru-based native process hook for targeted spoofing in app processes. · `riru/src/main/cpp/main.cpp`
- [Zygisk hook](https://github.com/script-sage/pixelify/blob/master/zygisk/src/main/cpp/pixelify.cpp): native runtime · Zygisk-based native hook with shared spoofing logic for injected Google apps. · `zygisk/src/main/cpp/pixelify.cpp`
- [Shared spoofing](https://github.com/script-sage/pixelify/blob/master/zygisk/src/main/cpp/tensor.cpp): native logic · Common runtime logic used by both native hook implementations. · `zygisk/src/main/cpp/tensor.cpp`
- [Target rules](https://github.com/script-sage/pixelify/blob/master/zygisk/src/main/cpp/tensor_2.cpp): native logic · Secondary runtime logic for package-specific spoofing decisions. · `zygisk/src/main/cpp/tensor_2.cpp`

### Feature packs

Optional bundled feature sets and privileged assets for specific Pixel capabilities.

- [Hotword pack](https://github.com/script-sage/pixelify/tree/master/module/extras/hotword): optional feature · Optional privileged hotword enrollment assets and permissions. · `module/extras/hotword`
- [Hotword pack 9](https://github.com/script-sage/pixelify/tree/master/module/extras/hotword-9): optional feature · Android 9-specific hotword enrollment package set. · `module/extras/hotword-9`
- [Now Playing](https://github.com/script-sage/pixelify/tree/master/module/extras/nplaying): optional feature · Now Playing overlay and firmware descriptors for music detection. · `module/extras/nplaying`

## Connections

- Gradle files → Module build: builds · Top-level build coordinates module packaging.
- Gradle files → Settings: includes · Project settings define the build graph.
- Module build → Module layout: packages · Module build assembles the flashable payload.
- Module layout → Installer scripts: contains · Module layout includes install-time scripts.
- Module layout → Boot service: contains · Boot service is shipped inside the module.
- Module layout → Rollback path: contains · Rollback scripts are part of the shipped module.
- Module layout → Module props: defines · Metadata and property files configure module behavior.
- Module layout → SELinux rule: extends · SELinux rules widen system access for the module.
- Module layout → System payloads: ships · Representative system-facing assets are bundled for mounting or copy-in.
- Module layout → Helper tools: uses · Helper binaries support installation and validation.
- Module layout → Hotword pack: optionally includes · Hotword feature pack can be installed separately.
- Module layout → Hotword pack 9: optionally includes · Android 9 hotword variant is packaged separately.
- Module layout → Now Playing: optionally includes · Now Playing resources are bundled as an optional pack.
- Installer scripts → Helper tools: invokes · Scripts call helper binaries during install-time orchestration.
- Boot service → Module props: reads · Boot service applies module configuration and state.
- Boot service → System payloads: mounts · Boot-time logic stages bundled assets into the system view.
- Rollback path → System payloads: removes · Cleanup path rolls back shipped assets.
- Zygisk hook → Shared spoofing: shares · Zygisk hook uses common spoofing logic.
- Zygisk hook → Target rules: shares · Zygisk hook uses target-selection logic.
- Riru hook → Shared spoofing: reuses · Riru hook shares runtime spoofing behavior.
- Shared spoofing → Target rules: coordinates · Shared logic delegates to package-specific rules.
- Zygisk hook → Boot service: complements · Native hooks work alongside boot-time module setup.
- Riru hook → Boot service: complements · Riru hook complements the shell-based control plane.
- Hotword pack → System payloads: adds · Optional pack contributes privileged APKs and permissions.
- Now Playing → System payloads: adds · Now Playing pack contributes overlay and firmware files.
