# hnvn/flutter_image_cropper architecture

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

- Interactive diagram: https://gitdiagram.com/hnvn/flutter_image_cropper
- Repository: https://github.com/hnvn/flutter_image_cropper

## Overview

##### Project Type and Purpose
- This is a multi‐platform Flutter plugin (package) that exposes a single Dart API—`ImageCropper().cropImage(...)`—but delegates actual image cropping to three separate native libraries:
- Android – uCrop (Java/Kotlin)
- iOS – TOCropViewController (Objective-C/Swift)
- Web – Cropper.js (JavaScript)
- The repo is arranged as a Flutter “federated plugin” with three packages:
- `image_cropper_platform_interface` – the common Dart interface and MethodChannel abstraction
- `image_cropper` – the Android + iOS implementation
- `image_cropper_for_web` – the Web implementation
- plus example apps under each package’s `example/` folder.

##### High-Level File Structure
- Top‐level packages:
- `image_cropper_platform_interface/`
- `image_cropper/` (contains native `android/` and `ios/` folders plus the host Dart wrapper)
- `image_cropper_for_web/`
- Each package has its own `pubspec.yaml`, `README.md`, and tests/examples.

##### Key Architectural Patterns
- Federated Plugin: a “platform interface” package defines an abstract API and registers implementations by platform.
- MethodChannel: Dart ↔ native messaging on Android/iOS
- JS Interop: Dart ↔ JavaScript interop on Web
- Delegation Pattern: the Dart facade (`ImageCropper` in `image_cropper.dart`) delegates to the platform interface, which finds the right platform implementation.

##### Main Components
- Flutter Application Layer
- Your Flutter UI code (example or host app)
- `image_cropper` Dart API façade
- Platform Interface Layer
- `ImageCropperPlatform` abstract class (in `image_cropper_platform_interface`)
- MethodChannel dispatcher (default implementation)
- Android Native Layer
- `MethodChannelImageCropper` (Java)
- uCrop library (external)
- AndroidManifest, Gradle build system
- iOS Native Layer
- `FLTImageCropperPlugin` (Objective-C/Swift)
- TOCropViewController (external)
- CocoaPods / Xcode project
- Web Layer
- `ImageCropperForWeb` (Dart)
- `cropperjs` (external JS)
- dart:js interop
- Storage / File System
- Temporary cache on Android (cache dir)
- NSTemporaryDirectory on iOS

##### Architectural Patterns & Principles to Highlight
- Separation of concerns (Dart API vs. native code vs. JS code)
- Platform‐agnostic interface vs. platform‐specific implementations
- Plugin registration and federated plugin pattern

##### Essential Elements
- Clear, descriptive labels for each component/class

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Flutter Application Layer
    subgraph "Flutter Application Layer"
        direction TB
        AppMobile["Example App (mobile)"]:::frontend
        AppWeb["Example App (web)"]:::frontend
    end

    %% Dart API Layer
    subgraph "Dart API Facade" 
        direction TB
        ImageCropperFacade["ImageCropper"]:::dart
        CropperSrc["src/cropper.dart"]:::dart
    end

    %% Platform Interface Layer
    subgraph "Platform Interface" 
        direction TB
        ImageCropperPlatform["ImageCropperPlatform (abstract)"]:::interface
        MethodChannelDispatcher["MethodChannelImageCropper (default)"]:::interface
        subgraph "Models" 
            direction TB
            CroppedFileBase["CroppedFile Base"]:::model
            CroppedFileIO["CroppedFile IO"]:::model
            CroppedFileHTML["CroppedFile HTML"]:::model
            CroppedFileUnsupported["CroppedFile Unsupported"]:::model
            Settings["Settings"]:::model
        end
    end

    %% Android Native Layer
    subgraph "Android Native Layer" 
        direction TB
        AndroidPlugin["ImageCropperPlugin.java"]:::android
        AndroidDelegate["ImageCropperDelegate.java"]:::android
        FileUtils["FileUtils.java"]:::android
        AndroidManifest["AndroidManifest.xml"]:::android
        GradleConfig["build.gradle"]:::android
        uCrop["uCrop Library"]:::external
    end

    %% iOS Native Layer
    subgraph "iOS Native Layer" 
        direction TB
        IOSPluginSrc["FLTImageCropperPlugin.m/.h"]:::ios
        PackageSwift["Package.swift"]:::ios
        Podspec["image_cropper.podspec"]:::ios
        TOCrop["TOCropViewController"]:::external
    end

    %% Web Layer
    subgraph "Web Layer"
        direction TB
        WebWrapper["ImageCropperForWeb"]:::web
        CropperPage["cropper_page.dart"]:::web
        CropperDialog["cropper_dialog.dart"]:::web
        CropperActionbar["cropper_actionbar.dart"]:::web
        Interop["cropper_interop.dart"]:::web
        CropperJS["cropper.js"]:::external
    end

    %% Pubspec & READMEs
    subgraph "Package Configurations"
        direction TB
        PubPlatform["platform_interface/pubspec.yaml\nREADME.md"]:::config
        PubMobile["image_cropper/pubspec.yaml\nREADME.md"]:::config
        PubWeb["image_cropper_for_web/pubspec.yaml\nREADME.md"]:::config
    end

    %% Connections - Flutter to Dart API
    AppMobile -->|"calls cropImage()"| ImageCropperFacade
    AppWeb -->|"calls cropImage()"| WebWrapper

    %% Dart API to Platform Interface
    ImageCropperFacade -->|"forwards to"| ImageCropperPlatform
    CropperSrc --> ImageCropperFacade

    %% Interface to Dispatcher
    ImageCropperPlatform -->|"default implementation"| MethodChannelDispatcher

    %% Dispatcher to Native Layers
    MethodChannelDispatcher -->|"MethodChannel"| AndroidPlugin
    MethodChannelDispatcher -->|"MethodChannel"| IOSPluginSrc

    %% Android Native to external
    AndroidPlugin -->|"invokes"| uCrop
    uCrop -->|"returns image path"| MethodChannelDispatcher

    %% iOS Native to external
    IOSPluginSrc -->|"invokes"| TOCrop
    TOCrop -->|"returns image path"| MethodChannelDispatcher

    %% Web flow
    WebWrapper -->|"JS interop"| Interop
    Interop -->|"opens UI"| CropperJS
    CropperJS -->|"returns Blob/dataURL"| WebWrapper
    WebWrapper --> CropperPage
    WebWrapper --> CropperDialog
    WebWrapper --> CropperActionbar

    %% Models usage
    MethodChannelDispatcher --> CroppedFileBase
    MethodChannelDispatcher --> Settings
    CroppedFileBase --> CroppedFileIO
    CroppedFileBase --> CroppedFileHTML
    CroppedFileBase --> CroppedFileUnsupported

    %% Pubspec dependencies
    AppMobile --> PubMobile
    AppWeb --> PubWeb
    ImageCropperFacade --> PubMobile
    ImageCropperPlatform --> PubPlatform

    %% Click Events
    click AppMobile "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper/example/lib/main.dart"
    click AppWeb "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_for_web/example/lib/main.dart"
    click ImageCropperFacade "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper/lib/image_cropper.dart"
    click CropperSrc "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper/lib/src/cropper.dart"
    click ImageCropperPlatform "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_platform_interface/lib/src/platform_interface/image_cropper_platform.dart"
    click MethodChannelDispatcher "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_platform_interface/lib/src/method_channel/method_channel_image_cropper.dart"
    click CroppedFileBase "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_platform_interface/lib/src/models/cropped_file/base.dart"
    click CroppedFileIO "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_platform_interface/lib/src/models/cropped_file/io.dart"
    click CroppedFileHTML "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_platform_interface/lib/src/models/cropped_file/html.dart"
    click CroppedFileUnsupported "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_platform_interface/lib/src/models/cropped_file/unsupported.dart"
    click Settings "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_platform_interface/lib/src/models/settings.dart"
    click AndroidPlugin "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper/android/src/main/java/vn/hunghd/flutter/plugins/imagecropper/ImageCropperPlugin.java"
    click AndroidDelegate "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper/android/src/main/java/vn/hunghd/flutter/plugins/imagecropper/ImageCropperDelegate.java"
    click FileUtils "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper/android/src/main/java/vn/hunghd/flutter/plugins/imagecropper/FileUtils.java"
    click AndroidManifest "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper/android/src/main/AndroidManifest.xml"
    click GradleConfig "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper/android/build.gradle"
    click IOSPluginSrc "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper/ios/image_cropper/Sources/image_cropper/FLTImageCropperPlugin.m"
    click PackageSwift "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper/ios/image_cropper/Package.swift"
    click Podspec "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper/ios/image_cropper.podspec"
    click WebWrapper "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_for_web/lib/image_cropper_for_web.dart"
    click CropperPage "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_for_web/lib/src/cropper_page.dart"
    click CropperDialog "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_for_web/lib/src/cropper_dialog.dart"
    click CropperActionbar "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_for_web/lib/src/cropper_actionbar.dart"
    click Interop "https://github.com/hnvn/flutter_image_cropper/blob/master/image_cropper_for_web/lib/src/interop/cropper_interop.dart"

    %% Styles
    classDef frontend fill:#D0E4F5,stroke:#0366D6,color:#0366D6;
    classDef dart fill:#CCE5FF,stroke:#0050EF,color:#0050EF;
    classDef interface fill:#E0F7FA,stroke:#00796B,color:#00796B;
    classDef model fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef android fill:#E8F5E9,stroke:#388E3C,color:#388E3C;
    classDef ios fill:#FFF8E1,stroke:#F57C00,color:#F57C00;
    classDef web fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A;
    classDef external fill:#EEEEEE,stroke:#9E9E9E,color:#616161,stroke-dasharray: 2 2;
    classDef config fill:#FAFAFA,stroke:#BDBDBD,color:#424242,stroke-dasharray: 2 2;
```
