# pikasojs/pikaso architecture

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

- Interactive diagram: https://gitdiagram.com/pikasojs/pikaso
- Repository: https://github.com/pikasojs/pikaso

## Overview

##### Main Components
- Domain Modules – The “src” directory is organized into several modular components, each handling a specific concern:
- Board & Background: Managing the canvas container and background image.
- Cropper: Several cropper implementations (Fixed, Flexible, Circular, Rectangle) which encapsulate cropping logic.
- Transformation Modules: Rotation, Flip, and Selection modules for interactive modifications.
- Export/Import: Modules under Export (for PNG/JPEG, JSON) and Import, to support state persistence.
- Utilities & Helpers: A variety of utility functions (e.g., rotate-around-center, get-points-distance) that facilitate arithmetic, coordinate computations, and environment detection.
- Events & Filters: Event management and filter modules to handle user interactions and custom drawing effects.
- External Interfaces:
- API Entry Point: The “Pikaso” class exported via the index files in the root or src directory, which encapsulates configuration and acts as the primary API.
- Integration Examples: Provided hooks for React (and possibly other frameworks) to integrate with the library.
- Testing & Quality Assurance:
- Unit & Integration Testing: Represented by directories like “jest”, “cypress”, and “tests”, which help ensure quality and coverage.

##### Relationships and Interactions
- The central API (Editor) interacts with nearly every module: when a user instantiates a new Pikaso instance, it configures the board, background, event management, etc.
- Event Manager is a crosscutting component that notifies various modules (e.g., History, Grouping, and the core drawing engine) about user interactions.
- Utility functions and configuration management (global settings, detection of Node vs. browser environment) underpin the operations of these modules.
- Testing suites (Jest and Cypress) interact with the modules to simulate user actions and validate expected behavior.

##### Architectural Patterns and Design Principles
- Modular Design: The project is clearly divided into self-contained modules (as seen in the “src” folder), promoting separation of concerns.
- Presentation/Interface Layer (API/Editor class, external integrations)
- Utility/Service Layer (event management, utilities, state management, testing harness)

##### Technology and Frameworks
- TypeScript serves as the backbone, ensuring full static typing across modules.
- Konva is the underlying canvas library that Pikaso extends.
- Build tools: Babel (babel.config.js), Rollup (rollup.config.js), and Jest and Cypress for testing.
- GitHub workflows and husky hooks indicate that CI/CD and quality checks are fundamental parts of the development process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation/Interface Layer
    subgraph "Presentation/Interface Layer"
        Pikaso_API_editor["Pikaso (API/Editor)"]:::core
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        BoardMgmt["Board Management"]:::business
        BackgroundMgmt["Background Management"]:::business
        Cropper_Mod["Cropper Module"]:::business
        subgraph "Shape System"
            ShapeModels["Shape Models"]:::business
            ShapeDrawers["Shape Drawers"]:::business
        end
        subgraph "Transformation Modules"
            Rotation["Rotation"]:::business
            Flip["Flip"]:::business
            Selection["Selection"]:::business
        end
        ExportFunc["Export Functionality"]:::business
        ImportFunc["Import Functionality"]:::business
        History["State Management (History)"]:::business
        Grouping["Grouping Module"]:::business
    end

    %% Utility/Service Layer
    subgraph "Utility/Service Layer"
        EventsMgmt["Events Management"]:::utility
        FilterMod["Filter Module"]:::utility
        Utils["Utility Functions & Helpers"]:::utility
    end

    %% External Libraries and Testing
    Konva_Library["Konva Library"]:::external
    Testing["Testing & Quality Assurance"]:::testing

    %% Connections from Pikaso (API/Editor) to Business Modules
    Pikaso_API_editor -->|"init_board"| BoardMgmt
    Pikaso_API_editor -->|"init_background"| BackgroundMgmt
    Pikaso_API_editor -->|"calls_cropper"| Cropper_Mod
    Pikaso_API_editor -->|"creates_shapes"| ShapeModels
    ShapeModels -->|"renders"| ShapeDrawers
    Pikaso_API_editor -->|"rotate"| Rotation
    Pikaso_API_editor -->|"flip"| Flip
    Pikaso_API_editor -->|"select"| Selection
    Pikaso_API_editor -->|"export"| ExportFunc
    Pikaso_API_editor -->|"import"| ImportFunc
    Pikaso_API_editor -->|"state_change"| History
    Pikaso_API_editor -->|"group_shapes"| Grouping

    %% Connections from Pikaso (API/Editor) to Utility Modules
    Pikaso_API_editor -->|"handles_events"| EventsMgmt
    Pikaso_API_editor -->|"uses_utils"| Utils

    %% Interaction with External Library
    Pikaso_API_editor -->|"extends_Konva"| Konva_Library

    %% Cross-layer interactions
    EventsMgmt -->|"notify_history"| History
    EventsMgmt -->|"notify_grouping"| Grouping
    Utils -->|"support"| ShapeModels

    %% Testing connection
    Testing -->|"verify"| Pikaso_API_editor

    %% Click Event Mappings
    click Pikaso_API_editor "https://github.com/pikasojs/pikaso/blob/master/src/index.ts"
    click BoardMgmt "https://github.com/pikasojs/pikaso/blob/master/src/Board/index.ts"
    click BackgroundMgmt "https://github.com/pikasojs/pikaso/blob/master/src/Background/index.ts"
    click Cropper_Mod "https://github.com/pikasojs/pikaso/tree/master/src/Cropper"
    click ShapeModels "https://github.com/pikasojs/pikaso/tree/master/src/shape/models"
    click ShapeDrawers "https://github.com/pikasojs/pikaso/tree/master/src/shape/drawers"
    click Rotation "https://github.com/pikasojs/pikaso/blob/master/src/Rotation/index.ts"
    click Flip "https://github.com/pikasojs/pikaso/blob/master/src/Flip/index.ts"
    click Selection "https://github.com/pikasojs/pikaso/blob/master/src/Selection/index.ts"
    click ExportFunc "https://github.com/pikasojs/pikaso/tree/master/src/Export"
    click ImportFunc "https://github.com/pikasojs/pikaso/blob/master/src/Import/index.ts"
    click History "https://github.com/pikasojs/pikaso/blob/master/src/History/index.ts"
    click Grouping "https://github.com/pikasojs/pikaso/tree/master/src/grouping"
    click Utils "https://github.com/pikasojs/pikaso/tree/master/src/utils"
    click EventsMgmt "https://github.com/pikasojs/pikaso/blob/master/src/Events/index.ts"
    click FilterMod "https://github.com/pikasojs/pikaso/blob/master/src/Filter/index.ts"
    click Testing "https://github.com/pikasojs/pikaso/tree/master/tests/"

    %% Styles
    classDef core fill:#ffadad,stroke:#333,stroke-width:2px;
    classDef business fill:#a0c4ff,stroke:#333,stroke-width:2px;
    classDef utility fill:#caffbf,stroke:#333,stroke-width:2px;
    classDef testing fill:#ffd6a5,stroke:#333,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:2px;
```
