# hesprs/pointeract architecture

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

- Interactive diagram: https://gitdiagram.com/hesprs/pointeract
- Repository: https://github.com/hesprs/pointeract

## Overview

1. **Repo shape**
   - This is a TypeScript monorepo managed with `pnpm` workspaces and Turborepo.
   - It contains one publishable library package, one shared utility package, and a separate documentation site.
   - The architecture is intentionally split between the runtime library and the docs/test infrastructure around it.

2. **Primary product: `packages/core`**
   - `packages/core` is the actual Pointeract library users import.
   - Its public surface is centered on `Pointeract`, with a module-based extension model built on `BaseModule`.
   - The core package also defines the library’s type system and internal utilities, which keep gesture detection and event emission consistent.

3. **Module-based gesture architecture**
   - Gestures are implemented as discrete modules under `packages/core/src/modules`.
   - The built-in modules cover `Click`, `Drag`, `Swipe`, `WheelPanZoom`, `MultitouchPanZoom`, `PreventDefault`, and `Lubricator`.
   - This makes the library tree-shakeable: the runtime is small, and behavior is composed by selecting only the modules needed.

4. **Event/data flow**
   - Input begins from DOM pointer, touch, wheel, and multitouch interactions on a target element.
   - `Pointeract` coordinates module lifecycle and routes raw interaction state into module logic.
   - Modules then detect higher-level gestures and emit normalized gesture events such as drag, swipe, pan, zoom, and click variants.
   - The architecture is event-driven rather than DOM-mutation-driven; the README explicitly notes that the library avoids modifying the DOM except for `PreventDefault`.

5. **Runtime boundaries**
   - `Pointeract` is the orchestration boundary; modules are the behavior boundary.
   - `BaseModule` likely defines shared lifecycle and hooks so every module can be started, stopped, updated, and cleaned up consistently.
   - `packages/core/src/types.ts` and `utils.ts` support the cross-module contract, keeping event shapes and calculations aligned.

6. **Shared package**
   - `packages/shared` is a separate internal package, likely for code reused between core and docs or between core sub-areas.
   - Keeping shared code isolated prevents circular dependencies and makes the core package easier to bundle and publish cleanly.

7. **Testing architecture**
   - The core package has a substantial test suite covering individual gestures and integration behavior.
   - There are dedicated tests for click, drag, swipe, wheel, multitouch, and lubricator behavior.
   - `packages/core/tests/dev` provides a browser-based test harness, suggesting some interaction scenarios are validated in a real DOM environment rather than only unit tests.

8. **Documentation site**
   - `docs` is a VitePress site, separate from the library build.
   - It contains user-facing docs for getting started, basic types, module guides, events, and development topics like custom modules and testing.
   - There is also a playground component, which implies interactive examples are part of the docs architecture.

9. **Build and release pipeline**
   - The library uses `tsdown` for packaging/build output, with Vite for local development/tests.
   - GitHub Actions handles CI, docs checks, routine maintenance, and publishing.
   - `publish.yml` indicates the repo is configured as a distributable npm package, while `ci-test.yml` and related workflows gate changes on tests and documentation.

10. **Operational characteristics**
   - Pointeract is designed as a lightweight gesture engine for DOM elements, not a UI framework.
   - The important architectural promise is composability: one core runtime, many small modules, strict typing, and minimal bundle cost.
   - For an architecture diagram, the central box should be `Pointeract` in `packages/core`, surrounded by gesture modules, with docs/tests/CI as supporting subsystems rather than runtime dependencies.

Main entry points: [`docs/.vitepress/config.ts`](https://github.com/hesprs/pointeract/blob/main/docs/.vitepress/config.ts) (Docs site), [`packages/core/src/BaseModule.ts`](https://github.com/hesprs/pointeract/blob/main/packages/core/src/BaseModule.ts) (BaseModule), [`packages/core/tests/integration.test.ts`](https://github.com/hesprs/pointeract/blob/main/packages/core/tests/integration.test.ts) (Core tests), [`packages/core/src/index.ts`](https://github.com/hesprs/pointeract/blob/main/packages/core/src/index.ts) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
  node_root["Workspace<br/>pnpm+turborepo"]
  node_shared_pkg["Shared<br/>internal package<br/>[index.ts]"]
end

subgraph group_core["Core package"]
  node_core_index["Public API<br/>entrypoint<br/>[index.ts]"]
  node_pointeract["Pointeract<br/>runtime orchestrator<br/>[Pointeract.ts]"]
  node_base_module["BaseModule<br/>module base<br/>[BaseModule.ts]"]
  node_core_types["Types<br/>type system<br/>[types.ts]"]
  node_core_utils["Utils<br/>shared helpers<br/>[utils.ts]"]
  node_click_mod["Click<br/>gesture module<br/>[Click.ts]"]
  node_drag_mod["Drag<br/>gesture module<br/>[Drag.ts]"]
  node_swipe_mod["Swipe<br/>gesture module<br/>[Swipe.ts]"]
  node_wheel_mod["WheelPanZoom<br/>gesture module<br/>[WheelPanZoom.ts]"]
  node_multi_mod["MultitouchPanZoom<br/>gesture module"]
  node_prevent_mod["PreventDefault<br/>behavior module<br/>[PreventDefault.ts]"]
  node_lube_mod["Lubricator<br/>behavior module<br/>[Lubricator.ts]"]
  node_core_tests["Core tests<br/>test suite"]
  node_dev_harness["Dev harness<br/>browser tests<br/>[index.html]"]
end

subgraph group_docs["Docs site"]
  node_docs_site["Docs site<br/>vitepress site<br/>[config.ts]"]
  node_playground["Playground<br/>docs component<br/>[playground.vue]"]
end

subgraph group_ci["CI and release"]
  node_ci_test["CI test<br/>workflow<br/>[ci-test.yml]"]
  node_ci_docs["CI docs<br/>workflow<br/>[ci-docs.yml]"]
  node_publish["Publish<br/>workflow<br/>[publish.yml]"]
end

node_root -->|"contains"| node_core_index
node_root -->|"contains"| node_shared_pkg
node_root -->|"contains"| node_docs_site
node_core_index -->|"exports"| node_pointeract
node_core_index -->|"exports"| node_base_module
node_core_index -->|"exports"| node_core_types
node_pointeract -->|"loads"| node_base_module
node_pointeract -->|"uses"| node_core_utils
node_pointeract -->|"uses"| node_core_types
node_base_module -->|"implements"| node_click_mod
node_base_module -->|"implements"| node_drag_mod
node_base_module -->|"implements"| node_swipe_mod
node_base_module -->|"implements"| node_wheel_mod
node_base_module -->|"implements"| node_multi_mod
node_base_module -->|"implements"| node_prevent_mod
node_base_module -->|"implements"| node_lube_mod
node_click_mod -->|"uses"| node_core_utils
node_drag_mod -->|"uses"| node_core_utils
node_swipe_mod -->|"uses"| node_core_utils
node_wheel_mod -->|"uses"| node_core_utils
node_multi_mod -->|"uses"| node_core_utils
node_prevent_mod -->|"uses"| node_core_types
node_lube_mod -->|"uses"| node_core_types
node_core_tests -->|"covers"| node_click_mod
node_core_tests -->|"covers"| node_drag_mod
node_core_tests -->|"covers"| node_swipe_mod
node_core_tests -->|"covers"| node_wheel_mod
node_core_tests -->|"covers"| node_multi_mod
node_core_tests -->|"covers"| node_lube_mod
node_dev_harness -->|"exercises"| node_pointeract
node_docs_site -->|"includes"| node_playground
node_docs_site -->|"documents"| node_core_index
node_docs_site -->|"documents"| node_click_mod
node_docs_site -->|"documents"| node_drag_mod
node_docs_site -->|"documents"| node_swipe_mod
node_docs_site -->|"documents"| node_wheel_mod
node_docs_site -->|"documents"| node_multi_mod
node_ci_test -->|"runs"| node_core_tests
node_ci_docs -->|"runs"| node_docs_site
node_publish -->|"publishes"| node_core_index

click node_core_index "https://github.com/hesprs/pointeract/blob/main/packages/core/src/index.ts"
click node_pointeract "https://github.com/hesprs/pointeract/blob/main/packages/core/src/Pointeract.ts"
click node_base_module "https://github.com/hesprs/pointeract/blob/main/packages/core/src/BaseModule.ts"
click node_core_types "https://github.com/hesprs/pointeract/blob/main/packages/core/src/types.ts"
click node_core_utils "https://github.com/hesprs/pointeract/blob/main/packages/core/src/utils.ts"
click node_click_mod "https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/Click.ts"
click node_drag_mod "https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/Drag.ts"
click node_swipe_mod "https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/Swipe.ts"
click node_wheel_mod "https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/WheelPanZoom.ts"
click node_multi_mod "https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/MultitouchPanZoom.ts"
click node_prevent_mod "https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/PreventDefault.ts"
click node_lube_mod "https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/Lubricator.ts"
click node_shared_pkg "https://github.com/hesprs/pointeract/blob/main/packages/shared/index.ts"
click node_core_tests "https://github.com/hesprs/pointeract/blob/main/packages/core/tests/integration.test.ts"
click node_dev_harness "https://github.com/hesprs/pointeract/blob/main/packages/core/tests/dev/index.html"
click node_docs_site "https://github.com/hesprs/pointeract/blob/main/docs/.vitepress/config.ts"
click node_playground "https://github.com/hesprs/pointeract/blob/main/docs/components/playground.vue"
click node_ci_test "https://github.com/hesprs/pointeract/blob/main/.github/workflows/ci-test.yml"
click node_ci_docs "https://github.com/hesprs/pointeract/blob/main/.github/workflows/ci-docs.yml"
click node_publish "https://github.com/hesprs/pointeract/blob/main/.github/workflows/publish.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root,node_shared_pkg toneBlue
class node_core_index,node_pointeract,node_base_module,node_core_types,node_core_utils,node_click_mod,node_drag_mod,node_swipe_mod,node_wheel_mod,node_multi_mod,node_prevent_mod,node_lube_mod,node_core_tests,node_dev_harness toneAmber
class node_docs_site,node_playground toneMint
class node_ci_test,node_ci_docs,node_publish toneRose
```

## Components

### Monorepo

Workspace root and shared tooling

- **Workspace**: pnpm+turborepo · Repository root with workspace and task orchestration
- [Shared](https://github.com/hesprs/pointeract/blob/main/packages/shared/index.ts): internal package · Reusable package shared across repository areas · `packages/shared/index.ts`

### Core package

Publishable gesture runtime

- [Public API](https://github.com/hesprs/pointeract/blob/main/packages/core/src/index.ts): entrypoint · Package export surface for the core library · `packages/core/src/index.ts`
- [Pointeract](https://github.com/hesprs/pointeract/blob/main/packages/core/src/Pointeract.ts): runtime orchestrator · Coordinates pointer interaction state and module lifecycle · `packages/core/src/Pointeract.ts`
- [BaseModule](https://github.com/hesprs/pointeract/blob/main/packages/core/src/BaseModule.ts): module base · Shared module lifecycle and hook contract · `packages/core/src/BaseModule.ts`
- [Types](https://github.com/hesprs/pointeract/blob/main/packages/core/src/types.ts): type system · Cross-module gesture and event shapes · `packages/core/src/types.ts`
- [Utils](https://github.com/hesprs/pointeract/blob/main/packages/core/src/utils.ts): shared helpers · Common calculations and internal helpers · `packages/core/src/utils.ts`
- [Click](https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/Click.ts): gesture module · Detects click variants and emits click events · `packages/core/src/modules/Click.ts`
- [Drag](https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/Drag.ts): gesture module · Detects drag gestures and movement events · `packages/core/src/modules/Drag.ts`
- [Swipe](https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/Swipe.ts): gesture module · Detects swipe gestures from pointer motion · `packages/core/src/modules/Swipe.ts`
- [WheelPanZoom](https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/WheelPanZoom.ts): gesture module · Maps wheel input to pan and zoom gestures · `packages/core/src/modules/WheelPanZoom.ts`
- [MultitouchPanZoom](https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/MultitouchPanZoom.ts): gesture module · Handles multi-touch pan and zoom interactions · `packages/core/src/modules/MultitouchPanZoom.ts`
- [PreventDefault](https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/PreventDefault.ts): behavior module · Only module that mutates DOM defaults to suppress native behavior · `packages/core/src/modules/PreventDefault.ts`
- [Lubricator](https://github.com/hesprs/pointeract/blob/main/packages/core/src/modules/Lubricator.ts): behavior module · Adjusts interaction handling to smooth gesture flow · `packages/core/src/modules/Lubricator.ts`
- [Core tests](https://github.com/hesprs/pointeract/blob/main/packages/core/tests/integration.test.ts): test suite · Gesture and integration coverage for the runtime · `packages/core/tests/integration.test.ts`
- [Dev harness](https://github.com/hesprs/pointeract/blob/main/packages/core/tests/dev/index.html): browser tests · Browser-based interaction harness for real DOM scenarios · `packages/core/tests/dev/index.html`

### Docs site

VitePress documentation and playground

- [Docs site](https://github.com/hesprs/pointeract/blob/main/docs/.vitepress/config.ts): vitepress site · User documentation and playground examples · `docs/.vitepress/config.ts`
- [Playground](https://github.com/hesprs/pointeract/blob/main/docs/components/playground.vue): docs component · Interactive example component embedded in docs · `docs/components/playground.vue`

### CI and release

GitHub Actions workflows

- [CI test](https://github.com/hesprs/pointeract/blob/main/.github/workflows/ci-test.yml): workflow · Automated test gate for repository changes · `.github/workflows/ci-test.yml`
- [CI docs](https://github.com/hesprs/pointeract/blob/main/.github/workflows/ci-docs.yml): workflow · Documentation checks and site validation · `.github/workflows/ci-docs.yml`
- [Publish](https://github.com/hesprs/pointeract/blob/main/.github/workflows/publish.yml): workflow · Release workflow for npm distribution · `.github/workflows/publish.yml`

## Connections

- Workspace → Public API: contains · Workspace includes the core package entrypoint
- Workspace → Shared: contains · Workspace includes the shared internal package
- Workspace → Docs site: contains · Workspace includes the documentation site
- Public API → Pointeract: exports · Public API exposes the runtime orchestrator
- Public API → BaseModule: exports · Public API exposes the module base class
- Public API → Types: exports · Public API exposes shared library types
- Pointeract → BaseModule: loads · Orchestrator instantiates and manages modules through the shared contract
- Pointeract → Utils: uses · Runtime uses internal helpers for consistent gesture processing
- Pointeract → Types: uses · Runtime routes typed interaction state and emitted events
- BaseModule → Click: implements · Concrete modules follow the shared lifecycle contract
- BaseModule → Drag: implements · Concrete modules follow the shared lifecycle contract
- BaseModule → Swipe: implements · Concrete modules follow the shared lifecycle contract
- BaseModule → WheelPanZoom: implements · Concrete modules follow the shared lifecycle contract
- BaseModule → MultitouchPanZoom: implements · Concrete modules follow the shared lifecycle contract
- BaseModule → PreventDefault: implements · Concrete modules follow the shared lifecycle contract
- BaseModule → Lubricator: implements · Concrete modules follow the shared lifecycle contract
- Click → Utils: uses · Gesture detection relies on shared helpers
- Drag → Utils: uses · Gesture detection relies on shared helpers
- Swipe → Utils: uses · Gesture detection relies on shared helpers
- WheelPanZoom → Utils: uses · Gesture detection relies on shared helpers
- MultitouchPanZoom → Utils: uses · Gesture detection relies on shared helpers
- PreventDefault → Types: uses · Behavior module participates in the shared event contract
- Lubricator → Types: uses · Behavior module participates in the shared event contract
- Core tests → Click: covers · Dedicated tests validate click behavior
- Core tests → Drag: covers · Dedicated tests validate drag behavior
- Core tests → Swipe: covers · Dedicated tests validate swipe behavior
- Core tests → WheelPanZoom: covers · Dedicated tests validate wheel pan/zoom behavior
- Core tests → MultitouchPanZoom: covers · Dedicated tests validate multitouch pan/zoom behavior
- Core tests → Lubricator: covers · Dedicated tests validate lubricator behavior
- Dev harness → Pointeract: exercises · Browser harness drives the runtime in a real DOM
- Docs site → Playground: includes · Docs site embeds an interactive playground
- Docs site → Public API: documents · Docs explain library usage and API concepts
- Docs site → Click: documents · Docs include module guides and examples
- Docs site → Drag: documents · Docs include module guides and examples
- Docs site → Swipe: documents · Docs include module guides and examples
- Docs site → WheelPanZoom: documents · Docs include module guides and examples
- Docs site → MultitouchPanZoom: documents · Docs include module guides and examples
- CI test → Core tests: runs · CI gates changes on the core test suite
- CI docs → Docs site: runs · CI validates the documentation site
- Publish → Public API: publishes · Release workflow packages the core library