# harley-xk/maliang architecture

> Architecture diagram of the GitHub repository harley-xk/maliang, 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/harley-xk/maliang
- Repository: https://github.com/harley-xk/maliang

## Overview

##### Project Type and Purpose
- The README shows that MaLiang is a painting framework based on Metal that enables drawing, handwriting, and special effects (like texture rotation, glowing brushes, and force/3D Touch support) in iOS. The project also supplies a sample (“Example”) Xcode project demonstrating its usage.
- It is provided as a CocoaPod (and also Carthage-compatible) and forms a core library for rendering strokes and chartlet elements on a canvas.

##### File Structure
- There are two major areas:
– The “Example” directory contains an Xcode project that demonstrates usage of MaLiang. This project includes view controllers, storyboards, and various UI components.
– The “MaLiang” directory (and its internal structure) houses the core classes and modules for the library. Within this directory you see:
- “Classes” which is further subdivided into modules such as Brush, Canvas, Data & Documents, Elements, Math & Utils, and MetalBase.
- The modular structure hints that the code is organized by functionality:
▸ The Brush module (with files like Brush.swift, ChartletBrush.swift, Eraser.swift etc.) is responsible for managing different brush types.
▸ The Canvas module (with Canvas.swift, ActionObserver.swift, ScrollableCanvas.swift, etc.) represents the drawable area handling drawing and rendering logic.
▸ Data & Documents, Elements, and Math & Utils provide support for saving/restoring, organizing drawn elements, and computational geometry (Bezier curves and gesture recognition).
▸ The MetalBase module indicates that the framework uses Metal for rendering. It contains classes like MetalView, Renderer, and shader files.
- The presence of configuration files (Podspec, .podspecs.json files in Pods) and external dependencies (Pods for SnapKit, Comet, Chrysan, Zip) shows integration with third-party libraries.

##### Main Components
- Library Core Components:
- Brush: Contains various brush types and related properties (opacity, pointSize, force sensitivity, etc.). It manages texture registration and usage.
- Elements: Represents drawing elements such as strokes, chartlets, line strips, etc.
- Data & Documents: Responsible for capturing the current state (CanvasData) and enabling Undo, Redo, saving, and restoring (DataExporter, DataImporter).
- Math & Utils: Provides computational routines (Bezier curve creation, gesture recognition, etc.) and general utility support.
- MetalBase: Acts as the bridge to Apple’s Metal API, hosting core rendering functionality (Renderer, MetalView, shader code, texture management).

- Sample Application Components (from the Example folder):
- The Example project’s view controllers (like RootViewController, File Samples view controllers, Painting Samples, Scroll Samples) that demonstrate how to integrate and use the library.
- Storyboard and XIB files that bind to the Canvas and other UI components.

- External Dependencies and Pods:
- Components such as SnapKit (for layout constraints), Comet (possibly for utility extensions), Chrysan, and Zip that may play auxiliary roles in UI and data handling.

##### Relationships and Interactions
- The sample application (client) instantiates a Canvas instance (a subclass of MTKView via MetalView) and configures it.
- As strokes are drawn, the Canvas collaborates with the MetalBase module to render using Metal’s GPU acceleration.
- Helper modules in Math & Utils process gesture input, generate Bezier paths, and adjust brush properties (such as handling force or 3D Touch).
- The Data & Documents module observes changes via CanvasData and enables Undo/Redo as well as exporting snapshots or vector documents.
- External dependencies may be used by the sample project or even the library (e.g., SnapKit for layout, Zip for archiving saved drawing data).

##### Architectural Patterns and Design Principles
- The design uses a modular architecture where each logical component (Canvas, Brush, Data, Elements, Math/Utils, MetalBase) is separated into its own subdirectory or module. This follows separation of concerns.
- The dependency on Metal for rendering encapsulated inside MetalBase is a key pattern, making the higher-level components (Canvas, Brush) independent of low-level GPU management.
- The use of observer patterns (CanvasData, DataObserver) facilitates undo/redo and real-time data tracking.
- The inclusion of third-party libraries via CocoaPods emphasizes reusability and integration with existing iOS layout and utility frameworks.

##### Extra Detail
- A separate block for the External Dependencies used in the Example project (showing pods like SnapKit, Comet, etc.).
- For the sample app, mention how it uses view controllers and storyboards to hook up the Canvas.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Sample Application Layer
    SampleApp["Sample Application (Example)"]:::sampleApp

    %% Core Library Subgraph
    subgraph "MaLiang Core Library"
        Canvas["Canvas (extends MetalView/MTKView)"]:::coreUI
        Brush["Brush (supports opacity, pointSize, force sensitivity)"]:::coreUI
        Elements["Elements (strokes, chartlets, line strips)"]:::coreLogic
        Data["Data & Documents (CanvasData, DataExporter/DataImporter)"]:::coreLogic
        MathUtils["Math & Utils (Bezier generation, gesture recognition)"]:::coreUtil
        MetalBase["MetalBase (Metal rendering, Renderer, MetalView)"]:::coreLogic
    end

    %% External Dependencies
    External["External Dependencies (SnapKit, Comet, Chrysan, Zip)"]:::external

    %% Relationships between Layers
    SampleApp -->|"instantiates"| Canvas
    Canvas -->|"utilizes"| Brush
    Canvas -->|"rendersVia"| MetalBase
    Canvas -->|"triggers"| Data
    Canvas -->|"processesInputVia"| MathUtils
    Brush -->|"providesDataTo"| Elements
    Data -->|"observes"| Canvas
    MathUtils -->|"computesFor"| Brush
    SampleApp ---|"integrates"| External

    %% Click Events
    click Canvas "https://github.com/harley-xk/maliang/tree/master/MaLiang/Classes/Canvas"
    click Brush "https://github.com/harley-xk/maliang/tree/master/MaLiang/Classes/Brush"
    click Elements "https://github.com/harley-xk/maliang/tree/master/MaLiang/Classes/Elements"
    click Data "https://github.com/harley-xk/maliang/tree/master/MaLiang/Classes/Data & Documents"
    click MathUtils "https://github.com/harley-xk/maliang/tree/master/MaLiang/Classes/Math & Utils"
    click MetalBase "https://github.com/harley-xk/maliang/tree/master/MaLiang/Classes/MetalBase"
    click SampleApp "https://github.com/harley-xk/maliang/tree/master/Example/MaLiang"

    %% Styles
    classDef sampleApp fill:#ffcc80,stroke:#e65100,stroke-width:2px;
    classDef coreUI fill:#a5d6a7,stroke:#2e7d32,stroke-width:2px;
    classDef coreLogic fill:#90caf9,stroke:#1565c0,stroke-width:2px;
    classDef coreUtil fill:#ce93d8,stroke:#6a1b9a,stroke-width:2px;
    classDef external fill:#ef9a9a,stroke:#c62828,stroke-width:2px;
```
