case study · integration

A search engine that understands “kubke”

Fast, Algolia-powered product search for a store on the Shoper platform, which has no off-the-shelf integration. A custom sync service, search-as-you-type suggestions and a filterable results page, embedded in the store theme with a single file.

Platform
Shoper (Storefront theme)
Search
Algolia
Scope
Specification, backend, frontend, deployment
Method
Spec-Driven Development, 6 phases
store / suggestions
Search overlay: the misspelled query “kubke” (mug) returns mugs with thumbnails, prices and a sale price
A misspelled query still returns the right products, with a thumbnail, price and the struck-through regular price on sale items.

01 / challenge

Native search wasn't enough, and there was no ready-made integration

The store needed search that forgives typos, knows synonyms, shows results while typing and lets shoppers filter like in big stores. Shoper has no Algolia integration, so everything had to be built: from pulling the catalogue via the REST API to a component embedded in the theme. On top of that, part of the API's behaviour isn't covered by the public documentation.

  • req.01Full catalogue in the indexNames, descriptions, prices with promotions, availability, categories, manufacturers, images, attributes and variants.
  • req.02Search-as-you-typeProduct thumbnail, name and price, plus category suggestions.
  • req.03Results page with filtersCategories, manufacturer, price, availability, attributes; sorting by relevance, price and newest.
  • req.04RelevanceTypos, synonyms, Polish inflection; in-stock products ranked above unavailable ones.
  • req.05Up-to-date dataStore changes and stock updates after orders appear in search automatically.
  • req.06Consistent lookMatches the store theme and fully supports phones.

02 / principles

Specification first, code second. And no guessing

The work followed Spec-Driven Development: the specification was approved before the first line of code, and every phase ended with a summary and a commit. Every claim about the Shoper API had a status in the spec, and assumptions became facts only after being checked against real responses.

✓ verified against the API ? assumption to verify 68 findings moved from assumption to verified
Resilience

A webhook is just a signal

Every event ends in the same operation: rebuild the product record from current API data. Duplicates and out-of-order events can't corrupt the index.

Security

The admin key never reaches the browser

The frontend only gets a search-only key. The build fails if anything resembling an admin key shows up in the bundle.

Privacy

Only product IDs from orders

Order webhooks carry personal data. The service stores nothing but IDs, and Algolia analytics only starts after the shopper's consent.

Continuity

The store always has working search

Atomic index swaps, a guard against wiping the index and a fallback to Shoper's native search if Algolia fails. One flag switches the integration off.

03 / architecture

Three paths to an up-to-date index

A sync service in a single container receives webhooks, queues them and refreshes products. Every 20 minutes it pulls changes by modification date, and once a day it compares the whole catalogue with the index and fixes any drift. The browser talks to Algolia directly.

04 / delivered

From the REST API to a component in the theme

Sync service

  • Shoper REST client with throttling based on rate-limit headers, 429/5xx retries and pagination
  • Product → record mapper: price as shown on store listings, variants as filters, 3-level categories, HTML-free descriptions
  • Full import with atomic index swap and a guard against shrinking it by more than 20%
  • Product, order and category webhooks with checksum verification, a queue, retries and a dead-letter store
  • Incremental and daily reconciliation sync that writes only the differences

Search in the store

  • Overlay with product and category suggestions that takes over the native Storefront field on desktop and mobile
  • Results page: filters, 4 sort orders, pagination, slide-out filter panel on phones
  • Shareable URLs with filters and a working “back” button
  • Lowest price from the last 30 days on promotions (EU Omnibus directive)
  • Algolia Insights analytics only after consent from the store's consent module

Configuration & maintenance

  • Index settings, replicas, synonyms and filters in the repository, applied with one command
  • Filters derived from the “show in filters” settings in the Shoper admin
  • Rootless Docker image with a read-only file system
  • CI: tests, linters, dependency audit, bundle check
  • Runbook with a rollback procedure and a pre-production checklist

05 / result

Screenshots from a real store on the Storefront theme with a demo catalogue. Click a screenshot to enlarge it.

06 / what the real API showed

Things that weren't in the documentation

Verification against a live store and live Algolia caught behaviour that, if coded “from memory”, would have ended in silent bugs in production.

AreaWhat we foundSolution
Shoper paginationA page size above 50 silently falls back to 10.The client always requests at most 50.
API limitsA 429 response comes back as HTML, without Retry-After.Throttling based on X-Shop-Api-* headers and a custom backoff.
API filtersUnknown filter syntax is ignored and returns the whole catalogue.Every syntax is checked by a “future date returns 0 results” test.
WebhooksX-Webhook-Id identifies the configuration, not the delivery; events can arrive together a minute later.Content-based deduplication and idempotent refresh from the API.
Deleted orderIts items can no longer be fetched from the API, and stock is restored without changing the modification date.Product IDs taken from the webhook payload, with the daily reconciliation as a fallback.
Index swapThe atomic swap in the Algolia SDK hangs when the index doesn't exist yet.The first import writes directly; later ones swap with a timeout.
Algolia connectionThe SDK doesn't fail over to backup hosts on a DNS error.Custom retries for connection errors.
Storefront themeConsent is handled by a different API than in the older theme, and the store runs a Service Worker.Integration with the Storefront consent module and versioned script URLs.

07 / metrics

Numbers from the test deployment

~10s
from a product change in the admin to an updated search result
3.6s
full import of 82 products with variants
0
differences between store and index in the reconciliation sync
1.3KB
average record; the plan limit is 10 KB
139
automated tests, including 6 against the real store
68
API assumptions verified against the live store
0
known vulnerabilities in dependencies (pip-audit, npm audit)
5.5KB
compressed CSS; 119 KB JS loaded with defer

The metrics come from a test environment: a Shoper store (Storefront) with an 80-product demo catalogue and an Algolia app on the free plan. They are not the client's business data. Impact on conversion and zero-result searches is measured in Algolia Analytics after going live.

08 / process

Six phases, each closed with verification and a commit

  1. phase 0SpecificationScope, record model, flows, decisions, open questions.
  2. phase 1Data discoveryAPI client and anonymised responses as fixtures.
  3. phase 2Mapper & importRecords, Algolia configuration as code, CLI.
  4. phase 3UpdatesWebhooks tested on real deliveries, queue.
  5. phase 4FrontendSuggestions, results, e2e tests on the store.
  6. phase 5DeploymentDocker, CI, documentation, runbook.

stack

  • Python 3.12
  • FastAPI
  • httpx
  • pydantic
  • SQLite
  • algoliasearch
  • Autocomplete.js
  • InstantSearch.js
  • esbuild
  • Playwright
  • pytest
  • Docker
  • GitHub Actions
  • Shoper REST API

next steps

Ready to launch for the client

What remains before production are business decisions: the Algolia plan, the synonym list, the analytics scope and the availability rule. The architecture is ready for what comes next: recommendations, personalisation, blog content search and indices for more languages.

next step

Facing a similar challenge?

Tell me what you want to achieve. I'll come back with a concrete proposal, a quote and a delivery plan.