EdgeReco
Search and product recommendations for online stores — from independent shops to large catalogs — running in each shopper's browser instead of a paid server.
Try the demo store at edge-reco.com. Nothing to install.
Most online stores rent their search box and their "you might also like" rows from a
cloud service that charges per search. The bill grows with traffic, and you pay for
enough capacity to survive your busiest day. Many small stores skip it and live with a
plain keyword search, which misses what shoppers mean: type "something for my aching
back" and it only finds products whose titles happen to contain the word "back".
EdgeReco does the searching and ranking inside the shopper's browser tab. Your store
publishes signed catalog bundles: a 4.7 MB starter for the first paint, then the
full 100,000-product catalog (about 36 MB) in the background. The browser verifies every
chunk, searches by meaning as well as by words, and re-ranks recommendations as the
shopper clicks. No server answers the searches, so the application and inference cost
does not grow with traffic, and the store keeps working offline.
Technical docs: Architecture · Getting started for developers · Python library and CLI · Security and privacy · Deploy
The Black Friday problem
A recommendation row is cheap per shopper and brutal at peak. On Black Friday, traffic
can multiply while every product page still asks for "recommended for you", "customers
also bought", and search-as-you-type. A hosted search or recommendation service charges
per request and has to be provisioned for the busiest hour; inference capacity sits idle
most of the year, then becomes the bottleneck exactly when revenue is concentrated.
EdgeReco moves that work to the shopper's device. The catalog and ranking data are
signed static assets served by a CDN. The browser downloads them once, verifies them,
and runs search and re-ranking locally. The retailer pays no per-query application or
inference cost; a traffic spike adds CDN bytes and uses the shopper's own CPU, not a
queue of API calls or a fleet sized for the worst hour.
For a Fortune 500 catalog, that is an offload layer: keep the systems of record,
pricing, and checkout in the cloud, but stop paying per recommendation and stop making
the recommendation service the scaling bottleneck. Every shopper uses the same signed
bundle; a price change ships as a few changed chunks.
Illustratively, if a store serves N shoppers with R recommendation requests each and
its vendor charges p per request, the hosted bill is roughly N × R × p. EdgeReco
replaces that with a bundle download per new device plus CDN egress; after the bundle is
cached, another request adds no server work. Plug in your own vendor price — the point is
the shape, not a quoted rate.
This is not a replacement for a multi-million-item merchandising platform. It is an edge
tier for the 100,000-SKU range and for the high-volume rows where per-request pricing
hurts most.
Try it
- Open edge-reco.com and click Launch the live demo. This
opens the EdgeReco demo store with 100,000 products across 12 departments. The
first launch fetches a 4.7 MB starter, then upgrades to the full catalog and loads
the small language model on the first semantic search, so give it a moment. Later
visits start from the copy in your browser.
- Type
something for my aching back in the search box and press Enter.
A neck and back massager comes first, then a stadium seat with back support. Only three
products come back, because nothing else in the store is a good match. The strip under
the search box shows 0 backend calls: the search ran in your tab. Its other
numbers (search time, start-up time, memory) are measured live on your machine and vary.
- Click the heart or the cart button on the massager. Scroll down to Recommended
for you. The counter next to it goes to 1, then 2 signals, and the row re-orders
toward the massager's category (Health & Household). Those signals are saved only in
your browser. Reset taste clears them.
- Click ⚡ Apply delta in the top metrics bar to simulate a live price update.
Because the catalog ships as a page-aligned SQLite database split into content-addressed
chunks, your browser downloads only the 2 changed chunks (about 32 KB) and reuses the
other 2,059 chunks from its local cache — updating prices in place without reloading the
page or the language model.
How it works
The store builds its catalog once: a prebuilt SQLite database (catalogue.sqlite) holding
the products, FTS5 keyword index, and quantized 384-d sqlite-vector embeddings, plus the
ranking weights. It signs that bundle with a private key. The shopper's
browser downloads the bundle, checks every piece against a public key built into the app,
and refuses to load anything that does not match. When products or prices change, the
browser compares the new signed manifest against its cached chunks, downloads only the
changed SQLite pages, and swaps the catalog in place. After that, each search runs a
keyword match and a meaning match side by side inside SQLite, merges the two lists, and
re-orders the result using what this shopper has clicked.
Your data stays on your device
No user data leaves the device. What you click, view, favorite or add to the cart is
stored only in a SQLite database inside your own browser, and nothing is sent to or
stored on any server or cloud. The data is yours. Wipe it with Reset taste or by
clearing the site's data in your browser. There is no export/import yet.
If your browser won't let the tab keep a database (private mode, or the store is open in
another tab), the store still works but forgets your activity on reload, and a note at
the top says so.
EdgeReco is built on three sibling projects by the same author:
- edgeproc-browser (
@gainratio/browser)
does the download, signature check and offline storage in the browser.
- edge-proc does the same job for the optional
Python side: it publishes and syncs the signed catalog, and searches it on a server.
- edgeproc-core is a small Python library
edge-proc uses to organise its search index.
EdgeReco adds the store-specific part: the ranking formula, the shopper's session
signals and the demo store. privacy-core is
a separate, unrelated project (it hides personal data in AI prompts).
What it does not do
- Multi-million-item catalogs. It is built for tens to hundreds of thousands of products
(the demo ships 100,000), not tens of millions. Search is an exact scan in SQLite with no
approximate index, and the whole catalog database is downloaded.
- Private catalogs. Every shopper gets the full catalog file, so anything in it is
public.
- Low-memory phones. A first visit fetches a 4.7 MB starter, then about 36 MB of
full catalog plus a ~24 MB model in the background; it needs real memory and has not
been measured on physical phones yet.
- A hosted service. You build the catalog and host the static files yourself.
- Merchandising tools. There is no dashboard, A/B testing or manual boosting. Ranking
is tuned by editing weights in the signed catalog.
- Proof of each result. The "why?" panel shows how a score was calculated and checks
that the ranking settings were signed. It does not prove that a specific displayed
result came from those settings.
When to use something else
| If you need | Use |
|---|
| Millions of products, merchandising tools, and a vendor who runs it | A hosted search and recommendation service |
| Shoppers who search by exact product names only | Your store platform's built-in search |
| A catalog that must stay private | Your own search server behind an API |
| Up to ~100,000 products, flat cost, offline use, nothing to run per search | EdgeReco |
| A Fortune 500 peak-traffic offload tier in front of an existing catalog | EdgeReco for the high-volume rows; keep the system of record hosted |
Run it yourself
You need Node 24.16 (see frontend/.nvmrc) and pnpm, which
corepack provides.
git clone https://github.com/gainratio/edge-reco
cd edge-reco/frontend
corepack enable
pnpm install
pnpm -F frontend run build:pages
pnpm -F frontend exec vite preview
Open http://localhost:4173 and click Launch the live demo. On a fresh clone the
install took 12 seconds and the build 17 seconds. The build downloads the language model
and its runtime once and checks each against a pinned fingerprint.
The optional Python library, command line tool and API server need Python 3.13 and
uv. See docs/USAGE.md.
Develop
make gate
This runs the backend checks (poe gate) and the frontend checks (pnpm gate), the same
as CI. Allow about 8 minutes. docs/GETTING_STARTED.md takes a
new developer from a fresh clone to a green build and a first change, including the
local traps to know about. Also see CONTRIBUTING.md.
More detail
- Getting started for developers: setup, the full check, a map
of the code, and a first change.
- Architecture: the pieces, the scoring formula, how the browser
and Python engines are kept in step, the security model, and what the tests prove.
- Explore the interactive architecture map: the runtime
flow in an offline viewer.
- Python library and CLI: run the same search in Python, tune the
ranking weights, the command line, and configuration.
- Quickstart: the longer walkthrough, including
make demo with
Docker and building a catalog from your own CSV.
- Deploy: hosting as static files, and the server-backed variant.
- Security and privacy: the threat model and what data goes
where. Report vulnerabilities as described in SECURITY.md.
- Dagger CI setup: how the CI pipeline is built and
shared with other repositories.
- CHANGELOG: what changed in each release.
License
MIT. See LICENSE. Demo data: Synthetic demo catalog generated by backend/scripts/generate_catalog.py (MIT). Every brand and product in it is invented.
Details in NOTICE.
