# canhub/android-image-cropper architecture

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

- Interactive diagram: https://gitdiagram.com/canhub/android-image-cropper
- Repository: https://github.com/canhub/android-image-cropper

## Overview

##### Main Components
- Library Module ("cropper"):
- Core Business Logic: This includes the classes that perform the actual cropping. For instance, the asynchronous worker jobs (BitmapCroppingWorkerJob and BitmapLoadingWorkerJob) handle the heavy lifting in the background.
- UI Components: Elements like CropImageView, CropImageActivity, CropOverlayView, and dialog components for picking image sources are implemented in Kotlin under the cropper directory.
- Utility Classes: Files like BitmapUtils, ParcelableUtils, and the methods in the “utils” package manage image file paths, permissions, and various helper routines.
- Exception Handling: Classes such as CropException provide error management logic.
- Resource Management: Located under src/main/res, they include layouts, drawables, values (strings, attrs), and XML configuration for file paths.
- Sample Application ("sample"):
- Entry Points: MainActivity, SampleApplication, and other fragments such as SampleCropFragment, SampleCustomActivity, and SampleUsingImageViewFragment illustrate different ways of invoking the crop functionality.
- Build/Configuration Components:
- Gradle Scripts: Both build.gradle.kts and settings.gradle.kts are used to manage the build process for both the cropper library and the sample app.
- CI/CD and Deployment: The .github/workflows directory includes files for building, publishing releases, and snapshots.

##### Relationships and Interactions
- The cropper library’s core components interact in a modular way:
- The UI components (CropImageView and CropImageActivity) serve as the front end interfaces for image cropping.
- Utility classes and asynchronous worker jobs support the main components ensuring image processing tasks run efficiently in the background.
- The Activity Contracts and intents (as depicted in the README’s sample code) show dialogs and navigation flows for various approaches (direct crop calls, using a custom CropImageView, or extending crop activity).
- The sample application acts as a client for the library. It demonstrates different usage patterns — directly calling crop, embedding the CropImageView in custom activities, or extending default activities.
- The build tools and configuration files ensure that the library is properly integrated and versioned for adoption via Maven repositories or other dependency management systems.

##### Architectural Patterns and Design Principles
- Modularization: The clear separation between the library and the sample app shows a design that promotes reusability and isolation of concerns.
- Asynchronous Processing: The use of worker jobs for cropping and image loading indicates an architecture that offloads intensive processing to background threads.
- Customizability: The design supports multiple patterns for integration (direct crop calls, using embedded views, extending activities) which reflects a flexible and extensible architecture.
- Android Componentization: Everything is built as Android components (activities, views, resources) following best practices in Android UI/UX and application structure.

##### Relevant Technologies, Frameworks, and Tools
- Android SDK and Lifecycle (Activities, Fragments, Views).
- Kotlin as the programming language for all business logic and UI components.
- Gradle for build configuration and project dependency management.
- GitHub Actions for CI/CD (as seen in the workflows) and sample projects that show integration.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Sample Application Layer
    subgraph "Sample Application"
        SA1["MainActivity"]:::ui
        SA2["SampleApplication"]:::ui
        SA3["SampleCropFragment"]:::ui
        SA4["SampleCustomActivity"]:::ui
        SA5["SampleUsingImageViewFragment"]:::ui
        SA6["UI & Layout Files"]:::resource
    end

    %% Cropper Library Layer
    subgraph "Cropper Library"
        %% Core Business Logic
        subgraph "Core Business Logic"
            CL1["BitmapCroppingWorkerJob"]:::worker
            CL2["BitmapLoadingWorkerJob"]:::worker
        end

        %% UI Components
        subgraph "UI Components"
            UI1["CropImageActivity"]:::ui
            UI2["CropImageView"]:::ui
            UI3["CropOverlayView"]:::ui
        end

        %% Utility Classes
        subgraph "Utility Classes"
            UT1["BitmapUtils"]:::util
            UT2["ParcelableUtils"]:::util
            UT3["Additional Utilities (GetFilePathFromUri,GetUriForFile)"]:::util
        end

        %% Exception Handling
        subgraph "Exception Handling"
            EX1["CropException"]:::exception
        end

        %% Resource Management
        subgraph "Resource Management"
            RS1["Resources (layouts,drawables,values)"]:::resource
        end
    end

    %% Build & CI/CD Layer
    subgraph "Build & CI/CD"
        BC1["Gradle Scripts"]:::build
        BC2["CI/CD Workflows"]:::build
    end

    %% Relationships between Sample Application and Cropper Library UI
    SA1 -->|"invokes"| UI1
    SA1 -->|"embeds"| UI2
    SA3 -->|"invokes"| UI1
    SA4 -->|"extends"| UI1
    SA5 -->|"embeds"| UI2

    %% Relationship from Sample Application Resources to Cropper Library Resources
    SA6 -->|"configures"| RS1

    %% Relationships inside Cropper Library (UI triggers asynchronous processing)
    UI1 -->|"triggers"| CL1
    UI1 -->|"triggers"| CL2

    %% UI Components use Utility Classes
    UI1 -->|"uses"| UT1
    UI1 -->|"uses"| UT2
    UI2 -->|"uses"| UT3

    %% Build & CI/CD involvement
    BC1 ---|"builds"| SA1
    BC1 ---|"builds"| UI1

    %% Class Definitions for Colors
    classDef ui fill:#91d1e3,stroke:#333,stroke-width:1px;
    classDef worker fill:#f9d5e5,stroke:#333,stroke-width:1px;
    classDef util fill:#fef3bd,stroke:#333,stroke-width:1px;
    classDef exception fill:#ffddcc,stroke:#333,stroke-width:1px;
    classDef resource fill:#dcedc1,stroke:#333,stroke-width:1px;
    classDef build fill:#c1d7f6,stroke:#333,stroke-width:1px;

    %% Click Events for Cropper Library - Core Business Logic
    click CL1 "https://github.com/canhub/android-image-cropper/blob/main/cropper/src/main/kotlin/com/canhub/cropper/BitmapCroppingWorkerJob.kt"
    click CL2 "https://github.com/canhub/android-image-cropper/blob/main/cropper/src/main/kotlin/com/canhub/cropper/BitmapLoadingWorkerJob.kt"

    %% Click Events for Cropper Library - UI Components
    click UI1 "https://github.com/canhub/android-image-cropper/blob/main/cropper/src/main/kotlin/com/canhub/cropper/CropImageActivity.kt"
    click UI2 "https://github.com/canhub/android-image-cropper/blob/main/cropper/src/main/kotlin/com/canhub/cropper/CropImageView.kt"
    click UI3 "https://github.com/canhub/android-image-cropper/blob/main/cropper/src/main/kotlin/com/canhub/cropper/CropOverlayView.kt"

    %% Click Events for Cropper Library - Utility Classes
    click UT1 "https://github.com/canhub/android-image-cropper/blob/main/cropper/src/main/kotlin/com/canhub/cropper/BitmapUtils.kt"
    click UT2 "https://github.com/canhub/android-image-cropper/blob/main/cropper/src/main/kotlin/com/canhub/cropper/ParcelableUtils.kt"
    click UT3 "https://github.com/canhub/android-image-cropper/tree/main/cropper/src/main/kotlin/com/canhub/cropper/utils"

    %% Click Event for Cropper Library - Exception Handling
    click EX1 "https://github.com/canhub/android-image-cropper/blob/main/cropper/src/main/kotlin/com/canhub/cropper/CropException.kt"

    %% Click Event for Cropper Library - Resource Management
    click RS1 "https://github.com/canhub/android-image-cropper/tree/main/cropper/src/main/res"

    %% Click Events for Sample Application
    click SA1 "https://github.com/canhub/android-image-cropper/blob/main/sample/src/main/kotlin/com/canhub/cropper/sample/MainActivity.kt"
    click SA2 "https://github.com/canhub/android-image-cropper/blob/main/sample/src/main/kotlin/com/canhub/cropper/sample/SampleApplication.kt"
    click SA3 "https://github.com/canhub/android-image-cropper/blob/main/sample/src/main/kotlin/com/canhub/cropper/sample/SampleCropFragment.kt"
    click SA4 "https://github.com/canhub/android-image-cropper/blob/main/sample/src/main/kotlin/com/canhub/cropper/sample/SampleCustomActivity.kt"
    click SA5 "https://github.com/canhub/android-image-cropper/blob/main/sample/src/main/kotlin/com/canhub/cropper/sample/SampleUsingImageViewFragment.kt"
    click SA6 "https://github.com/canhub/android-image-cropper/tree/main/sample/src/main/res"

    %% Click Events for Build/Configuration Components
    click BC1 "https://github.com/canhub/android-image-cropper/blob/main/build.gradle.kts"
    click BC2 "https://github.com/canhub/android-image-cropper/tree/main/.github/workflows"
```
