# tahash/swapy architecture

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

- Interactive diagram: https://gitdiagram.com/tahash/swapy
- Repository: https://github.com/tahash/swapy

## Overview

##### Project type and purpose
- From the README (“A framework-agnostic tool that converts any layout into a drag-to-swap one…”) and the file tree, this is a front-end JavaScript/TypeScript library (not a full-stack web app).
- It’s meant to be built once (via Vite/Rollup) and then published (npm dist/ files) and consumed by any framework (React, Vue, Svelte, vanilla, etc.).

##### File structure
- Top-level build/config files:
- package.json / pnpm-lock.yaml
- tsconfig.json / tsconfig.build.json
- vite.config.ts
- `/src`: Core library modules (animators.ts, draggable.ts, flip.ts, utils.ts, view.ts, etc.)
- `/dist`: Compiled output (swapy.js, swapy.d.ts)
- `/examples`: Demo consumer apps in various frameworks, each with its own index.html + main.ts(x)

##### README for additional insights

a. Main components
1. Source modules (in `/src`):
– Core logic sub-components:
- Drag & drop logic (draggable.ts)
- Animation routines (animators.ts, easings.ts)
- Layout utilities (math.ts, rect.ts, vector.ts)
- Flip transition engine (flip.ts)
- API entry point (index.ts)
2. Build toolchain:
– Vite (build orchestrator)
– TypeScript compiler
– Output bundler (Rollup under the hood)
3. Published package:
– Dist artifact (swapy.js + swapy.d.ts) pushed to npm
4. Consumer applications (examples):
– React, Vue, Svelte, vanilla demos that import swapy.js
5. Optional external services:
– Documentation site (swapy.tahazsh.com)

b. Relationships & data flow
– “Source modules” → (via TS compile & Rollup/Vite) → “Dist bundle”
– “Dist bundle” → (npm publish) → “Consumer apps”
– “Consumer apps” → at runtime → interact with DOM/layout and call into the library API
– (Optionally) “Consumer” authors visit the documentation site for usage guidance

c. Architectural patterns & design principles
– Modular single-responsibility modules in `/src` (e.g., separate math, DOM view, animation, swapping logic)
– Build-time separation (source vs. dist)
– Framework-agnostic public API (index.ts) that decouples from any UI framework
– Demo sandbox pattern under `/examples` to validate cross-framework compatibility

d. Key technologies
– TypeScript for type-safe source
– Vite as the build orchestrator (leveraging ES modules & Rollup)
– PNPM as the package manager
– Framework examples: React, Vue, Svelte, vanilla

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Modules
    subgraph "Source Modules" 
        direction TB
        DRAG["Drag & Drop Logic\n(draggable.ts)"]:::src
        ANIM["Animation Engine\n(animators.ts)"]:::src
        EASE["Easings\n(easings.ts)"]:::src
        LAY1["Math Utilities\n(math.ts)"]:::src
        LAY2["Rect Utilities\n(rect.ts)"]:::src
        LAY3["Vector Utilities\n(vector.ts)"]:::src
        FLIP["Flip Transition Engine\n(flip.ts)"]:::src
        VIEW["View Management\n(view.ts)"]:::src
        UTIL["Misc Utilities\n(utils.ts, borderRadius.ts)"]:::src
        API["Public API Entry Point\n(index.ts)"]:::src
    end

    %% Build Toolchain
    subgraph "Build Toolchain"
        direction TB
        VITE["Vite Config\n(vite.config.ts)"]:::build
        TSC_DEV["TS Compiler Config\n(tsconfig.json)"]:::build
        TSC_BU["TS Build Config\n(tsconfig.build.json)"]:::build
    end

    %% Dist Artifact
    subgraph "Dist Artifact"
        direction TB
        BUNDLE["JS Bundle\n(swapy.js)"]:::dist
        TYPES["Type Definitions\n(swapy.d.ts)"]:::dist
    end

    %% Consumer Applications
    subgraph "Consumer Apps"
        direction TB
        VAN["Vanilla Demo\n(examples/vanilla)"]:::consumer
        VAND["Vanilla Dynamic Demo\n(examples/vanilla-dynamic)"]:::consumer
        REA["React Demo\n(examples/react)"]:::consumer
        READ["React Dynamic Demo\n(examples/react-dynamic)"]:::consumer
        VUE["Vue Demo\n(examples/vue)"]:::consumer
        VUED["Vue Dynamic Demo\n(examples/vue-dynamic)"]:::consumer
        SEL["Svelte Demo\n(examples/svelte)"]:::consumer
        SED["Svelte Dynamic Demo\n(examples/svelte-dynamic)"]:::consumer
    end

    %% External Docs
    DOCS["Documentation Site\n(swapy.tahazsh.com)"]:::docs

    %% Browser DOM
    DOM["Browser DOM/Layout"]:::docs

    %% Connections
    API -->|"sources compile & bundle"| VITE
    DRAG --> VITE
    ANIM --> VITE
    EASE --> VITE
    LAY1 --> VITE
    LAY2 --> VITE
    LAY3 --> VITE
    FLIP --> VITE
    VIEW --> VITE
    UTIL --> VITE
    TSC_DEV --> VITE
    TSC_BU --> VITE

    VITE -->|"bundle output"| BUNDLE
    VITE -->|"types output"| TYPES

    BUNDLE -->|"npm publish"| VAN
    BUNDLE -->|"npm publish"| VAND
    BUNDLE -->|"npm publish"| REA
    BUNDLE -->|"npm publish"| READ
    BUNDLE -->|"npm publish"| VUE
    BUNDLE -->|"npm publish"| VUED
    BUNDLE -->|"npm publish"| SEL
    BUNDLE -->|"npm publish"| SED

    VAN -->|"runtime import & initialize"| DOM
    VAND -->|"runtime import & initialize"| DOM
    REA -->|"runtime import & initialize"| DOM
    READ -->|"runtime import & initialize"| DOM
    VUE -->|"runtime import & initialize"| DOM
    VUED -->|"runtime import & initialize"| DOM
    SEL -->|"runtime import & initialize"| DOM
    SED -->|"runtime import & initialize"| DOM

    DOCS -->|"usage guidance"| VAN
    DOCS -->|"usage guidance"| VAND
    DOCS -->|"usage guidance"| REA
    DOCS -->|"usage guidance"| READ
    DOCS -->|"usage guidance"| VUE
    DOCS -->|"usage guidance"| VUED
    DOCS -->|"usage guidance"| SEL
    DOCS -->|"usage guidance"| SED

    %% Click Events
    click DRAG "https://github.com/tahash/swapy/blob/main/src/draggable.ts"
    click ANIM "https://github.com/tahash/swapy/blob/main/src/animators.ts"
    click EASE "https://github.com/tahash/swapy/blob/main/src/easings.ts"
    click LAY1 "https://github.com/tahash/swapy/blob/main/src/math.ts"
    click LAY2 "https://github.com/tahash/swapy/blob/main/src/rect.ts"
    click LAY3 "https://github.com/tahash/swapy/blob/main/src/vector.ts"
    click FLIP "https://github.com/tahash/swapy/blob/main/src/flip.ts"
    click VIEW "https://github.com/tahash/swapy/blob/main/src/view.ts"
    click UTIL "https://github.com/tahash/swapy/blob/main/src/utils.ts"
    click UTIL "https://github.com/tahash/swapy/blob/main/src/borderRadius.ts"
    click API "https://github.com/tahash/swapy/blob/main/src/index.ts"
    click VITE "https://github.com/tahash/swapy/blob/main/vite.config.ts"
    click TSC_DEV "https://github.com/tahash/swapy/blob/main/tsconfig.json"
    click TSC_BU "https://github.com/tahash/swapy/blob/main/tsconfig.build.json"
    click BUNDLE "https://github.com/tahash/swapy/blob/main/dist/swapy.js"
    click TYPES "https://github.com/tahash/swapy/blob/main/dist/swapy.d.ts"
    click VAN "https://github.com/tahash/swapy/tree/main/examples/vanilla"
    click VAND "https://github.com/tahash/swapy/tree/main/examples/vanilla-dynamic"
    click REA "https://github.com/tahash/swapy/tree/main/examples/react"
    click READ "https://github.com/tahash/swapy/tree/main/examples/react-dynamic"
    click VUE "https://github.com/tahash/swapy/tree/main/examples/vue"
    click VUED "https://github.com/tahash/swapy/tree/main/examples/vue-dynamic"
    click SEL "https://github.com/tahash/swapy/tree/main/examples/svelte"
    click SED "https://github.com/tahash/swapy/tree/main/examples/svelte-dynamic"

    %% Styles
    classDef src fill:#E0F7FA,stroke:#0277BD,color:#01579B
    classDef build fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    classDef dist fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef consumer fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
    classDef docs fill:#ECEFF1,stroke:#546E7A,color:#263238
```
