Use this when you need to walk a reader through a whole pipeline — request in, response out — with a sticky table of contents, plain prose, one real code snippet, and an annotated diagram of the flow.
This is a copyable exemplar. Lift the <section> demo block below into a lesson built from assets/lesson-template.html — keep the design tokens and the .tech-toggle pattern verbatim.
You type a few words into a search box and, a fraction of a second later, a ranked list of results appears. In between, your words travel through five hand-offs: your browser sends them off, an API cleans them up, an index finds every page that could match, a ranking step decides which matches are best, and a response carries the winners back to your screen.
Think of it like… asking a librarian for "books about volcanoes." You speak (browser). She repeats it back to be sure she heard right (API). She walks to the card catalog and pulls every card tagged volcanoes (index). She sorts that stack so the most useful books are on top (ranking). Then she hands you the top few and tells you how many more exist (response).
The browser issues an HTTPS GET /search?q=… that terminates at a load balancer fronting a stateless API tier. The API normalizes the query (lowercasing, Unicode folding, stop-word handling, tokenization), then queries an inverted index — a map from each term to a posting list of document IDs. Candidate documents are scored, typically by BM25 for lexical relevance plus signals like freshness and popularity, then a learned ranker re-orders the top candidates. The API serializes the top k hits to JSON and returns them; the whole round trip usually completes in tens of milliseconds.
When you press Enter, the browser packages your words into a web request and sends it over the network. Nothing has been "searched" yet — this step is just delivering your question to a computer that knows how to answer it.
The receiving service tidies up your text: trims spaces, lowercases it, splits it into individual words, and checks it is safe and well-formed. A messy " Volcanoes! " becomes the clean term the rest of the system expects.
The index is a pre-built lookup table: for every word, it already knows which documents contain it. Instead of scanning millions of pages, the system jumps straight to the list for "volcanoes" and pulls back every matching document — often thousands of them.
Thousands of matches are useless without order. The ranking step scores each candidate — how well it matches, how fresh it is, how often people click it — and sorts so the most useful results rise to the top. Only the top handful survive.
The top results are packed into a compact data format (JSON) and sent back along the same connection. Your browser receives them and draws the familiar list of blue links — and the whole journey is over before you have finished blinking.
Here is the handler that ties the five stages together — read it top to bottom and you will recognize every step from the diagram.
# GET /search?q=... — one request, five stages def search(request): raw = request.query.get("q", "") query = normalize(raw) # 2 · parse + validate if not query.terms: return json({"hits": [], "total": 0}) candidates = index.lookup(query.terms) # 3 · find candidates ranked = rank(candidates, query) # 4 · score + sort top = ranked[: 10] # keep top k return json({ # 5 · response "hits": [hit.to_dict() for hit in top], "total": len(candidates), })
Open the handler and jump to the entry point with: grep -n "def search" services/search/handler.py
normalize, index.lookup, and rank each live in their own module under services/search/ — trace any stage deeper with grep -rn "def normalize\|def rank" services/search/.