# ddnexus/pagy architecture

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

- Interactive diagram: https://gitdiagram.com/ddnexus/pagy
- Repository: https://github.com/ddnexus/pagy

## Overview

##### Main Components
- Core Library Module – The central pagination logic is implemented in the gem’s core (look at gem/lib/pagy.rb and its supporting files under gem/lib/pagy/…) which provides the fundamental functionality.
- Extras Modules – There are many optional integration modules for additional features (e.g., calendar pagination, keyset pagination, countless, headers, JSON:API, CSS framework helpers like bootstrap, bulma, tailwind, etc.) that extend or plug into the core.
- Frontend Integration – The gem provides view helpers in the frontend (pagy_nav, pagy_nav_js, pagy_info, etc.) and associated JavaScript/TypeScript components (supported via the src and gem/javascripts directories) to enhance client-side rendering.
- Configuration & Initializers – Files in gem/config and perhaps some of the Rake tasks are used to configure defaults for pagination behavior.
- Testing & CI – The repository is thoroughly tested, with Ruby tests (located under test/), end-to-end tests using Cypress (e2e/), and CI workflows (.github/workflows) that automate builds and releases.
- Documentation & Examples – Extensive documentation is provided in the docs folder (with API, extras, how-to guides) and playground examples showing integration scenarios.
- Build & Release Infrastructure – The tasks, Rakefile, versioning (CHANGELOG, Gemfile), and GitHub release workflows indicate a well-organized release and development process.

##### Relationships and Interactions
- The Core Library is the central engine that all other components rely on. It exposes backend functions (for wrapping collections with pagy) and frontend view helpers.
- Extras modules “plug in” to augment the core functionality. They are loaded in an initializer and then mix into the main module to support integrations with ActiveRecord, Sequel, JSON rendering, search frameworks, CSS frameworks, etc.
- The frontend components are designed to be used in views of web frameworks. They interact with the backend by receiving the pagy instance and rendering the corresponding navigation and pagination information.
- The testing layers (both Ruby and JavaScript E2E tests) interact with the core and extras – verifying that pagination works correctly across multiple scenarios and environments.
- CI workflows and tasks automate code quality checks, test runs, and documentation builds before publishing the gem.

##### Important Architectural Patterns and Technologies
- Modular Design and Mixins: The gem employs Ruby’s module and mixin features, segregating the backend and frontend functionalities and then enabling extras to extend these.
- Separation of Concerns: There is a clear separation between the core logic, the user-interface rendering, and integration “extras.”
- Integration Points: The project supports multiple integration environments including server-side Ruby frameworks and client-side JavaScript (as indicated by the src, gem/javascripts, and e2e directories).
- Testing and CI/CD: With dedicated tests and GitHub workflows, the project emphasizes robust testing and continuous integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Application Controllers/Views"]:::external
    B["Core Pagy Engine"]:::backend
    C["Extras Modules"]:::backend
    D["Frontend Integration"]:::frontend
    D2["JS Components"]:::frontend
    D3["TypeScript Components"]:::frontend
    E["Configuration & Initializers"]:::backend
    F1["Ruby Tests"]:::infra
    F2["E2E Tests"]:::infra
    G["CI Workflows"]:::infra
    H["Documentation & Examples"]:::infra
    H2["Examples"]:::infra
    I["Build & Release Infrastructure"]:::infra
    I2["Rake Tasks"]:::infra
    I3["Build Scripts"]:::infra

    %% Connections
    A -->|"pagyCall"| B
    E -->|"configures"| B
    B -->|"extends"| C
    B -->|"renders"| D
    D -->|"includes"| D2
    D -->|"includes"| D3
    F1 -->|"validates"| B
    F2 -->|"validates"| B
    G -->|"automates"| B
    I -->|"builds"| B
    I -->|"includes"| I2
    I -->|"includes"| I3
    H -->|"documents"| B
    H -->|"provides"| H2

    %% Click Events
    click B "https://github.com/ddnexus/pagy/blob/master/gem/lib/pagy.rb"
    click C "https://github.com/ddnexus/pagy/tree/master/gem/lib/pagy/extras/"
    click D "https://github.com/ddnexus/pagy/blob/master/gem/lib/pagy/frontend.rb"
    click D2 "https://github.com/ddnexus/pagy/tree/master/gem/javascripts/"
    click D3 "https://github.com/ddnexus/pagy/blob/master/src/pagy.ts"
    click E "https://github.com/ddnexus/pagy/blob/master/gem/config/pagy.rb"
    click F1 "https://github.com/ddnexus/pagy/tree/master/test/"
    click F2 "https://github.com/ddnexus/pagy/tree/master/e2e/"
    click G "https://github.com/ddnexus/pagy/tree/master/.github/workflows/"
    click H "https://github.com/ddnexus/pagy/tree/master/docs/"
    click H2 "https://github.com/ddnexus/pagy/blob/master/playground.md"
    click I "https://github.com/ddnexus/pagy/tree/master/Rakefile"
    click I2 "https://github.com/ddnexus/pagy/tree/master/tasks/"
    click I3 "https://github.com/ddnexus/pagy/tree/master/scripts/"

    %% Styles
    classDef backend fill:#FFD700,stroke:#333,stroke-width:2px
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px
    classDef infra fill:#90EE90,stroke:#333,stroke-width:2px
    classDef external fill:#FFB6C1,stroke:#333,stroke-width:2px
```
