Meilisearch Architecture: How the Codebase Actually Works

Meilisearch is an open-source, Rust-based search engine: a self-hosted alternative to hosted search APIs, built around a fast full-text and vector-ranking core called milli. Symvanta's Louvain community detection organized the codebase into 53 functional modules (modularity Q=0.78, generated by Symvanta's code graph). The codebase's biggest jobs are product-shaped: IndexScheduler owns the durable, async task queue that every write (document ingestion, settings change, index swap) is enqueued onto and processed from; a Search/SearchContext pair builds and walks a query graph over the index; bucket_sort ranks candidates through an ordered chain of ranking rules; and Embedder wraps one of several pluggable providers (OpenAI, HuggingFace, a generic REST backend, or user-supplied vectors) for semantic search. The repository also vendors a full typed client for the OpenAI API (external-crates/async-openai) and carries its own large integration-test harness (crates/meilisearch/tests/common); both are real graph clusters but neither is Meilisearch's own architecture, so both are left out of the diagram and the subsystem sections below.

Module map

The diagram below shows the 10 largest of the 53 detected modules, sized by symbol count, with arrows weighted by how many calls cross between them. The two vendored/test clusters mentioned above are excluded from the diagram along with a dozen smaller vendored fragments (audit-log types, fine-tuning and vector-store types, message types) that all trace back to the same bundled OpenAI client crate: they are real graph nodes, just not Meilisearch's own architecture.

Where to start reading

These are the load-bearing entry points into the codebase, blended from the global PageRank ranking and the hub of each product-shaped module, plus the handful of HTTP routes most requests actually go through: start here to see how the pieces connect.

• IndexScheduler
• Task
• IndexMetadata
• Search
• OrderBy
• Interned
• Embedder
• Settings
• perform_search
• read_txn
• insert_object
• POST /indexes/{index_uid}/search
• POST /indexes/{index_uid}/documents
• PATCH /indexes/{index_uid}/settings
• POST /multi-search
• GET /tasks

A few of these are worth calling out individually. IndexScheduler is the hub of the Indexing and Scheduling cluster and the owner of every asynchronous write; its own read_txn method opens the LMDB read transaction most of the scheduler's read paths run inside. Task and IndexMetadata anchor the task-lifecycle and per-index configuration clusters respectively. Search and SearchContext (from Interned, the Search Indexing Components cluster) are the two structs that carry a query from HTTP request to ranking, and OrderBy is the sort-direction type that same cluster uses to build a query's ranking and sort order. Embedder is the hub of the Embedding Management cluster: one implementation per configured provider. Settings is the top-level, per-field-optional configuration object every PATCH /indexes/{index_uid}/settings call updates. perform_search is the request-level orchestrator traced in the canonical flow below, and insert_object comes from the flatten-serde-json crate that turns nested JSON documents into the flat field-value pairs the index stores. The five HTTP routes above are Meilisearch's primary surface: search, document writes, settings, multi-index search, and task status.

Key subsystems

Indexing and Scheduling

Manages the scheduling and identification of indexed features. Its hub, IndexScheduler, is the durable task queue every write passes through, alongside IndexUid/IndexUidPattern (index name validation) and RuntimeTogglableFeatures (the experimental-features gate). This cluster calls into the task-lifecycle cluster 359 times and into the search-tools cluster (OrderBy) 165 times, reflecting how much of index management ends up reading task state or search configuration back out.

Task Management System

Handles the lifecycle and state tracking of asynchronous operations. Task, TaskId, Status, and Kind model a single enqueued job (document addition, settings update, index swap, snapshot, and so on) from enqueued through processing to succeeded or failed. It is the most-called-into cluster on the map by a wide margin: every other module on the diagram calls into it, from 69 times (Configuration Management) up to the 521 calls described under Bitmap Codec Utilities below, plus 432 calls within its own cluster, the expected shape for a task table that both writes its own state and gets read back constantly by the scheduler that drives it.

Configuration Management

Manages application settings and metadata. IndexMetadata and Document sit alongside the Setting<T> wrapper type that lets every configurable field be explicitly "not set," "reset," or "set to a value" rather than defaulting silently. 69 calls back into the task cluster reflect that a settings change is itself dispatched as an asynchronous task.

Search Indexing Module

Manages the indexing and retrieval logic for searchable data. Its hub, Search, is the entry struct a query is built on (TermsMatchingStrategy, Criterion, ScoreDetails) before ranking runs; read_txn here is the index-level counterpart to the scheduler's own read-transaction helper. This cluster calls into filter-parser 36 times, the recursive-descent parser behind every filter= query parameter.

Search Indexing Tools

Provides utilities for ordering, indexing, and querying documents. OrderBy (sort direction), SearchHit (one result row), and ComputedFacets live here alongside SemanticRatio, the knob that blends keyword and vector scoring in a hybrid search. It calls into IndexScheduler's cluster 236 times, since building a search response routinely needs index and task state.

Search Indexing Components

Manages the internal structures for indexing and querying data. Interned (Meilisearch's interned-string type) and SearchContext carry the in-flight query graph (QueryGraph, QueryNode, LocatedQueryTermSubset) that the ranking-rule chain below walks. 249 calls into the task-lifecycle cluster and 112 into Search itself show this as the connective layer between a parsed query and the ranking engine.

Embedding Management

Handles the process of embedding and managing runtime fragments. Embedder is the hub, with Embedding, Prompt, RuntimeFragment, and FaultSource/DistributionShift (embedding-drift detection) as its immediate members. Each of the four provider modes, OpenAi, Rest, HuggingFace, and UserProvided, is defined on EmbedderOptions, the hub of a smaller cluster not drawn above (AI Service Integrations, 9 symbols), and implements the same embed interface. That shared interface is why the mutually recursive symbol groups below include six separate embedder new constructors.

Configuration Management #2

Handles application settings, persistence, and resets. Settings is the top-level struct PATCH /indexes/{index_uid}/settings deserializes into; Set/NotSet/Reset are the three states Setting<T> can carry, and SettingsAnalytics/EmbeddingSettings track what changed for telemetry. 301 calls into the task cluster confirm every settings write becomes a task, and 119 calls into the embedding cluster reflect how much of a settings payload is embedder configuration.

Shared infrastructure

Two large clusters round out the shared infrastructure everything above calls into, both named generically by Louvain's directory-based fallback rather than by a single descriptive concept. Data Processing Utilities (2058 symbols, the largest cluster on the map) centers on Index, DocumentId, FieldsIdsMap, and Progress: the core on-disk data model, and it calls out into nearly every other cluster on the map, most heavily into Bitmap Codec Utilities' bitmap codecs (484 calls) and the Search Indexing Module (288 calls). Bitmap Codec Utilities (854 symbols) centers on FieldId and the roaring-bitmap codecs (CboRoaringBitmapCodec, FacetGroupKeyCodec) that encode which documents match which field values on disk, and it makes the heaviest single cross-module call of anything on the map: 521 calls into the task-lifecycle cluster.

Canonical request flow

The representative flow traced here is a document search: what happens when a client calls POST /indexes/{index_uid}/search.

1. search_with_post (and its GET counterpart search_with_url_query), both in crates/meilisearch/src/routes/indexes/search.rs, parse the request and hand it to perform_search.
2. perform_search (crates/meilisearch/src/search/mod.rs) is the request-level orchestrator both handlers import. It resolves the query's display options (attributes_to_retrieve, attributes_to_crop, attributes_to_highlight, distinct), applies any dynamic search rules configured on the index, and builds a milli::Search.
3. Search::execute (or execute_hybrid when a semantic ratio is set, blending keyword and vector results) in crates/milli/src/search/mod.rs calls into execute_search (crates/milli/src/search/new/mod.rs).
4. execute_search resolves the ranking-rule chain for the query, via get_ranking_rules_for_query_graph_search for a text query or get_ranking_rules_for_placeholder_search for a filter-only browse, checks sort criteria and geo parameters, then calls bucket_sort.
5. bucket_sort (crates/milli/src/search/new/bucket_sort.rs) walks the ordered chain of BoxRankingRule implementations (typo tolerance, proximity, attribute, exactness, and configured sort criteria) over the candidate document set, applies apply_distinct_rule to drop duplicates by the configured distinct field, and returns a BucketSortOutput carrying document_scores, documents_ids, and a degraded flag for searches that hit the time budget.
6. Back in perform_search, compute_facet_distribution_stats builds ComputedFacets and the ranked documents are formatted into SearchHits for the JSON response.

Health signals

Symvanta detected 0 dependency cycles across the 53 modules (modularity Q=0.78): the module boundaries are clean, with no cluster depending on another in a loop.

13 sets of mutually recursive symbols were detected, all consistent with a single natural pattern: a function that walks a tree or expression grammar calling itself on the pieces it contains. The largest is the filter-parser crate's recursive-descent parser (7 symbols: parse_expression, parse_and, parse_or, parse_not, parse_primary, parse_foreign, parse_foreign_operator), which is exactly the shape a parser for a boolean filter grammar with nested AND/OR/NOT takes. Smaller groups appear in ranking_rule_graph (visit_node, visit_condition, visit_no_condition, walking the ranking-rule condition graph), fields_ids_map (inserting and looking up field IDs by name), and the permissive-json-pointer and flatten-serde-json crates that both recurse while walking nested JSON documents, one flattening them for indexing and the other mapping leaf values back out. A modularity Q of 0.78 with zero cycles indicates the 53 modules are cleanly separated: call traffic mostly stays within a module, and the handful of recursive groups above sit exactly where tree-walking and grammar parsing are expected to produce them.

For teams weighing a dedicated search engine against embedding search results straight into an existing store, code embeddings vs. code graph covers the same call-graph-vs-vector-similarity tradeoff from the code-search side.