Lists are the platform
You own a list — countries, products, clinics, anything people pick from. AutoSugges compiles it into an immutable artifact and serves that artifact from the edge, never from a live database query.
Every list has exactly one owner tenant. A platform list — like the built-in countries list — is owned by the AutoSugges platform tenant itself, using the same model a customer list uses; there is no separate code path for “global” data.
From list to lookup
Three steps, and the runtime never touches your list's live data — it reads what the compiler already verified.
1. Author a list
Add items with a display value, optional hierarchy, aliases, locale variants and metadata (emoji, flags, icons) through the dashboard or import.
2. Publish an immutable version
The compiler builds a version/hash-addressed artifact from your list. A version activates only after it verifies, and once published it never changes — a client never sees data mixed from two versions.
3. Serve it from the edge
A Cloudflare Worker answers every query from Workers KV. PostgreSQL is never on the autocomplete hot path, so a keystroke never waits on a database.
The compiler and adaptive prefix buckets
A published list doesn't become one big searchable blob — it becomes a tree of pre-ranked buckets, so a query is a lookup, not a search.
The compiler builds adaptive 2, 3, 4 and 5-character prefix buckets. Each bucket carries around ten pre-ranked suggestions plus metadata about its child buckets, so a keystroke resolves to a bucket read rather than a scan across the whole list. A query longer than the deepest compiled prefix is served from the longest matching bucket and filtered at the edge against your full query — no extra read, no extra round trip.
Publishing is reversible. Superseded versions stay retained rather than deleted immediately, so rolling back to a previous published version is a control-plane action, not a re-import.
The edge lookup order
Cache is never placed ahead of authorization. Every query runs through the same four checks, in the same order, before anything is served.
Step 1
Auth
Resolve the publishable key to its owner, list and policy.
Step 2
Entitlement
Confirm the origin and the list are allowed to talk.
Step 3
Quota / metering
Check and record usage in a Durable Object, before any cache read.
Step 4
Cache, then KV
Serve from the Worker cache, or read the verified artifact from KV.
Quota is enforced against the consumer’s own subscription, never the client’s say-so. When a quota is exhausted, the edge returns a structured quota_exceeded / upgrade_required response — never a synthetic result standing in for real data.
What an item can carry
One item structure, flexible enough for a flat list or a hierarchy, without a second data model for each domain.
Aliases and synonyms
“US”, “USA” and “United” all resolve to the same canonical item, compiled in ahead of time — matching an alias costs no extra lookup at query time.
Hierarchy with ancestor auto-fill
Selecting a city can return its state and country in the same selection, so a form fills three fields from one pick instead of three separate lookups.
Localization
A list can carry locale-specific display values, so the same canonical item reads correctly for every audience it serves.
Rich display metadata
Items carry emoji, flags and icons as data, not as a rendering hack — a country item can carry its own flag without your code computing one.
Small lists run entirely on the client
An eligible small list can be downloaded once and searched locally, with no per-keystroke request at all.
The client validates the list’s manifest hash at session start and refreshes in the background if it has gone stale — never serving a known-stale list silently. Larger lists stay on the edge-query path described above; the choice is transparent to your integration code either way.
One SDK, one embeddable component
The same @autosugges/client package powers a plain HTML page, a React app, Next.js and Expo — and the AutoSugges dashboard's own playground is not a special build, it's the same package.
Debounce and result-limit policy come from the list’s own configuration, delivered with the runtime key rather than hard-coded in the client. Every integration guide carries a Copy for AI / LLM control next to the ordinary code sample, so an agent and a person get the same instructions.