# crimera/piko architecture

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

- Interactive diagram: https://gitdiagram.com/crimera/piko
- Repository: https://github.com/crimera/piko

## Overview

#### Purpose and Entry Points
Piko is a Morphe patch bundle for modifying Android X/Twitter and Instagram APKM packages. It is not a standalone app: Morphe Manager or CLI loads the built bundle, selects compatible patches, rewrites a target APKM, and installs the resulting app. Build/module entry points are `settings.gradle.kts`, `build.gradle.kts`, and `patches/build.gradle.kts`; published patch metadata is `patches-bundle.json` and `patches-list.json`.

#### Patch Authoring Layer
Kotlin patch definitions locate target-app bytecode/resources through fingerprints and inject hooks, code, or resources. Instagram and X are separate patch domains:
- `patches/src/main/kotlin/app/crimera/patches/instagram/misc/extension/SharedExtensionPatch.kt`
- `patches/src/main/kotlin/app/crimera/patches/twitter/misc/extension/ExtensionPatch.kt`
- `patches/src/main/kotlin/app/crimera/patches/twitter/ads/timelineEntryHook/TimelineEntryHookPatch.kt`

Feature patches commonly depend on foundational entity, settings, resource, or extension patches rather than directly communicating with one another.

#### Runtime Extension Injection
The patch layer embeds and invokes Android Java extension code inside the patched target process. App initialization hooks establish this boundary; injected code then interacts with target UI/model classes and Android APIs.
- Instagram bootstrap: `patches/src/main/kotlin/app/crimera/patches/instagram/misc/extension/hooks/ApplicationInitHook.kt`
- Instagram runtime: `extensions/instagram/src/main/java/app/morphe/extension/instagram/patches/`
- X runtime: `extensions/twitter/src/main/java/app/morphe/extension/twitter/patches/`

This is the critical compatibility boundary: Kotlin patches target version-specific, often obfuscated app bytecode, while Java extensions execute against the patched app at runtime.

#### Target-Specific Data and UI Hooks
Entity-generation patches expose otherwise internal Instagram/X objects to extension code; UI patches add settings, menus, buttons, timeline filtering, media actions, and privacy behavior. Examples:
- Instagram media/entity bridge: `patches/src/main/kotlin/app/crimera/patches/instagram/entity/mediadata/MediaDataEntity.kt`
- Instagram download runtime: `extensions/instagram/src/main/java/app/morphe/extension/instagram/patches/download/DownloadUtils.java`
- X tweet/entity bridge: `patches/src/main/kotlin/app/crimera/patches/twitter/entity/TweetEntityPatch.kt`
- X native download runtime: `extensions/twitter/src/main/java/app/morphe/extension/twitter/patches/nativeFeatures/downloader/NativeDownloader.java`

Typical flow: fingerprint target method → inject call/hook → extension receives target data → applies preferences/logic → alters UI, network-related behavior, or local media handling.

#### Settings, Resources, and Persistence
Settings patches inject entry points/resources into target apps; extension activities/fragments render controls and persist choices. Shared preferences and backup/restore are runtime-local to the patched application.
- Instagram settings injection: `patches/src/main/kotlin/app/crimera/patches/instagram/misc/settings/SettingsPatch.kt`
- X settings runtime: `extensions/twitter/src/main/java/app/morphe/extension/twitter/settings/Settings.java`
- Local preference abstraction: `extensions/shared/library/src/main/java/app/morphe/extension/crimera/SharedPref.java`
- Localized injected resources: `patches/src/main/resources/addresources/values/twitter/strings.xml`

#### Shared Library and Compile-Time Stubs
`extensions/shared/library` supplies reusable downloader, settings, crash, storage, and request functionality used by target extensions. Stub modules provide compile-time declarations for classes owned by Instagram/X/Material; they are compatibility scaffolding, not bundled replacements.
- Shared downloader: `extensions/shared/library/src/main/java/app/morphe/extension/crimera/downloader/MediaDownloader.java`
- HTTP abstraction: `extensions/shared/library/src/main/java/app/morphe/extension/shared/requests/Requester.java`
- X stubs: `extensions/twitter/stub/src/main/java/`
- Instagram stubs: `extensions/instagram/stub/src/main/java/`

#### Build, Distribution, and External Dependencies
The project is Gradle-based Kotlin/Java Android patch code, consumed by the Morphe patching runtime. GitHub Actions builds/releases artifacts; Crowdin workflows synchronize translations. External operational dependencies are Morphe (patch application), original APKM inputs (typically ApkMirror), target-app backends, optional translation providers in the X extension, and Piko-Shim for newer X compatibility.
- Release automation: `.github/workflows/release.yml`
- Translation configuration: `crowdin.yml`
- Version mapping references: `docs/mappings/435.0.0.37.76.json`

Main entry points: [`extensions/instagram/src/main/java/app/morphe/extension/instagram/patches/download/DownloadUtils.java`](https://github.com/crimera/piko/blob/main/extensions/instagram/src/main/java/app/morphe/extension/instagram/patches/download/DownloadUtils.java) (Instagram extension runtime), [`extensions/twitter/src/main/java/app/morphe/extension/twitter/patches/TimelineEntry.java`](https://github.com/crimera/piko/blob/main/extensions/twitter/src/main/java/app/morphe/extension/twitter/patches/TimelineEntry.java) (X extension runtime), [`patches/src/main/kotlin/app/crimera/patches/twitter/entity/TweetEntityPatch.kt`](https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/twitter/entity/TweetEntityPatch.kt) (Entity bridges), [`patches/src/main/kotlin/app/crimera/patches/instagram/misc/extension/SharedExtensionPatch.kt`](https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/instagram/misc/extension/SharedExtensionPatch.kt) (Instagram patch definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build &amp; Distribution"]
  node_gradle["Gradle build<br/>[build.gradle.kts]"]
  node_patch_module["Patches module<br/>Gradle module<br/>[build.gradle.kts]"]
  node_bundle_metadata["Patch bundle metadata<br/>published metadata"]
  node_release["Release workflow<br/>GitHub Actions<br/>[release.yml]"]
end

subgraph group_patches["Patch Authoring"]
  node_instagram_patches["Instagram patch definitions<br/>Kotlin patches"]
  node_x_patches["X patch definitions<br/>Kotlin patches<br/>[ExtensionPatch.kt]"]
  node_entity_bridges["Entity bridges<br/>injected hooks"]
  node_settings_resources["Settings &amp; resources injection<br/>injected UI<br/>[SettingsPatch.kt]"]
  node_instagram_bootstrap["Instagram initialization hook<br/>bootstrap patch"]
end

subgraph group_runtime["Injected Runtime"]
  node_instagram_runtime["Instagram extension runtime<br/>Java runtime<br/>[DownloadUtils.java]"]
  node_x_runtime["X extension runtime<br/>Java runtime<br/>[TimelineEntry.java]"]
  node_shared_library["Shared extension library<br/>Java library"]
  node_preferences[("Runtime preferences<br/>local persistence<br/>[SharedPref.java]")]
  node_compile_stubs["Target API stubs<br/>compile-time scaffolding<br/>[JsonApiTweet.java]"]
end

subgraph group_external["External Systems"]
  node_morphe{{"Morphe Manager / CLI<br/>patching runtime"}}
  node_input_apkm["Original Instagram / X APKM<br/>target package"]
  node_patched_app["Patched installed app<br/>Android application"]
  node_target_backends["Target backends &amp; Android APIs<br/>external platform"]
end

node_gradle -->|"builds"| node_patch_module
node_patch_module -->|"publishes"| node_bundle_metadata
node_release -->|"releases"| node_bundle_metadata
node_instagram_patches -->|"included in"| node_patch_module
node_x_patches -->|"included in"| node_patch_module
node_entity_bridges -.->|"foundation for features"| node_instagram_patches
node_entity_bridges -.->|"foundation for features"| node_x_patches
node_settings_resources -.->|"supports features"| node_instagram_patches
node_settings_resources -.->|"supports features"| node_x_patches
node_instagram_bootstrap -->|"initializes"| node_instagram_runtime
node_instagram_patches -->|"embeds and invokes"| node_instagram_runtime
node_x_patches -->|"embeds and invokes"| node_x_runtime
node_entity_bridges -->|"passes target data"| node_instagram_runtime
node_entity_bridges -->|"passes target data"| node_x_runtime
node_instagram_runtime -->|"uses"| node_shared_library
node_x_runtime -->|"uses"| node_shared_library
node_instagram_runtime -->|"persists settings"| node_preferences
node_x_runtime -->|"persists settings"| node_preferences
node_compile_stubs -.->|"compiles against"| node_instagram_runtime
node_compile_stubs -.->|"compiles against"| node_x_runtime
node_bundle_metadata -->|"loaded by"| node_morphe
node_input_apkm -->|"patch input"| node_morphe
node_morphe -->|"rewrites and installs"| node_patched_app
node_patched_app -->|"interacts with"| node_target_backends

click node_gradle "https://github.com/crimera/piko/blob/main/build.gradle.kts"
click node_patch_module "https://github.com/crimera/piko/blob/main/patches/build.gradle.kts"
click node_bundle_metadata "https://github.com/crimera/piko/blob/main/patches-bundle.json"
click node_release "https://github.com/crimera/piko/blob/main/.github/workflows/release.yml"
click node_instagram_patches "https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/instagram/misc/extension/SharedExtensionPatch.kt"
click node_x_patches "https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/twitter/misc/extension/ExtensionPatch.kt"
click node_entity_bridges "https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/twitter/entity/TweetEntityPatch.kt"
click node_settings_resources "https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/instagram/misc/settings/SettingsPatch.kt"
click node_instagram_bootstrap "https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/instagram/misc/extension/hooks/ApplicationInitHook.kt"
click node_instagram_runtime "https://github.com/crimera/piko/blob/main/extensions/instagram/src/main/java/app/morphe/extension/instagram/patches/download/DownloadUtils.java"
click node_x_runtime "https://github.com/crimera/piko/blob/main/extensions/twitter/src/main/java/app/morphe/extension/twitter/patches/TimelineEntry.java"
click node_shared_library "https://github.com/crimera/piko/blob/main/extensions/shared/library/src/main/java/app/morphe/extension/crimera/downloader/MediaDownloader.java"
click node_preferences "https://github.com/crimera/piko/blob/main/extensions/shared/library/src/main/java/app/morphe/extension/crimera/SharedPref.java"
click node_compile_stubs "https://github.com/crimera/piko/blob/main/extensions/twitter/stub/src/main/java/com/twitter/api/model/json/core/JsonApiTweet.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_gradle,node_patch_module,node_bundle_metadata,node_release toneBlue
class node_instagram_patches,node_x_patches,node_entity_bridges,node_settings_resources,node_instagram_bootstrap toneAmber
class node_instagram_runtime,node_x_runtime,node_shared_library,node_preferences,node_compile_stubs toneMint
class node_morphe,node_input_apkm,node_patched_app,node_target_backends toneRose
```

## Components

### Build & Distribution

- [Gradle build](https://github.com/crimera/piko/blob/main/build.gradle.kts): build · Builds Kotlin patches and Java extension artifacts. · `build.gradle.kts`
- [Patches module](https://github.com/crimera/piko/blob/main/patches/build.gradle.kts): Gradle module · `patches/build.gradle.kts`
- [Patch bundle metadata](https://github.com/crimera/piko/blob/main/patches-bundle.json): published metadata · `patches-bundle.json`
- [Release workflow](https://github.com/crimera/piko/blob/main/.github/workflows/release.yml): GitHub Actions · `.github/workflows/release.yml`

### Patch Authoring

- [Instagram patch definitions](https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/instagram/misc/extension/SharedExtensionPatch.kt): Kotlin patches · Fingerprints and rewrites Instagram bytecode/resources. · `patches/src/main/kotlin/app/crimera/patches/instagram/misc/extension/SharedExtensionPatch.kt`
- [X patch definitions](https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/twitter/misc/extension/ExtensionPatch.kt): Kotlin patches · Fingerprints and rewrites X bytecode/resources. · `patches/src/main/kotlin/app/crimera/patches/twitter/misc/extension/ExtensionPatch.kt`
- [Entity bridges](https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/twitter/entity/TweetEntityPatch.kt): injected hooks · Expose target app objects to extension code. · `patches/src/main/kotlin/app/crimera/patches/twitter/entity/TweetEntityPatch.kt`
- [Settings & resources injection](https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/instagram/misc/settings/SettingsPatch.kt): injected UI · Adds settings entry points and localized target resources. · `patches/src/main/kotlin/app/crimera/patches/instagram/misc/settings/SettingsPatch.kt`
- [Instagram initialization hook](https://github.com/crimera/piko/blob/main/patches/src/main/kotlin/app/crimera/patches/instagram/misc/extension/hooks/ApplicationInitHook.kt): bootstrap patch · Establishes the patched-process extension boundary. · `patches/src/main/kotlin/app/crimera/patches/instagram/misc/extension/hooks/ApplicationInitHook.kt`

### Injected Runtime

- [Instagram extension runtime](https://github.com/crimera/piko/blob/main/extensions/instagram/src/main/java/app/morphe/extension/instagram/patches/download/DownloadUtils.java): Java runtime · Runs injected features inside Instagram. · `extensions/instagram/src/main/java/app/morphe/extension/instagram/patches/download/DownloadUtils.java`
- [X extension runtime](https://github.com/crimera/piko/blob/main/extensions/twitter/src/main/java/app/morphe/extension/twitter/patches/TimelineEntry.java): Java runtime · Runs injected features inside X. · `extensions/twitter/src/main/java/app/morphe/extension/twitter/patches/TimelineEntry.java`
- [Shared extension library](https://github.com/crimera/piko/blob/main/extensions/shared/library/src/main/java/app/morphe/extension/crimera/downloader/MediaDownloader.java): Java library · Provides preferences, downloads, storage, crash, and request support. · `extensions/shared/library/src/main/java/app/morphe/extension/crimera/downloader/MediaDownloader.java`
- [Runtime preferences](https://github.com/crimera/piko/blob/main/extensions/shared/library/src/main/java/app/morphe/extension/crimera/SharedPref.java): local persistence · Stores settings and backup data in the patched app. · `extensions/shared/library/src/main/java/app/morphe/extension/crimera/SharedPref.java`
- [Target API stubs](https://github.com/crimera/piko/blob/main/extensions/twitter/stub/src/main/java/com/twitter/api/model/json/core/JsonApiTweet.java): compile-time scaffolding · Declarations for target-owned classes; not replacement runtime code. · `extensions/twitter/stub/src/main/java/com/twitter/api/model/json/core/JsonApiTweet.java`

### External Systems

- **Morphe Manager / CLI**: patching runtime · Selects compatible patches and rewrites APKM inputs.
- **Original Instagram / X APKM**: target package
- **Patched installed app**: Android application · Hosts injected extensions and retains local runtime state.
- **Target backends & Android APIs**: external platform · Runtime hooks can affect UI, network behavior, and media handling.

## Connections

- Gradle build → Patches module: builds
- Patches module → Patch bundle metadata: publishes
- Release workflow → Patch bundle metadata: releases
- Instagram patch definitions → Patches module: included in
- X patch definitions → Patches module: included in
- Entity bridges → Instagram patch definitions: foundation for features
- Entity bridges → X patch definitions: foundation for features
- Settings & resources injection → Instagram patch definitions: supports features
- Settings & resources injection → X patch definitions: supports features
- Instagram initialization hook → Instagram extension runtime: initializes
- Instagram patch definitions → Instagram extension runtime: embeds and invokes
- X patch definitions → X extension runtime: embeds and invokes
- Entity bridges → Instagram extension runtime: passes target data
- Entity bridges → X extension runtime: passes target data
- Instagram extension runtime → Shared extension library: uses
- X extension runtime → Shared extension library: uses
- Instagram extension runtime → Runtime preferences: persists settings
- X extension runtime → Runtime preferences: persists settings
- Target API stubs → Instagram extension runtime: compiles against
- Target API stubs → X extension runtime: compiles against
- Patch bundle metadata → Morphe Manager / CLI: loaded by
- Original Instagram / X APKM → Morphe Manager / CLI: patch input
- Morphe Manager / CLI → Patched installed app: rewrites and installs
- Patched installed app → Target backends & Android APIs: interacts with
