hesprs/pointeract

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.