# jjolano/shadow architecture

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

- Interactive diagram: https://gitdiagram.com/jjolano/shadow
- Repository: https://github.com/jjolano/shadow

## Overview

##### Project type and purpose
- This is an iOS “tweak” — a jailbreak-detection bypass library that hooks into target apps at runtime. It consists of:
- A dynamic library (Shadow.dylib) loaded by a hooking engine (Substrate/Substitute or fishhook)
- A private framework (Shadow.framework) containing the core bypass logic, rulesets, and settings API
- A Settings bundle (ShadowSettings.bundle) to expose a configuration UI in Apple’s Settings app
- Build scripts, Makefiles, and Debian packaging metadata to assemble a .deb for Cydia/AltStore

##### File structure
- Top-level: Makefile, build.sh, common.h, control & layout for Debian packaging
- Shadow.dylib/…:
- hooks/ : X-code assembly stubs (.x) and headers to intercept Objective-C methods and syscalls
- layout/Library/libSandy : helper library for sandboxed preference loading
- Shadow.framework/…:
- Core.m, Backend.m, Utilities → business logic and rule evaluation
- Ruleset.m, Settings.m → load embedded .plist rule definitions, read user prefs
- layout/Library/Shadow/Rulesets : default rule files (StandardRules.plist, etc.)
- ShadowSettings.bundle/…:
- Resources/*.plist & .lproj : PreferenceLoader definitions for Settings.app UI
- Controller .m/.h files : table-view controllers for each screen
- shdw/: an executable entrypoint (CLI or diagnostic tool)

##### README for additional insights
- Confirms it’s a hook-based bypass for modern iOS jailbreak methods

##### Main components & their interactions
a. Components
1. Hooking Engine (Substrate/Substitute/fishhook)
2. Shadow.dylib (hook stubs)
3. Shadow.framework
– Core & Utilities
– Ruleset loader
– Settings API (reads /var/mobile/Library/Preferences/me.jjolano.shadow.plist)
4. Embedded Ruleset files (.plist)
5. iOS Settings App + ShadowSettings.bundle UI
6. Installer (dpkg) / control scripts (postinst triggers respring)
7. External Dependencies (libSandy, AltList, HookKit, RootBridge)
b. Relationships & Data flow
– At app launch, Hooking Engine injects Shadow.dylib → calls into Shadow.framework
– Shadow.framework intercepts detection calls (syscalls/Obj-C methods) → applies bypass logic from Ruleset
– Ruleset loader fetches built-in .plist files
– Settings API reads user preferences set via Settings.app UI
– Settings.bundle UI writes preferences → file watcher in framework picks up changes
– Installer writes all components into their target directories and triggers a device respring
c. Architectural patterns
– Plugin/Hook pipeline: decouples low-level hook stubs from high-level bypass logic
– MVC in Settings.bundle: plist model → controller .m files → table-view UI
– Configuration-as-data: .plist rulesets and preference files
d. Key technologies
– Assembly stubs (.x) for dyld/substrate hooking
– Objective-C framework code (.m/.h)
– plist for resource/config data
– Debian control files for packaging

##### Elements
- Installer (Debian packaging)
- Hooking engine & dependencies
- Shadow.dylib (hook stubs)
- Shadow.framework subcomponents (Core, Ruleset, Settings API)
- Settings.app + ShadowSettings.bundle (UI)
- Rule files (.plist) & Preferences file
- “Injects” / “Hooks” (engine → dylib)
- “Calls into” (dylib → framework)
- “Reads” (framework → .plist files / Preferences)
- “Writes” (Settings UI → Preferences)
- “Installs to” (Installer → device filesystem)
- Green for installer/build components
- Blue for runtime hooking components
- Yellow for configuration/UI components

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Installer / Packaging Layer
    subgraph "Installer / Packaging" 
        direction TB
        Makefile["Makefile"]:::installer
        BuildScript["build.sh"]:::installer
        Control["control"]:::installer
        Postinst["postinst"]:::installer
        Postrm["postrm"]:::installer
        Triggers["triggers"]:::installer
    end

    %% External Dependencies & Hooking Engine
    subgraph "Hooking Engine & Dependencies"
        direction TB
        HookEngine["Substrate/Substitute/fishhook"]:::external
        subgraph "Shadow.dylib" 
            direction TB
            DylibMake["Makefile"]:::runtime
            DylibEntry["dylib.x"]:::runtime
            HooksStubs["hooks/*.x & hooks.h"]:::runtime
            libSandy["libSandy (ShadowSettings.plist)"]:::runtime
        end
    end

    %% Runtime Injection Layer
    subgraph "Runtime in App Process"
        direction TB
        ShadowDylib["Shadow.dylib"]:::runtime
        subgraph "Shadow.framework"
            direction TB
            FrameworkMake["Makefile"]:::runtime
            InfoPlist["Info.plist"]:::runtime
            Core["Core & Utilities"]:::runtime
            Backend["Backend dispatch"]:::runtime
            RulesetLoader["Ruleset loader"]:::runtime
            SettingsAPI["Settings API"]:::runtime
            subgraph "Embedded Rulesets"
                direction TB
                StandardRules["StandardRules.plist"]:::runtime
                JailbreakMisc["JailbreakMisc.plist"]:::runtime
                dpkgInstalled["dpkgInstalled.plist"]:::runtime
            end
        end
        PrefsFile["/var/mobile/Library/Preferences/me.jjolano.shadow.plist"]:::runtime
    end

    %% Settings UI Layer
    subgraph "Settings App & UI"
        direction TB
        SettingsApp["iOS Settings.app"]:::config
        subgraph "ShadowSettings.bundle"
            direction TB
            BundleMake["Makefile"]:::config
            AboutPlist["About.plist"]:::config
            AppPlist["App.plist"]:::config
            HooksPlist["Hooks.plist"]:::config
            RootPlist["Root.plist"]:::config
            Controllers["Controllers (.h/.m)"]:::config
            PrefLoader["PreferenceLoader ShadowSettings.plist"]:::config
        end
    end

    %% Connections
    Makefile -->|installs to| ShadowDylib
    BuildScript -->|installs to| ShadowFramework
    Control -->|installs to| ShadowDylib
    Postinst -->|respring triggers| SettingsApp
    HookEngine -->|injects| DylibEntry
    DylibEntry -->|hooks| Core
    DylibEntry -->|hooks| Backend
    DylibEntry -->|hooks| RulesetLoader
    Core -->|calls into| Core
    ShadowDylib -->|loads| Shadow.framework
    RulesetLoader -->|reads| StandardRules
    RulesetLoader -->|reads| JailbreakMisc
    RulesetLoader -->|reads| dpkgInstalled
    SettingsAPI -->|reads| PrefsFile
    SettingsApp -->|writes| PrefsFile
    Controllers -->|driven by| PrefLoader

    %% Click Events
    click Makefile "https://github.com/jjolano/shadow/tree/master//Makefile"
    click BuildScript "https://github.com/jjolano/shadow/blob/master//build.sh"
    click Control "https://github.com/jjolano/shadow/tree/master//control"
    click Postinst "https://github.com/jjolano/shadow/tree/master//layout/DEBIAN/postinst"
    click Postrm "https://github.com/jjolano/shadow/tree/master//layout/DEBIAN/postrm"
    click Triggers "https://github.com/jjolano/shadow/tree/master//layout/DEBIAN/triggers"
    click DylibMake "https://github.com/jjolano/shadow/tree/master//Shadow.dylib/Makefile"
    click DylibEntry "https://github.com/jjolano/shadow/blob/master//Shadow.dylib/dylib.x"
    click HooksStubs "https://github.com/jjolano/shadow/blob/master//Shadow.dylib/hooks/hooks.h"
    click libSandy "https://github.com/jjolano/shadow/blob/master//Shadow.dylib/layout/Library/libSandy/ShadowSettings.plist"
    click FrameworkMake "https://github.com/jjolano/shadow/tree/master//Shadow.framework/Makefile"
    click InfoPlist "https://github.com/jjolano/shadow/blob/master//Shadow.framework/Resources/Info.plist"
    click Core "https://github.com/jjolano/shadow/blob/master//Shadow.framework/Core.m"
    click Backend "https://github.com/jjolano/shadow/blob/master//Shadow.framework/Backend.m"
    click RulesetLoader "https://github.com/jjolano/shadow/blob/master//Shadow.framework/Ruleset.m"
    click SettingsAPI "https://github.com/jjolano/shadow/blob/master//Shadow.framework/Settings.m"
    click StandardRules "https://github.com/jjolano/shadow/blob/master//Shadow.framework/layout/Library/Shadow/Rulesets/StandardRules.plist"
    click JailbreakMisc "https://github.com/jjolano/shadow/blob/master//Shadow.framework/layout/Library/Shadow/Rulesets/JailbreakMisc.plist"
    click dpkgInstalled "https://github.com/jjolano/shadow/blob/master//Shadow.framework/layout/Library/Shadow/Rulesets/dpkgInstalled.plist"
    click BundleMake "https://github.com/jjolano/shadow/tree/master//ShadowSettings.bundle/Makefile"
    click AboutPlist "https://github.com/jjolano/shadow/blob/master//ShadowSettings.bundle/Resources/About.plist"
    click AppPlist "https://github.com/jjolano/shadow/blob/master//ShadowSettings.bundle/Resources/App.plist"
    click HooksPlist "https://github.com/jjolano/shadow/blob/master//ShadowSettings.bundle/Resources/Hooks.plist"
    click RootPlist "https://github.com/jjolano/shadow/blob/master//ShadowSettings.bundle/Resources/Root.plist"
    click PrefLoader "https://github.com/jjolano/shadow/blob/master//ShadowSettings.bundle/layout/Library/PreferenceLoader/Preferences/ShadowSettings.plist"

    %% Styles
    classDef installer fill:#e0f7e0,stroke:#2e7d32,color:#2e7d32;
    classDef runtime fill:#e3f2fd,stroke:#1565c0,color:#1565c0;
    classDef config fill:#fff8e1,stroke:#f9a825,color:#f9a825;
    classDef external fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a;
```
