# yalantis/ucrop architecture

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

- Interactive diagram: https://gitdiagram.com/yalantis/ucrop
- Repository: https://github.com/yalantis/ucrop

## Overview

##### Main Components
- Library Module (ucrop): This is the core image cropping functionality. It contains all of the Java classes organized under packages such as com.yalantis.ucrop, with sub-packages for callbacks, models, tasks, utilities, views, and widgets.
- Native Processing Module: Located under the jni folder (with corresponding native code, C++ files, and JNI libraries), this module provides enhanced (native) image processing capabilities.
- Sample Application: The “sample” module serves as a demo or sandbox for integration. It consists of manifest configurations, activities (e.g., BaseActivity, SampleActivity, ResultActivity), and resources that enable a live demonstration of the library’s functionality.
- Resources: Both the ucrop module and the sample include extensive resources (layouts, drawables, menus, animations, and strings) that are integral to the UI/UX.
- Build and Configuration Infrastructure: The Gradle build scripts and configuration files (e.g., build.gradle, settings.gradle, gradle.properties) orchestrate building, dependency management, and packaging for different Android versions and CPU architectures.

##### Relationships & Interactions
- Client Application Usage: External apps integrate uCrop by including the library project, adding its UCropActivity to their AndroidManifest.xml, and using the builder pattern (UCrop.of(...)) to configure and start the cropping process.
- UI Flow: The user interacts with the UCropActivity (and possibly UCropFragment) which is the primary entry point for image cropping. These UI components then interact with various internal SDK components.
- Business Logic & Async Tasks: Once the cropping process is triggered, tasks like BitmapCropTask and BitmapLoadTask process the image in the background. Callback interfaces (BitmapCropCallback, BitmapLoadCallback, etc.) relay completion and error notifications back to the UI.
- Native Code Integration: For users opting for enhanced image quality, the library exposes a native processing path via the JNI (uCrop.cpp, headers) and packaged native libraries (in the jniLibs directory). This module sits “under” the image processing tasks, providing fast, native bitmap manipulation.
- Configuration & Customization: The builder pattern via UCrop.Options allows developers to customize the cropping experience (aspect ratios, UI elements, gesture support, etc.). This customization cascades through the UI layer and image processing logic.

##### Architectural Patterns and Design Principles
- Layer Separation: Clearly differentiate between the presentation layer (Activities, Fragments, Views, Resources), the business logic (Tasks, Models, Callbacks), and the native processing layer.
- Builder Pattern: Notice that uCrop uses a builder approach to construct configuration options, which aims for flexibility and readability.
- Modular Design: The project splits the core library (ucrop) from the sample application, making it easier to update and test components independently.
- Asynchronous Processing: The cropping and image loading tasks execute on background threads, ensuring smooth UI performance.

##### Relevant Technologies & Frameworks
- Android SDK Components: Activities (UCropActivity), Fragments (UCropFragment), and various resources (layouts, drawables, animations).
- Gradle (and related configuration files): For build management and dependency resolutions.
- JNI/NDK for Native Code: Native libraries and C++ code for efficient image processing.
- Java: Core business logic and UI handling.
- Optional: Use of Material Design elements (as mentioned in the changelog) to modernize the interface.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global Entities
    CI["Client Integration"]:::external
    BC["Build & Config"]:::build
    SA["Sample Application"]:::sample

    %% uCrop Library Subgraph
    subgraph "uCrop Library"
        UO["UCrop Options"]:::config
        UA["UCropActivity"]:::ui
        UF["UCropFragment"]:::ui
        BCT["BitmapCropTask"]:::task
        BLT["BitmapLoadTask"]:::task
        BCC["BitmapCropCallback"]:::callback
        BLC["BitmapLoadCallback"]:::callback
    end

    %% Native Processing Module Subgraph
    subgraph "Native Processing Module"
        JNI["JNI Code"]:::native
        JNL["JNI Libraries"]:::native
    end

    %% Resources Subgraph
    subgraph "Resources"
        UCR["uCrop Resources"]:::resource
        SR["Sample Resources"]:::resource
    end

    %% Build and Configuration Subgraph
    subgraph "Build & Config"
        PRBS["Project Root Build Scripts"]:::build
        UBBS["uCrop Build Scripts"]:::build
    end

    %% Relationships
    CI -->|"usesBuilder"| UO
    UO -->|"configures"| UA
    UA -->|"manages"| UF
    UA -->|"triggers"| BCT
    UA -->|"triggers"| BLT
    BCT -->|"notifies"| BCC
    BLT -->|"notifies"| BLC
    BCT -->|"optimizes"| JNI
    BLT -->|"optimizes"| JNI
    SA -->|"demonstrates"| UA
    UA ---|"uses"| UCR
    SA ---|"uses"| SR
    BC -->|"builds"| UO
    BC -->|"builds"| SA

    %% Click Events
    click UO "https://github.com/yalantis/ucrop/tree/develop/ucrop/src/main/java/com/yalantis/ucrop"
    click UA "https://github.com/yalantis/ucrop/tree/develop/ucrop/src/main/java/com/yalantis/ucrop"
    click UF "https://github.com/yalantis/ucrop/tree/develop/ucrop/src/main/java/com/yalantis/ucrop"
    click BCT "https://github.com/yalantis/ucrop/tree/develop/ucrop/src/main/java/com/yalantis/ucrop"
    click BLT "https://github.com/yalantis/ucrop/tree/develop/ucrop/src/main/java/com/yalantis/ucrop"
    click JNI "https://github.com/yalantis/ucrop/tree/develop/ucrop/src/main/jni"
    click JNL "https://github.com/yalantis/ucrop/tree/develop/ucrop/src/main/jniLibs"
    click UCR "https://github.com/yalantis/ucrop/tree/develop/ucrop/src/main/res"
    click SR "https://github.com/yalantis/ucrop/tree/develop/sample/src/main/res"
    click SA "https://github.com/yalantis/ucrop/tree/develop/sample/src/main/java/com/yalantis/ucrop/sample"
    click PRBS "https://github.com/yalantis/ucrop/blob/develop/build.gradle"
    click UBBS "https://github.com/yalantis/ucrop/blob/develop/ucrop/build.gradle"

    %% Styles
    classDef external fill:#F0E68C,stroke:#B8860B,stroke-width:2px;
    classDef ui fill:#AEDFF7,stroke:#1E90FF,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef task fill:#F7D6AD,stroke:#DE8E00,stroke-width:2px,stroke-dasharray: 2, 2;
    classDef callback fill:#FFF5BA,stroke:#DAA520,stroke-width:2px;
    classDef config fill:#D0F0C0,stroke:#228B22,stroke-width:2px;
    classDef native fill:#C1E1C1,stroke:#008000,stroke-width:2px;
    classDef resource fill:#FFC0CB,stroke:#FF69B4,stroke-width:2px;
    classDef build fill:#E6E6FA,stroke:#6A5ACD,stroke-width:2px;
```
