# kekland/croppy architecture

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

- Interactive diagram: https://gitdiagram.com/kekland/croppy
- Repository: https://github.com/kekland/croppy

## Overview

##### Main Components
- Library Core (croppy package):
- Core logic and API: Located in the lib folder (e.g., lib/croppy.dart) and its src subdirectories.
- Image processing routines (crop, transform, rotate, scale, etc.), geometry calculations (lib/src/geometry), and utility functions (lib/src/utils).
- Controllers and Transformations:
- Controllers for handling user gestures and image transformations, along with mixins to add features (in lib/src/controller and its mixins and transformations folders).
- UI Components:
- Material and Cupertino specific widgets and pages (lib/src/widgets/material vs. lib/src/widgets/cupertino) that build the actual cropping UI.
- Common components for gesture detection and image viewing shared between these UI variations.
- FFI and native integrations:
- FFI bindings (in lib/src/ffi) provide native performance support, while alternative implementations (like for web – see lib/src/image/web_crop_image.dart) exist for platforms without FFI.
- Localization:
- Localization support components (lib/src/l10n) with language-specific resources.
- Platform-specific code:
- Android, iOS, macOS, Linux, and Windows directories contain wrappers and project files to integrate and test the Flutter package in native environments. They indicate that the library supports several native platforms.
- Example Application:
- The “example” folder gives a runnable app demonstration and includes platform-specific folders to show how the package is integrated.
- C/C++ Library Integration:
- The “src” folder outside the Flutter package (src/kiwi and others) suggests that there might be low-level algorithms (perhaps for the underlying cropping math or constrained solvers) reused from native C/C++ code.

##### Relationships and Interactions
- The Core Library exposes a high-level API (via croppy.dart) that the UI components (Material and Cupertino) call to perform image cropping.
- Controllers manage state and user interactions and invoke transformation algorithms.
- Widgets use controllers and models to render interactive cropping interfaces.
- FFI components serve as bridges calling into native routines from Dart for performance-sensitive operations.
- Localization layers sit below the UI components to provide language-specific strings; this is configured via the localization delegates in the host app.
- The example app acts as a client to the library, demonstrating how the various components interact in a real Flutter app.

##### Architectural Patterns and Design Principles
- Separation of concerns: Clear division between UI (widgets/pages), business logic (controllers, models, transformation logic), and integration layers (FFI, platform-specific code).
- Modular design: The library is split into many submodules (controllers, geometry, image, localization, widgets) that work together as loosely coupled components.
- Cross-platform abstraction: Most core functionality is implemented in a way that is abstracted from the underlying platform, with conditionals or separate implementations (e.g., web vs. mobile).
- Customization and extensibility: The package is fully customizable; the use of themes and configurable controllers allows integration with both Material and Cupertino design languages.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Example["Example Application"]:::example
    MaterialUI["Material UI Components"]:::ui
    CupertinoUI["Cupertino UI Components"]:::ui
    Controllers["Controllers"]:::controller
    Transformations["Transformations"]:::controller
    CoreAPI["Croppy Core API"]:::core
    DomainModels["Domain Models"]:::core
    FFI["FFI Integration"]:::ffi
    Native["C/C++ Native Components"]:::ffi
    Localization["Localization Module"]:::localization
    PlatformAndroid["Android"]:::platform
    PlatformiOS["iOS"]:::platform
    PlatformMacos["macOS"]:::platform
    PlatformLinux["Linux"]:::platform
    PlatformWindows["Windows"]:::platform

    %% Relationships
    Example -->|"uses"| MaterialUI
    Example -->|"uses"| CupertinoUI
    MaterialUI -->|"triggers"| Controllers
    CupertinoUI -->|"triggers"| Controllers
    Controllers -->|"invokes"| Transformations
    Transformations -->|"calls"| CoreAPI
    Transformations -->|"calls"| DomainModels
    CoreAPI -->|"bridges"| FFI
    FFI -->|"integrates with"| Native
    FFI -->|"supportedBy"| PlatformAndroid
    FFI -->|"supportedBy"| PlatformiOS
    FFI -->|"supportedBy"| PlatformMacos
    FFI -->|"supportedBy"| PlatformLinux
    FFI -->|"supportedBy"| PlatformWindows
    MaterialUI -->|"localizesVia"| Localization
    CupertinoUI -->|"localizesVia"| Localization

    %% Click Events
    click Example "https://github.com/kekland/croppy/tree/master/example"
    click MaterialUI "https://github.com/kekland/croppy/tree/master/lib/src/widgets/material"
    click CupertinoUI "https://github.com/kekland/croppy/tree/master/lib/src/widgets/cupertino"
    click Controllers "https://github.com/kekland/croppy/tree/master/lib/src/controller"
    click Transformations "https://github.com/kekland/croppy/tree/master/lib/src/controller/transformations"
    click CoreAPI "https://github.com/kekland/croppy/blob/master/lib/croppy.dart"
    click DomainModels "https://github.com/kekland/croppy/tree/master/lib/src/model"
    click FFI "https://github.com/kekland/croppy/tree/master/lib/src/ffi"
    click Native "https://github.com/kekland/croppy/tree/master/src"
    click Localization "https://github.com/kekland/croppy/tree/master/lib/src/l10n"
    click PlatformAndroid "https://github.com/kekland/croppy/tree/master/android"
    click PlatformiOS "https://github.com/kekland/croppy/tree/master/ios"
    click PlatformMacos "https://github.com/kekland/croppy/tree/master/macos"
    click PlatformLinux "https://github.com/kekland/croppy/tree/master/linux"
    click PlatformWindows "https://github.com/kekland/croppy/tree/master/windows"

    %% Styles
    classDef example fill:#f9c,stroke:#333,stroke-width:2px;
    classDef ui fill:#bbf,stroke:#333,stroke-width:2px;
    classDef controller fill:#fb8,stroke:#333,stroke-width:2px;
    classDef core fill:#afa,stroke:#333,stroke-width:2px;
    classDef ffi fill:#fda,stroke:#333,stroke-width:2px;
    classDef localization fill:#ddf,stroke:#333,stroke-width:2px;
    classDef platform fill:#d8f,stroke:#333,stroke-width:2px;
```
