# adoratorio/hades architecture

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

- Interactive diagram: https://gitdiagram.com/adoratorio/hades
- Repository: https://github.com/adoratorio/hades

## Overview

##### Project Type and Purpose
- Hades is a TypeScript library implemented as an npm package. Its purpose is to provide smooth scrolling functionality via a core system that manages scroll events and easing, while supporting different renderers (plugins) such as virtual or native rendering, drag-and-scroll, scrollbars, etc.
- It is designed as a modular, plugin-based system that internally uses external packages (Hermes for scroll event management and Aion for requestAnimationFrame management).

##### File Structure
- The top-level files (.gitignore, package.json, tsconfig.json, README.md) indicate a typical npm package/module project.
- The primary source code is located in the “src” folder. The main entry point is src/index.ts with supporting modules like easing.ts, Boundaries.ts, utils.ts, and declarations.ts.
- The “plugins” directory includes multiple subdirectories for each rendering or functional plugin (e.g., “drag-and-scroll”, “lenis-render”, “native-render”, “scrollbars”, “start-stop”, “virtual-render”). Each plugin folder contains its own README, declarations, and index files which exposes its own API and integration points.
- This layout clearly reflects the design choice of having a core engine (Hades) decoupled from its rendering and functional extensions via plugins.

##### README for Additional Architectural Insights
- The README confirms that Hades provides a core smooth scrolling engine and then relies on plugins to handle various rendering methods. It describes the API methods, including registerPlugin, scrollTo, play, pause, and destroy.
- It also clarifies the architecture with hooks provided in the plugin interface (register, wheel, preScroll, scroll, preFrame, render, destroy, scrollTo) that the plugins must implement.
- The integration with external tools (Hermes, Aion) is mentioned, reinforcing the decoupled design where Hades orchestrates scroll capture and animation while delegating rendering and other functionalities to plugins.

a. Main Components to be Represented:
- Hades Core:
– Represents the nucleus of the library with the internal scroll amount and velocity handling.
– Manages global options (easing, autoplay, touch multiplier, etc.) and provides public APIs (scrollTo, play, pause, destroy, etc.).
- Plugin Manager:
– Handles the registration, invocation, and unregistration of plugins.
- Plugins:
– Individual plugins (such as virtual render, native render, drag-and-scroll, scrollbars, start-stop) are depicted as separate components.
– Each follows the HadesPlugin interface with lifecycle hooks to integrate into the system.
- External Dependencies:
– Hermes: Responsible for event handling and scroll normalization.
– Aion: Manages animations and per-frame operations.
- Utility Modules:
– Auxiliary files like easing.ts and utils.ts provide supporting logic (e.g., easing functions, helper utilities).

b. Relationships and Interactions:
– preScroll and scroll hooks allow plugins to modify the scroll values.
– PreFrame and render hooks are invoked once per animation frame (managed by Aion/“render cycle”).
- That the Plugin Manager acts as a central registry for plugins; Hades calls methods like registerPlugin, registerPlugins, getPlugin, and unregisterPlugin.

c. Highlighted Architectural Patterns:
- Modular & Plugin-based Architecture: Emphasize the clear separation between core functionality and extensible plugin modules.
- Event-driven Design: Display that scroll events are handled by Hermes and then propagated through the system.
- Frame-based Update Cycle: Use Aion for managing the animation frame updates with easing applied in the rendering phase.
- Dependency Injection: Hades allows external instances of Aion to be injected and manages plugin lifecycle externally.

d. Relevant Technologies and Frameworks:
- Written in TypeScript.
- Uses npm (package.json, package-lock.json).
- Relies on external packages: Hermes for scroll events, Aion for requestAnimationFrame.

##### Elements
– Hermes → Hades Core (provides scroll events)
– Hades Core → Plugin Manager (manages registration and lifecycle interactions)
– Hades Core → Plugins (calls hooks such as wheel, preFrame, render, etc.)
– Aion → Hades Core (controls frame-based updates)
– Core engine components (e.g., rectangles)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Dependencies"
        Hermes["Hermes - Scroll Events"]:::external
        Aion["Aion - Animation Manager"]:::external
    end

    HadesCore["Hades Core"]:::core
    Utils["Utility Modules"]:::utility
    PluginManager["Plugin Manager"]:::manager

    subgraph "Plugins"
        DragScroll["Drag-and-Scroll Plugin"]:::plugin
        LenisRender["Lenis Render Plugin"]:::plugin
        NativeRender["Native Render Plugin"]:::plugin
        Scrollbars["Scrollbars Plugin"]:::plugin
        StartStop["Start-Stop Plugin"]:::plugin
        VirtualRender["Virtual Render Plugin"]:::plugin
    end

    Hermes -->|"scrollEvents"| HadesCore
    Aion -->|"frameUpdates"| HadesCore
    HadesCore -->|"utilizeEasing"| Utils
    HadesCore -->|"registerPlugin"| PluginManager

    PluginManager -->|"invokeHooks"| DragScroll
    PluginManager -->|"invokeHooks"| LenisRender
    PluginManager -->|"invokeHooks"| NativeRender
    PluginManager -->|"invokeHooks"| Scrollbars
    PluginManager -->|"invokeHooks"| StartStop
    PluginManager -->|"invokeHooks"| VirtualRender

    click HadesCore "https://github.com/adoratorio/hades/blob/master/src/index.ts"
    click HadesCore "https://github.com/adoratorio/hades/blob/master/src/declarations.ts"
    click HadesCore "https://github.com/adoratorio/hades/blob/master/src/easing.ts"
    click HadesCore "https://github.com/adoratorio/hades/blob/master/src/Boundaries.ts"
    
    click PluginManager "https://github.com/adoratorio/hades/blob/master/src/plugins/index.ts"
    
    click DragScroll "https://github.com/adoratorio/hades/tree/master/src/plugins/drag-and-scroll"
    click LenisRender "https://github.com/adoratorio/hades/tree/master/src/plugins/lenis-render"
    click NativeRender "https://github.com/adoratorio/hades/tree/master/src/plugins/native-render"
    click Scrollbars "https://github.com/adoratorio/hades/tree/master/src/plugins/scrollbars"
    click StartStop "https://github.com/adoratorio/hades/tree/master/src/plugins/start-stop"
    click VirtualRender "https://github.com/adoratorio/hades/tree/master/src/plugins/virtual-render"
    
    click Utils "https://github.com/adoratorio/hades/blob/master/src/utils.ts"

    classDef core fill:#bbf,stroke:#333,stroke-width:2px,color:#000;
    classDef manager fill:#fdd,stroke:#333,stroke-width:2px,color:#000;
    classDef plugin fill:#fcf,stroke:#333,stroke-width:2px,color:#000;
    classDef external fill:#cff,stroke:#333,stroke-width:2px,color:#000;
    classDef utility fill:#efe,stroke:#333,stroke-width:2px,color:#000;
```
