# pkuleon/tiny-zepto architecture

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

- Interactive diagram: https://gitdiagram.com/pkuleon/tiny-zepto
- Repository: https://github.com/pkuleon/tiny-zepto

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is a **single-file, client-side JavaScript DOM utility library** (“Tiny Zepto”) meant to be **dropped into a web page** via a `<script>` tag (CDN via jsDelivr/GitHub). There is **no backend, no build step, no dependencies**. The “system” is essentially:

- **Consumer Web Page / App (HTML + JS)**
loads →
- **Tiny Zepto library (`latest.js`)**
which wraps/augments →
- **Browser DOM APIs** (querySelectorAll, classList, addEventListener, etc.)
to manipulate →
- **DOM Tree / Elements** and handle →
- **Browser Events**

##### File structure analysis (what components exist)
From the tree:

- `latest.js`
The entire library implementation. This is the core runtime artifact users execute in the browser.
- `README.md`
Public contract: features, API surface, usage/integration.
- `.github/workflows/npm-publish.yml`
Release/publish automation (CI/CD) for distributing the library (likely to npm and/or tagging). Even if the README highlights CDN usage, the workflow indicates a packaging/distribution pipeline.
- `.github/`
Meta tooling.

**Implication:** the system has two “planes” worth diagramming:
##### Runtime plane (in-browser): how `latest.js` interacts with the DOM and user code.
2) **Delivery plane (distribution)**: how code goes from GitHub repo → published artifact/CDN/npm → loaded by consumers.

##### README-derived architecture hints (key relationships)
The README tells you the library provides:

- Selection (`$q(selector | element | html | list)`)
- Manipulation: `.html()`, `.text()`, `.append()`, `.remove()`
- Traversal: `.find()`
- Attributes/styles: `.attr()`, `.css()`, `.data()`
- Classes: `.addClass()`, `.removeClass()`, `.hasClass()`
- Events: `.on()`, `.off()`
- **Chainable API** (setter methods return the instance)

This implies an internal model like:
- A **factory function** `$q(...)` returning a **TinyZepto instance** wrapping an **element collection**.
- Methods operate on that collection using **native DOM APIs**.
- Event methods attach/detach listeners on elements.

##### Tiny Zepto (`latest.js`)
- `$q()` factory
- `TinyZepto` wrapper/collection (or similar)
- Method groups:
- Selection/Creation
- DOM manipulation
- Traversal
- Attributes/Styles/Dataset
- Class ops
- Event binding
##### Browser DOM & Web APIs
- DOM tree / Elements
- Events subsystem (EventTarget/addEventListener)
- CSSOM style interface (element.style)
- Dataset API (element.dataset)
##### Rendered Page / UI (optional but useful to show “effect”)

**Distribution / Delivery**
##### Package Registry / CDN
- npm (if used)
- jsDelivr + GitHub (explicit in README)

**Runtime**
- Consumer Code → Tiny Zepto: *invokes `$q()` + chainable methods*
- Tiny Zepto → Browser DOM APIs: *queries elements, mutates DOM, binds/unbinds events*
- Browser DOM APIs → Rendered Page/UI: *reflow/repaint; user sees updates*
- User Interactions (click/input) → Browser Events → Tiny Zepto handlers → Consumer callbacks
(this is the important event-flow loop)

**Delivery**
- GitHub Repository → GitHub Actions: *on tag/release/push triggers pipeline*
- GitHub Actions → npm/CDN: *publishes artifact*
- Consumer Web Page → CDN: *downloads `latest.js`*
- CDN → Browser: *serves JS asset*

##### Architectural patterns / principles
- **Wrapper / Facade over native DOM APIs** (Tiny Zepto simplifies common tasks)
- **Chainable fluent interface** (setter methods return the wrapper instance)
- **Zero dependency / no build** (single artifact, direct inclusion)
- **In-browser runtime only** (no server-side component)

##### Relevant technologies
- **JavaScript (ES6+)**
- **Browser DOM APIs** (querySelectorAll, classList, dataset, addEventListener)
- **GitHub Actions** (CI/CD)
- **jsDelivr (GitHub CDN)** and optionally **npm**

- **Clear labels**:
- “Consumer App Code”
- “Tiny Zepto: `$q()` + chainable wrapper”
- “DOM APIs / Web Platform”
- “GitHub Actions (publish)”
- “CDN (jsDelivr) / npm”
- Code modules (rectangles)
- External services (rounded rectangles)

Include:
- `$q(input)` → “Normalize input to element collection”
- DOM APIs called by each method group
- Event loop: user → event → handler → consumer callback

Include:
- Commit/tag → workflow trigger
- Publish step → artifact available
- `<script src="...latest.js">` → browser fetch

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Delivery / Distribution Plane
  %% =========================
  subgraph DP["Delivery Plane (Source → Publish → Consume)"]
    direction TB

    subgraph SRC["Source (GitHub)"]
      direction TB
      Repo["GitHub Repository"]:::repo
      Readme["README (API/Usage Contract)"]:::doc
      Latest["latest.js (Single-File Library Artifact)"]:::lib
      GHMeta[".github/ (Meta Tooling)"]:::meta
      WorkflowsDir[".github/workflows/"]:::meta
      Workflow["GitHub Actions: npm-publish.yml"]:::cicd
    end

    subgraph PUB["Publish Targets (External)"]
      direction TB
      NPM["Package Registry (npm)"]:::external
      CDN["CDN (jsDelivr via GitHub)"]:::external
    end

    subgraph CONS["Consumer Load (Browser Fetch)"]
      direction TB
      ScriptTag["Consumer Web Page: script src='...latest.js'"]:::consumer
      BrowserFetch["Browser HTTP Fetch"]:::browser
    end

    Repo -->|"contains"| Latest
    Repo -->|"contains"| Readme
    Repo -->|"contains"| GHMeta
    GHMeta -->|"includes"| WorkflowsDir
    WorkflowsDir -->|"runs"| Workflow

    Repo -.->|"push/tag/release_triggers"| Workflow
    Workflow -.->|"publish_artifact"| NPM
    Workflow -.->|"publish_or_tag_for_cdn"| CDN

    ScriptTag -->|"requests_asset"| BrowserFetch
    BrowserFetch -->|"downloads"| CDN
  end

  %% =========================
  %% Runtime / In-Browser Plane
  %% =========================
  subgraph RT["Runtime Plane (In-Browser Integration & Interaction)"]
    direction TB

    subgraph APP["Consumer App"]
      direction TB
      ConsumerCode["Consumer App Code (calls $q(...), chains methods)"]:::consumer
      ConsumerCallbacks["Consumer Callbacks (event handlers)"]:::consumer
      RenderedUI["Rendered Page / UI"]:::ui
    end

    subgraph LIB["Tiny Zepto (latest.js)"]
      direction TB
      Entry["Global $q(input) Factory"]:::lib
      Normalize["Normalize Input → Element Collection"]:::lib
      Wrapper["TinyZepto Wrapper / Collection Instance"]:::lib

      subgraph API["Chainable API (setter_returns_instance)"]
        direction TB
        Selection["Selection/Creation (selector|element|html|list)"]:::libgroup
        Manip["DOM Manipulation (.html,.text,.append,.remove)"]:::libgroup
        Traversal["Traversal (.find)"]:::libgroup
        AttrStyleData["Attributes/Styles/Dataset (.attr,.css,.data)"]:::libgroup
        ClassOps["Class Ops (.addClass,.removeClass,.hasClass)"]:::libgroup
        EventsAPI["Events (.on,.off)"]:::libgroup
      end
    end

    subgraph WEB["Browser Platform (Native Web APIs)"]
      direction TB
      DOMAPIs["DOM APIs (querySelectorAll, Element, classList)"]:::browser
      CSSOM["CSSOM (element.style)"]:::browser
      DatasetAPI["Dataset API (element.dataset)"]:::browser
      EventTarget["Events (EventTarget/addEventListener)"]:::browser
      DOMTree[("DOM Tree / Elements")]:::dom
      User["User Interactions (click/input)"]:::external
    end

    %% Library integration
    BrowserFetch -->|"executes_script"| Latest
    ConsumerCode -->|"invokes_$q(input)"| Entry
    Entry -->|"creates"| Normalize
    Normalize -->|"wraps"| Wrapper

    %% Fluent chaining to method groups
    Wrapper -->|"provides"| Selection
    Wrapper -->|"provides"| Manip
    Wrapper -->|"provides"| Traversal
    Wrapper -->|"provides"| AttrStyleData
    Wrapper -->|"provides"| ClassOps
    Wrapper -->|"provides"| EventsAPI

    %% Method groups to native APIs
    Selection -->|"uses_querySelectorAll"| DOMAPIs
    Traversal -->|"uses_querySelectorAll"| DOMAPIs
    Manip -->|"mutates_nodes"| DOMAPIs
    AttrStyleData -->|"reads/writes_attributes"| DOMAPIs
    AttrStyleData -->|"writes_styles"| CSSOM
    AttrStyleData -->|"reads/writes_dataset"| DatasetAPI
    ClassOps -->|"uses_classList"| DOMAPIs
    EventsAPI -->|"add/remove_listener"| EventTarget

    %% DOM effects
    DOMAPIs -->|"reads/writes"| DOMTree
    CSSOM -->|"updates_styles"| DOMTree
    DatasetAPI -->|"updates_data_attrs"| DOMTree
    DOMTree -->|"reflow/repaint"| RenderedUI

    %% Event loop
    User -->|"triggers"| EventTarget
    EventTarget -->|"dispatches_to"| EventsAPI
    EventsAPI -->|"invokes"| ConsumerCallbacks
    ConsumerCallbacks -->|"calls_chainable_methods"| Wrapper
  end

  %% =========================
  %% Notes / Principles
  %% =========================
  subgraph KP["Key Principles"]
    direction TB
    Note1["Wrapper/Facade over native DOM APIs"]:::note
    Note2["Chainable fluent interface (setters return wrapper)"]:::note
    Note3["Zero dependencies / no build (single artifact)"]:::note
    Note4["Client-side only (no backend)"]:::note
  end

  Latest -.->|"enables"| Note1
  Wrapper -.->|"implements"| Note2
  Latest -.->|"characteristic"| Note3
  BrowserFetch -.->|"runtime_scope"| Note4

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click Latest "https://github.com/pkuleon/tiny-zepto/blob/main/latest.js"
  click Readme "https://github.com/pkuleon/tiny-zepto/blob/main/README.md"
  click Workflow "https://github.com/pkuleon/tiny-zepto/blob/main/.github/workflows/npm-publish.yml"
  click GHMeta "https://github.com/pkuleon/tiny-zepto/tree/main/.github/"
  click WorkflowsDir "https://github.com/pkuleon/tiny-zepto/tree/main/.github/workflows/"

  %% =========================
  %% Styles
  %% =========================
  classDef consumer fill:#E8F1FF,stroke:#2B6CB0,stroke-width:1.2px,color:#0B1F44
  classDef lib fill:#E9FBEA,stroke:#1F7A3F,stroke-width:1.2px,color:#0E2A16
  classDef libgroup fill:#DFF7E2,stroke:#2F855A,stroke-width:1px,color:#0E2A16
  classDef browser fill:#FFF2CC,stroke:#B7791F,stroke-width:1.2px,color:#3B2F0B
  classDef dom fill:#FFE4E6,stroke:#B83280,stroke-width:1.2px,color:#3B0A1E
  classDef external fill:#F3F4F6,stroke:#4B5563,stroke-width:1.2px,color:#111827
  classDef cicd fill:#FDE68A,stroke:#B45309,stroke-width:1.2px,color:#3B2F0B
  classDef repo fill:#E5E7EB,stroke:#374151,stroke-width:1.2px,color:#111827
  classDef meta fill:#E0E7FF,stroke:#4338CA,stroke-width:1.2px,color:#111827
  classDef doc fill:#FAF5FF,stroke:#6B21A8,stroke-width:1.2px,color:#2D0A4A
  classDef ui fill:#FFECC7,stroke:#B45309,stroke-width:1.2px,color:#3B2F0B
  classDef note fill:#ECFDF5,stroke:#059669,stroke-dasharray: 4 3,color:#064E3B,font-style:italic
```
