# desandro/draggabilly architecture

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

- Interactive diagram: https://gitdiagram.com/desandro/draggabilly
- Repository: https://github.com/desandro/draggabilly

## Overview

##### Main Components
- Core Library Module: Represent the key file (draggabilly.js), which implements the core drag-and-drop logic, event binding, options management, and public API. This is the heart of the system.
- Distribution Bundle: Include the “dist” folder, which holds the packaged and minified versions of the library for consumption (e.g., draggabilly.pkgd.js).
- Build Tools & Scripts: Show the “bin” directory with its bespoke scripts (e.g., build-dist.js for building the distribution, lint-json.js, version.js) which are used to automate tasks such as building, linting, and versioning.
- Sandbox / Examples: The “sandbox” folder contains example usage (both for require.js and vanilla HTML examples) that demonstrate how to integrate Draggabilly. This illustrates how consumers will test and interact with the library in real-world scenarios.
- Testing Suite: Illustrate the “test” directory that holds unit tests (with folders and files for basic functionality and jQuery-specific tests as well as front-end demos via HTML).

##### Relationships and Interactions
- Consumers (Developers/Applications): Show how external applications or webpage consumers interact with the library. They download the built bundles via CDNs, package managers, or directly from the “dist” folder.
- API Consumers: Indicate two main integrations:
- Vanilla JS consumers using the new Draggabilly(…) constructor.
- jQuery Plugin consumers via the jquery-bridget integration.
- Build Pipeline: Represent the relationship between the source module, build scripts (in the “bin” folder), and the resulting distribution bundle (in the “dist” folder). This illustrates the compilation and packaging process.
- Testing: Link the core module and the sandbox demos to the test suite. This shows how the functionality is verified and how changes can be validated via unit tests.
- Event & Method Handlers: Within the library, highlight the use of events (e.g., dragStart, dragMove, dragEnd, pointer events) for interactive behavior and note how these events are exposed as the public API.

##### Architectural Patterns and Design Principles
- Modular Design: The library is built as a modular component that can be used either as a standalone vanilla JS module or extended for jQuery use. Emphasize the separation between core functionality and integration/adaptation layers.
- Testing & Sandbox Guidance: Highlight the importance of isolated test cases and real-world examples found in the “sandbox” directory.
- Loose Coupling with External Dependencies: Even though the library supports jQuery, its core remains independent and can be integrated with various frameworks via adapters like jquery-bridget.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Module
    Core["Core Module: draggabilly.js"]:::library

    %% Build Tools Subgraph
    subgraph "Build Tools (bin)"
        BuildDist["build-dist.js"]:::build
        Lint["lint-json.js"]:::build
        Version["version.js"]:::build
    end

    %% Distribution Bundle
    Dist["Distribution Bundle: dist/draggabilly.pkgd.js"]:::bundle

    %% Sandbox / Examples Subgraph
    subgraph "Sandbox / Examples"
        RequireJS["sandbox/require-js"]:::sandbox
        SandboxHTML["sandbox/sandbox.html"]:::sandbox
        SingleHTML["sandbox/single.html"]:::sandbox
    end

    %% Testing Suite
    TestSuite["Test Suite: test/"]:::test

    %% API Consumers Subgraph
    subgraph "API Consumers"
        Vanilla["Vanilla JS Consumer"]:::consumer
        jQuery["jQuery Integration"]:::consumer
    end

    %% Connections
    %% Build Pipeline: Core -> Build Tools -> Distribution Bundle
    Core -->|"builds via"| BuildDist
    Core -->|"builds via"| Lint
    Core -->|"builds via"| Version
    BuildDist -->|"generates"| Dist
    Lint -->|"validates"| Dist
    Version -->|"updates"| Dist

    %% Testing & Sandbox: Core module usage verification
    Core -->|"tested by"| TestSuite
    Core -->|"demonstrated in"| RequireJS
    Core -->|"demonstrated in"| SandboxHTML
    Core -->|"demonstrated in"| SingleHTML

    %% API Consumers get library via Distribution Bundle
    Dist -->|"consumed by"| Vanilla
    Dist -->|"consumed by"| jQuery

    %% Note: Core Module exposes events like dragStart, dragMove, dragEnd, pointerDown, pointerMove, pointerUp, staticClick
    Core ---|"exposes events"| Vanilla
    Core ---|"exposes events"| jQuery

    %% Click Events
    click Core "https://github.com/desandro/draggabilly/blob/master/draggabilly.js"
    click BuildDist "https://github.com/desandro/draggabilly/blob/master/bin/build-dist.js"
    click Lint "https://github.com/desandro/draggabilly/blob/master/bin/lint-json.js"
    click Version "https://github.com/desandro/draggabilly/blob/master/bin/version.js"
    click Dist "https://github.com/desandro/draggabilly/blob/master/dist/draggabilly.pkgd.js"
    click RequireJS "https://github.com/desandro/draggabilly/tree/master/sandbox/require-js"
    click SandboxHTML "https://github.com/desandro/draggabilly/blob/master/sandbox/sandbox.html"
    click SingleHTML "https://github.com/desandro/draggabilly/blob/master/sandbox/single.html"
    click TestSuite "https://github.com/desandro/draggabilly/tree/master/test/"

    %% Styles
    classDef library fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef build fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef bundle fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef sandbox fill:#E0FFFF,stroke:#000,stroke-width:1px;
    classDef test fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef consumer fill:#DDA0DD,stroke:#000,stroke-width:1px;
```
