# woylie/flop architecture

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

- Interactive diagram: https://gitdiagram.com/woylie/flop
- Repository: https://github.com/woylie/flop

## Overview

##### Major Components
- Core Library Modules: At the heart of the project is the “Flop” module (in lib/flop.ex) that ties together functionality for filtering, ordering, and paginating Ecto queries.
- Adapter Layer: Under “lib/flop/adapter”, especially in “ecto” subdirectories, you see the specific adapters (e.g., lib/flop/adapter/ecto.ex and its operators) responsible for integrating Flop with the Ecto database layer.
- Custom Types & Utility Modules: Modules like “lib/flop/custom_types” and modules such as “Flop.Filter”, “Flop.Meta”, “Flop.Schema”, “Flop.Cursor”, “Flop.Validation”, and “Flop.Relay” encapsulate core business logic (validation, pagination meta, filtering operations, and also Relay (cursor based) formatters).
- Configuration/Integration Modules: Configuration files in “config/” and the mix.exs file set up project dependencies and establish default behaviors (for example, linking to a default repo).
- Testing & Support: The “test/” directory shows a detailed test hierarchy for each component (including adapter tests for Ecto on different databases like PostgreSQL and SQLite, custom types tests, etc.) along with support modules which simulate domain models (like pet, owner, vegetable, etc.) to exercise the functionality.
- Documentation & Cheatsheets: The README and the “cheatsheets” directory provide quick reference designs and usage instructions, especially guiding the integration with Phoenix and Absinthe Relay.

##### Relationships & Interactions
- The core functions (e.g., Flop.validate_and_run/3, Flop.validate/2, Flop.run/3) will be the entry point for any query modification tasks.
- Once parameters are received (either from a Phoenix controller/resolver or directly), the validation modules check and validate the provided parameters.
- Then, the adapter layer (Flop.Adapter.Ecto) is used to transform the validated parameters into appropriate Ecto queries by applying filters, join conditions, ordering, and pagination logic.
- The “Flop.Relay” module comes into play for scenarios that require Relay-compatible pagination, transforming query results into a “connection” response with edges and PageInfo.
- Custom types (defined under lib/flop/custom_types) add flexibility to support additional data types or specialized filtering beyond the built-ins.
- Testing modules simulate various components and scenarios – this verifies that the interactions between the validation, adapter, and the main library are correct across different backends (e.g., PostgreSQL vs. SQLite).

##### Architectural Patterns & Design Principles
- Separation of Concerns: There is a clear separation between validation (Flop.Validation), query adaptation (Flop.Adapter), and formatting (Flop.Relay). This modular approach makes the library highly reusable and testable.
- Extensibility: The design allows for customizations via user-defined schemas (see Flop.Schema) to explicitly declare which fields are sortable/filterable, and also via custom types to extend beyond the default behavior.
- Integration with Third-Party Systems: The library smoothly integrates with Ecto for DB querying, and with Phoenix/Absinthe (via Flop Phoenix and Flop.Relay) to cater to web applications and GraphQL APIs.

- On the left, show the “Input Layer” (parameter intake, validation modules).
- In the center, the “Business Logic” area including adapters (Ecto integration) and core functions (sorting, filtering, pagination, metadata generation).
- On the right, the “Output Layer” (result formatting via Flop.Relay and any helper utilities for URL generation and UI).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Integration
    consumer["Consumer Integration"]:::external

    %% Input Layer
    subgraph "Input Layer"
        schema["Schema (Flop.Schema)"]:::input
        validation["Validation (Flop.Validation)"]:::input
        filter["Filtering Logic (Flop.Filter)"]:::input
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        core["Flop Core (lib/flop.ex)"]:::core
        %% Adapter Layer Subgraph
        subgraph "Adapter Layer"
            adapterCore["Adapter Core (lib/flop/adapter/ecto.ex)"]:::core
            adapterOps["Adapter Operators (lib/flop/adapter/ecto/operators.ex)"]:::core
        end
        custom["Custom Types (lib/flop/custom_types)"]:::core
        paginationMeta["Pagination Meta (Flop.Meta)"]:::core
        cursor["Cursor-Based Pagination (Flop.Cursor)"]:::core
    end

    %% Output Layer
    subgraph "Output Layer"
        relay["Relay Formatter (Flop.Relay)"]:::output
    end

    %% Supporting Components
    mixExs["mix.exs"]:::support
    config["Configuration Files (config/)"]:::support
    readme["README.md"]:::support
    cheatsheets["Cheatsheets (cheatsheets/)"]:::support
    testing["Testing & Support (test/)"]:::support

    %% Data Flow
    consumer -->|"sends params"| schema
    consumer -->|"sends params"| validation
    consumer -->|"sends params"| filter

    schema --> core
    validation --> core
    filter --> core

    core --> adapterCore
    core --> adapterOps
    core --> custom
    core --> paginationMeta
    paginationMeta --> cursor
    core --> relay
    relay -->|"returns results"| consumer

    %% Supporting Dependencies (dotted lines)
    mixExs --- core
    config --- core
    readme --- core
    cheatsheets --- core
    testing --- core

    %% Click Events
    click core "https://github.com/woylie/flop/blob/main/lib/flop.ex"
    click adapterCore "https://github.com/woylie/flop/blob/main/lib/flop/adapter/ecto.ex"
    click adapterOps "https://github.com/woylie/flop/blob/main/lib/flop/adapter/ecto/operators.ex"
    click custom "https://github.com/woylie/flop/tree/main/lib/flop/custom_types"
    click filter "https://github.com/woylie/flop/blob/main/lib/flop/filter.ex"
    click paginationMeta "https://github.com/woylie/flop/blob/main/lib/flop/meta.ex"
    click cursor "https://github.com/woylie/flop/blob/main/lib/flop/cursor.ex"
    click relay "https://github.com/woylie/flop/blob/main/lib/flop/relay.ex"
    click schema "https://github.com/woylie/flop/blob/main/lib/flop/schema.ex"
    click validation "https://github.com/woylie/flop/blob/main/lib/flop/validation.ex"
    click mixExs "https://github.com/woylie/flop/blob/main/mix.exs"
    click config "https://github.com/woylie/flop/blob/main/config/config.exs"
    click readme "https://github.com/woylie/flop/blob/main/README.md"
    click cheatsheets "https://github.com/woylie/flop/blob/main/cheatsheets/schema.cheatmd"
    click testing "https://github.com/woylie/flop/tree/main/test/"

    %% Styles
    classDef input fill:#D1E8FF,stroke:#1f78b4,stroke-width:2px;
    classDef core fill:#FFD700,stroke:#FFA500,stroke-width:2px;
    classDef output fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef support fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
```
