# xmir64/shadow architecture

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

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

## Overview

##### Main Components
- Host Application: This is the container (or “host”) that integrates the plugin framework.
- Plugin Framework SDK: It includes multiple submodules such as:
– Core Modules (e.g., “core”, “common”, “runtime”): These handle fundamental functionalities like shadowing the standard Android components (Activity, Service, etc.), classloading, and resource management.
– Loader/Manager Modules (e.g., “loader”, “manager”, “activity-container”): Responsible for dynamically loading the plugin APKs, managing the plugin lifecycle, and delegating calls.
– Gradle Plugin & Transform Kit: Used at build time to instrument and package plugins by rewriting or transforming bytecode (e.g., “gradle-plugin”, “transform-kit”, “transform”). These components integrate with the build system, ensuring that plugin code and the framework co-evolve.
- Plugin APKs/Modules: Actual plugins (which are essentially independent APKs) that are loaded by the host. They include both plugin-specific code and parts of the plugin framework.
- Test & Sample Projects: “projects/sample” (demonstration host and plugin implementations) and “projects/test” which contain automated tests to validate compatibility with different Android configurations and dynamic behaviors.
- Code-Generation/Configuration Tools: Tools such as the code-generator and various gradle scripts (under “buildScripts”, “gradle”, etc.) that help set up, package, or configure the plugins and host.

##### Representing Relationships and Interactions
- That the Host Application includes a minimal “shadow” layer (around 15KB) that delegates to the Plugin Manager.
- How the Gradle Plugin/Transform Kit hooks into the build process: they transform the plugin APK code and incorporate parts of the shadow framework into the plugin packages.
- That the Plugin Loader is responsible for bridging Android’s classloader, resource, and component (Activity, Service, etc.) models between the host and the plugin.
- How test projects simulate and validate these interactions.

##### Architectural Patterns and Design Principles
- Minimal host impact – indicate that the host application integrates only a small “shadow” stub, relying on runtime delegation.
- Separation of concerns – group the SDK into modules (e.g., core functionality, classloading, resource management, and transformation) to emphasize modularity.
- Build-time instrumentation – show that the Gradle Plugin and Transformation tools are crucial in preparing plugins for runtime dynamic loading.

##### Relevant Technologies and Frameworks
- The framework is written partly in Kotlin (notably in “core.loader” and “core.transform”), so include that as a note.
- The Android platform and its standard component lifecycle are central.
- Gradle and associated build scripts are the backbone of packaging and dependency management.

##### Additional Elements
- That each component carries clear labels that capture both its name and its role.
- On potential external dependencies (for example, Gradle configurations, testing environments) as smaller “side” components if relevant.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-Time Layer
    subgraph "Build-Time Layer"
        GRADLE_PLUGIN["Gradle Plugin"]
        TRANSFORM_KIT["Transform Kit"]
        ADD_TRANSFORM["Additional Transformations"]
        CODE_GENERATOR["Code Generator"]
        BUILD_SCRIPTS["Build Scripts & Gradle Configuration"]
    end

    %% Runtime Framework Layer
    subgraph "Runtime Framework Layer"
        HOST_APP["Host Application\n(shadow stub)"]
        subgraph "Plugin Framework SDK"
            CORE["Core"]
            COMMON["Common"]
            RUNTIME_SDK["Runtime"]
            LOADER["Loader"]
            MANAGER["Manager"]
            ACTIVITY_CONTAINER["Activity Container"]
        end
    end

    %% Plugin Modules
    subgraph "Plugin Modules"
        SAMPLE_API["Sample Plugin API"]
        SAMPLE_APK["Sample Plugin APK"]
    end

    %% Test & Sample Projects
    subgraph "Test & Sample Projects"
        SAMPLE_PROJECTS["Sample Projects"]
        TEST_PROJECTS["Test Projects"]
    end

    %% Relationships in Runtime
    HOST_APP -->|"delegateTo"| MANAGER
    MANAGER -->|"callLoader"| LOADER
    LOADER -->|"loadPluginAPK"| SAMPLE_APK

    %% Internal Dependencies within Plugin Framework SDK
    CORE -->|"providesBase"| COMMON
    CORE -->|"supports"| RUNTIME_SDK
    CORE -->|"enables"| LOADER
    CORE -->|"enables"| MANAGER
    MANAGER -->|"utilizes"| ACTIVITY_CONTAINER

    %% Build-Time instrumentation on Plugin Modules
    GRADLE_PLUGIN -->|"instrument"| SAMPLE_APK
    TRANSFORM_KIT -->|"transform"| SAMPLE_APK
    ADD_TRANSFORM -->|"applyTransform"| SAMPLE_APK
    BUILD_SCRIPTS -->|"configure"| SAMPLE_APK

    %% Code generation impacting Build-Time Tools
    CODE_GENERATOR -->|"generatesConfig"| BUILD_SCRIPTS

    %% Test & Sample Projects interactions
    SAMPLE_PROJECTS -->|"demoIntegration"| HOST_APP
    TEST_PROJECTS -->|"validate"| HOST_APP

    %% Click Events
    click HOST_APP "https://github.com/xmir64/shadow/tree/master/projects/sample/dynamic-apk/sample-hello-host"
    click CORE "https://github.com/xmir64/shadow/tree/master/projects/sdk/core"
    click COMMON "https://github.com/xmir64/shadow/tree/master/projects/sdk/core/common"
    click RUNTIME_SDK "https://github.com/xmir64/shadow/tree/master/projects/sdk/core/runtime"
    click LOADER "https://github.com/xmir64/shadow/tree/master/projects/sdk/core/loader"
    click MANAGER "https://github.com/xmir64/shadow/tree/master/projects/sdk/core/manager"
    click ACTIVITY_CONTAINER "https://github.com/xmir64/shadow/tree/master/projects/sdk/core/activity-container"
    click GRADLE_PLUGIN "https://github.com/xmir64/shadow/tree/master/projects/sdk/core/gradle-plugin"
    click TRANSFORM_KIT "https://github.com/xmir64/shadow/tree/master/projects/sdk/core/transform-kit"
    click ADD_TRANSFORM "https://github.com/xmir64/shadow/tree/master/projects/sdk/core/transform"
    click SAMPLE_API "https://github.com/xmir64/shadow/tree/master/projects/sample/dynamic-apk/sample-hello-api"
    click SAMPLE_APK "https://github.com/xmir64/shadow/tree/master/projects/sample/dynamic-apk/sample-hello-apk"
    click SAMPLE_PROJECTS "https://github.com/xmir64/shadow/tree/master/projects/sample"
    click TEST_PROJECTS "https://github.com/xmir64/shadow/tree/master/projects/test"
    click CODE_GENERATOR "https://github.com/xmir64/shadow/tree/master/projects/sdk/coding/code-generator"
    click BUILD_SCRIPTS "https://github.com/xmir64/shadow/tree/master/buildScripts"

    %% Styles
    class GRADLE_PLUGIN,TRANSFORM_KIT,ADD_TRANSFORM,CODE_GENERATOR,BUILD_SCRIPTS buildNodes
    class HOST_APP host
    class CORE,COMMON,RUNTIME_SDK,LOADER,MANAGER,ACTIVITY_CONTAINER sdk
    class SAMPLE_API,SAMPLE_APK plugin
    class SAMPLE_PROJECTS,TEST_PROJECTS test

    classDef buildNodes fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef host fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef sdk fill:#FFFFE0,stroke:#000,stroke-width:1px;
    classDef plugin fill:#F08080,stroke:#000,stroke-width:1px;
    classDef test fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
