# meilisearch/meilisearch-rails architecture

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

- Interactive diagram: https://gitdiagram.com/meilisearch/meilisearch-rails
- Repository: https://github.com/meilisearch/meilisearch-rails

## Overview

##### Main components
- Meilisearch::Rails Gem Core – This is the heart of the gem, found in the “lib” directory. It contains modules (for example, configuration, job handling, multi_search, pagination adapters for Kaminari, WillPaginate, and Pagy, etc.) that plug into Rails models.
- Rails Application Integration – The gem is designed to be “included” in Rails models. Show that a Rails application (like the “playground” folder) uses the gem through mixins, initializers (e.g. config/initializers/meilisearch.rb), and ActiveRecord callbacks for auto-indexing and removal.
- External Meilisearch Service – Represent the external Meilisearch engine that the gem communicates with via HTTP (using the provided configuration options such as MEILISEARCH_HOST and API key).
- Background Jobs/Queueing Mechanism – Illustrate the optional integration with background processing systems (ActiveJob, Sidekiq, DelayedJob) that handle asynchronous indexing tasks.
- Testing & CI/CD – Although not part of runtime architecture, include components like the spec suite and GitHub workflows that are used for automated testing and releases.

##### Relationships and data flow
- The Rails model (e.g., Book, Author) includes the Meilisearch::Rails module, invoking methods that transform model data into search-ready documents.
- Upon create/update/destroy, callbacks trigger gem methods which send HTTP requests (indexing, deletion) to the Meilisearch API.
- For asynchronous operations, background job components are enqueued; these jobs (implemented in lib/meilisearch/rails/ms_job.rb or ms_clean_up_job.rb) then communicate with the Meilisearch API.
- The configuration initializer and rake tasks coordinate with the gem to set up environment-specific settings, index names, and pagination configurations.
- Optionally, multi-search and federated search functionalities allow combining search results from various models (or indexes) and require the gem to orchestrate responses from multiple HTTP requests to Meilisearch.

##### Important architectural patterns and design choices
- Modular Integration – The gem is structured as a modular library that plugs into Rails through mixins, so emphasize strong encapsulation of indexing/search logic within the “lib” folder.
- Callback-Driven synchronization – Rails ActiveRecord callbacks are extended (and sometimes overridden) to keep the Meilisearch index in sync.
- Configurable Extensibility – The gem uses initializer configuration (and even custom blocks in the “meilisearch” DSL) to allow developers to customize attributes, primary keys, conditions for indexing, and even share indexes between models.
- Asynchronous Processing – The ability to define custom job enqueuing (ActiveJob, Sidekiq, etc.) is an important pattern and should be clearly delineated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Rails Application Integration"
        A1["Initializer"]:::rails
        A2["Rails Models"]:::rails
    end

    subgraph "Meilisearch::Rails Gem"
        B1["Gem Core [File]"]:::gem
        B1a["Gem Core [Modules]"]:::gem
        B2["Multi Search"]:::gem
        B2a["Multi Search Modules"]:::gem
        B3["Pagination Adapters"]:::gem
        B4["Rake Tasks"]:::gem
        B5["Initializer Template"]:::gem
    end

    subgraph "Background Job Queue"
        BG1["Indexing Job"]:::job
        BG2["Clean-up Job"]:::job
    end

    subgraph "Development & Testing"
        T1["Test Suite"]:::dev
        T2["CI/CD Pipelines"]:::dev
    end

    ES["Meilisearch Service (External)"]:::external

    %% Relationships
    A1 -->|"configures"| B1
    A2 -->|"includesGemMixins"| B1
    B1 -->|"loadsModules"| B1a
    B1 -->|"triggersMultiSearch"| B2
    B1 -->|"utilizesPagination"| B3
    B1 -->|"providesRakeTasks"| B4
    B1 -->|"providesTemplate"| B5
    B1 -->|"enqueuesJob"| BG1
    B1 -->|"enqueuesJob"| BG2
    B1 -->|"syncCall"| ES
    BG1 -->|"executesIndexing"| ES
    BG2 -->|"executesCleanup"| ES
    ES -->|"returnsResults"| A2
    T1 -->|"tests"| B1
    T2 -->|"CI_CDfeeds"| B1
    B2 -->|"includesModules"| B2a

    %% Click Events
    click A1 "https://github.com/meilisearch/meilisearch-rails/blob/main/playground/config/initializers/meilisearch.rb"
    click A2 "https://github.com/meilisearch/meilisearch-rails/tree/main/playground/app/models/"
    click B1 "https://github.com/meilisearch/meilisearch-rails/blob/main/lib/meilisearch-rails.rb"
    click B1a "https://github.com/meilisearch/meilisearch-rails/tree/main/lib/meilisearch/rails"
    click BG1 "https://github.com/meilisearch/meilisearch-rails/blob/main/lib/meilisearch/rails/ms_job.rb"
    click BG2 "https://github.com/meilisearch/meilisearch-rails/blob/main/lib/meilisearch/rails/ms_clean_up_job.rb"
    click B2 "https://github.com/meilisearch/meilisearch-rails/blob/main/lib/meilisearch/rails/multi_search.rb"
    click B2a "https://github.com/meilisearch/meilisearch-rails/tree/main/lib/meilisearch/rails/multi_search"
    click B3 "https://github.com/meilisearch/meilisearch-rails/tree/main/lib/meilisearch/rails/pagination"
    click B4 "https://github.com/meilisearch/meilisearch-rails/blob/main/lib/meilisearch/rails/tasks/meilisearch.rake"
    click B5 "https://github.com/meilisearch/meilisearch-rails/blob/main/lib/meilisearch/rails/templates/initializer.rb"
    click T1 "https://github.com/meilisearch/meilisearch-rails/tree/main/spec"
    click T2 "https://github.com/meilisearch/meilisearch-rails/blob/main/.github"

    %% Styles
    classDef rails fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef gem fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef job fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef external fill:#FFC0CB,stroke:#000,stroke-width:1px;
    classDef dev fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
