Elasticsearch Search Platform: engineering search and relevance

A search platform built with Elasticsearch 8.15.3 and Django REST Framework, treating index design, text analysis, relevance, fuzzy matching, facets, pagination, and explainability as engineering problems.

Start a conversation View related solution

Context

A real search API is more than a match query. Search quality depends on index design, text analysis, relevance, filtering, sorting, pagination, and the ability to explain why a result was ranked. This project turns those concerns into an inspectable engineering platform.

Problem

The goal was to build a search API that handles compound requests predictably: boosted full-text queries, filters that do not distort scoring, stable sorting, pagination without skipped or duplicated results, and optional facets and score explanations.

Constraints & requirements

Keep domain logic independent of Django and Elasticsearch
Make relevance and field boosts explicit and tunable
Apply combined filters without unintended score changes
Provide stable pagination with a tie-breaker and search_after
Expose explainability for score inspection
Enforce architecture dependency rules through tests

Approach

The project is divided into Domain, Application, Infrastructure, and Presentation layers. Elasticsearch is confined to infrastructure adapters while application use cases depend on domain ports. The HTTP API exposes relevance, fuzzy search, autocomplete, facets, highlighting, and explainability through a consistent interface.

text

HTTP -> Presentation -> Application -> Domain
                              ^
                      Infrastructure -> Elasticsearch

Key decisions & trade-offs

Decision	Reason
Use filter context for filters	Filters should constrain results without changing relevance scores.
Stable sorting with a tie-breaker	Pagination should not skip or duplicate documents.
Keep domain independent of Elasticsearch	Business logic and use cases should not depend on the client or query DSL.
Treat explainability as a capability	Relevance should be inspectable rather than an opaque score.
Test architecture rules	Invalid layer dependencies should fail the build instead of remaining convention.

Outcome

The result is an executable, inspectable search platform covering full-text search, relevance tuning, fuzzy matching, filtering, facets, sorting, offset and cursor pagination, highlighting, and explainability. The project README reports 452 passing tests, with architectural dependency rules enforced mechanically. It demonstrates how a vague requirement such as “better search” can be decomposed into concrete problems in relevance, architecture, pagination, and validation.

Technical depth

Elasticsearch 8.15.3 with explicit mappings and text/keyword multi-fields
multi_match, match_phrase, bool, fuzzy, and function_score
Terms and range aggregations for facets
Stable search_after pagination with a tie-breaker
_explain for inspecting score contributions
Clean Architecture with test-enforced dependency rules

Evidence

The code, design documentation, and tests are publicly inspectable on GitHub.

GitHub — Elasticsearch Search Platform

The repository contains the API, architecture, relevance and search documentation, and project tests.

Open source

Working on a search or service-architecture problem?

For relevance, search behavior, performance, or service architecture problems, we can discuss scope and an appropriate path forward.

Start a conversation