# opa334/choicy architecture

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

- Interactive diagram: https://gitdiagram.com/opa334/choicy
- Repository: https://github.com/opa334/choicy

## Overview

##### Main Components
- Preferences UI Module (ChoicyPrefs): This directory contains numerous .h and .m files along with its own Makefile and Resources. It is responsible for displaying configuration options, managing tweak configurations (global and per-process), and handling localization via multiple languages.
- SpringBoard/Sys Integration Module (ChoicySB): This part of the project involves integration with SpringBoard (see files like SpringBoard.h, runningboardd.x) and managing override behaviors (see ChoicyOverrideManager.h). It likely handles the actual injection/disabling of tweaks in the process lifecycle.
- Core Tweak Implementation (Tweak.c, Tweak.s, Shared.h/m): These files represent the fundamental embedding point for the tweak itself. They are where interposition or hook mechanisms are implemented (also via dyld_interpose.h) and integrate with external libraries (found in the external folder).
- External Dependencies: The “external” folder (with ChOma and litehook) suggests the project uses external hooking libraries/libraries to assist in the low-level interception of function calls.
- Packaging/Deployment Layout: The “layout” directory provides the structure for the DEBIAN packaging scripts and resource bundles (localizations in various languages) that bundle the application for installation.
- Utility and Build Scripts: The presence of build scripts (Makefile, release_build.sh, update_localizations.sh) and migration code (ChoicyPrefsMigrator) indicate support for packaging, versioning, and configuration migrations.

##### Relationships and Data Flow
- Preferences UI sends tweak configuration updates that, through shared settings (e.g., via plists or centralized data structures like Info.plist in resources), are consumed by the core tweak runtime.
- The Core Tweak Module, through its implementation in Tweak.c and the dyld interposing mechanism, modifies the behavior of the target system or processes – especially affecting SpringBoard functions via ChoicySB.
- External libraries such as litehook serve as helper modules within the core runtime, and they are used to intercept function calls or hook methods.
- The packaging/deployment structure (layout folder) is used to distribute these components together with the necessary configuration files, ensuring that the entire system is deployed as intended on iOS.

##### Architectural Patterns and Design Principles
- Modular Separation: There is a clear separation of concerns – UI (ChoicyPrefs), system integration (ChoicySB), and core functionalities (Tweak.c, Shared modules).
- Dynamic Hooking/Interposition: Use of dyld_interpose and external hooking libraries indicates that the system leverages dynamic runtime modification.
- Localization: The resources in layout indicate a commitment to multi-language support.
- Build and Deployment Automation: Utilization of Makefiles and shell scripts directs a controlled, script-driven build and packaging process.

##### Essential Architectural Elements
- Be very detailed in capturing how the UI alters system behavior (i.e., the configuration driven design) and which components are responsible for runtime modifications.
- External integrations and any build-time versus runtime components.

- The separation between the Preferences UI (for managing and configuring tweak settings) and the system integration (SpringBoard modifications).
- The core tweak engine employing dynamic interposition techniques supported by external libraries for configurable tweak injection behaviors.
- The packaging and build process that ties together the localized resources and deployment scripts.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    UI("Preferences UI (ChoicyPrefs)"):::ui
    subgraph "External Dependencies"
        extA("ChOma"):::external
        extB("litehook"):::external
    end
    core("Core Tweak Engine (Tweak.c, Tweak.s, dyld_interpose.h, Shared.h, Shared.m)"):::core
    SB("SpringBoard Module (ChoicySB) (SpringBoard.h, RunningBoard.h, runningboardd.x, ChoicyOverrideManager)"):::sys
    pack("Packaging & Localizations (layout/DEBIAN, Choicy.bundle)"):::packaging
    build("Build & Deployment (Makefile, release_build.sh, update_localizations.sh, ChoicyPrefsMigrator)"):::build

    UI -->|"configurationFlow"| core
    extA -->|"lowLevelHooks"| core
    extB -->|"lowLevelHooks"| core
    core -->|"hookSetup"| SB
    pack -->|"packageAssembly"| build

    click UI "https://github.com/opa334/choicy/tree/master/ChoicyPrefs/"
    click SB "https://github.com/opa334/choicy/tree/master/ChoicySB/"
    click core "https://github.com/opa334/choicy/blob/master/Tweak.c"
    click extA "https://github.com/opa334/choicy/tree/master/external/ChOma"
    click extB "https://github.com/opa334/choicy/tree/master/external/litehook"
    click pack "https://github.com/opa334/choicy/tree/master/layout/"
    click build "https://github.com/opa334/choicy/tree/master/Makefile"

    classDef ui fill:#AED6F1,stroke:#2471A3,stroke-width:2px
    classDef core fill:#82E0AA,stroke:#229954,stroke-width:2px
    classDef sys fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px
    classDef external fill:#F5B7B1,stroke:#CB4335,stroke-width:2px
    classDef packaging fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px
    classDef build fill:#FAD7A0,stroke:#D68910,stroke-width:2px
```
