Architecture
Clear is a library, not a feed. Every page is a plain file, written once and served as it is. There is no database standing between you and a page, nothing to spin up, nothing to wait for. This page explains the whole model, from the ten thousand pages we have now to the hundred million we are building toward. The shape never changes. Only the number of shelves grows.
The whole system, in one picture
The five layers
A recipe, a course, a guide: each one is a single finished HTML file with its words, its picture, and its tags baked in. A page never waits on another page to render, and it never asks a database a question. Serving a file is the fastest, cheapest, most reliable trick on the web, and it does not get slower when we add more files. Rule for every page: under a megabyte, open in under a second, no ads, no trackers.
Content lives in collections: recipes, courses, guides, news. Each collection has one source of truth. For recipes, that is one structured record per dish: title, ingredients, steps, tags. A page is that record, rendered. Render it in a new language and the same dish becomes a new page without anyone rewriting it. That is how 616 dishes become 2,464 pages across four languages, and how the next language adds 616 more in one pass. Writing grows the seed. Rendering grows the farm.
Every page carries tags: what it is, where it is from, who it helps. A recipe is tagged Italian, main course, baking, vegetarian. Tags do three jobs. They organize: each tag gets its own page listing everything on that shelf, generated from the same records, counted, never hand maintained. They connect: every page links to its tag pages and every tag page links back, so a visitor can always walk sideways to something similar. And they rank: TagRank scores a tag by the quality of what sits on its shelf, so strong shelves lift every page on them. Adding a tag costs nothing and opens a new doorway. At a hundred million pages, tags are how anyone, person or program, finds the right shelf without searching the whole library.
Tags live in the HTML, three ways
Every tag on a page is written into the page file itself, in three places, so that people, programs, and search engines all read the same truth and nobody has to guess.
First, as links a person can tap. The tags show at the foot of the page as ordinary links to their shelf pages, and the shelf pages link back. If a human can see it, it is real.
Second, as meta tags in the head. The page head carries its title, a plain description, its canonical address, and one alternate link per language, so a program can tell at a glance what the page is, where it lives, and which language versions are its siblings.
Third, as JSON-LD, the machine-readable card. Every page carries a small block of structured data, written in JSON, that states the facts about the page in a format software reads directly: what kind of thing it is, its name, its tags (as keywords), and the details that matter for its kind. A recipe declares its ingredients, times, and steps. A course declares its lessons. Nothing about the page is left to inference.
One record in the collection is the source; the HTML, the meta tags, and the JSON-LD are all rendered from it in the same pass. They cannot disagree, because they were never written separately. When a tag changes, the record changes, the page is rendered again, and all three copies move together.
Search needs a list of everything, so we keep one: the index. It is a plain data file with one small entry per page: its address, title, tags, language, and rank. Search reads the index, never the pages themselves, which is why search stays quick no matter how big the library gets. Our climbers rebuild the index from the collections, and Doodle runs admissions at the open gate, checking new pages before they are listed. When the index outgrows one file, it splits by collection and language into a shelf of index files, and a tiny router sends each question to the right shelf. Same model, more shelves.
Kindness Rank, the score that orders results, is worked out in batches, away from visitors: recommendations flow through links, kindness flows through vouching, and each page ends with one number. That number is written into the index. Answering a search is then just reading numbers that already exist, never live math. Recomputing for a bigger library means splitting the batch by collection and running the pieces side by side, then merging the numbers. Slow work happens in the workshop. The reading room stays instant.
What changes at scale, and what does not
One index file. One batch for ranking. Every collection on one shelf each. The whole library can be read by one person in an afternoon.
Pages are stored in bundles by collection and language. The index splits into one file per bundle. Ranking runs per bundle, in parallel. Nothing about a page, a tag, or a shelf changes.
More bundles, more index files, more parallel ranking runs, and copies of popular shelves kept close to readers around the world. The reading experience is identical, because reading a finished file is the same at any size. Libraries solved this centuries ago: you do not redesign the book when the library grows. You add shelves, keep the catalog honest, and let people walk the aisles.
For engineers: the system, precisely
This section is the same model with the numbers attached. If you were handed this system tomorrow, this is what you would be operating.
Data model
Content is stored as structured records, one per item, in plain files under version control. A recipe record holds: a slug (its one-word address), a language code, a title, a short deck, timing fields, an ingredient list, an ordered step list, a tip, and a tag set. A course record holds lessons instead of ingredients. There is no content database. The records are the database, and git is its history, backup, and audit log in one.
Render pipeline
Pages are produced by generator programs, never edited by hand. The pipeline is: edit a record, run the generator for that collection, review the rendered files, commit, push. The host builds from the repository and serves the result at the edge. A deploy is therefore a git push; a rollback is a git revert. Every build is verified by content, not by status code: the checker fetches the live page and confirms its title and language match the record, because a missing page and a real page can both answer 200.
Addresses and languages
Each item lives at one canonical address. English sits at the root (clearrecipe.net/margherita-pizza/). Each additional language renders the same records under a full-word prefix (clearrecipe.net/portuguese/margherita-pizza/), never an abbreviation a reader has to decode, and every version links to every sibling with hreflang alternates and a matching lang attribute. The short prefixes redirect permanently, so old links never die. New pages get one-word slugs; if a person cannot read an address aloud, the address is wrong.
Index format and sharding
The search index is a JSON file of small entries, one per page: address, title, language, tag list, rank, and a last-verified date. Budget 200 bytes per entry. At 10,000 pages the index is about 2 MB and loads whole. At 10,000,000 pages it is about 2 GB, so it is sharded: a shard holds at most 100,000 entries (about 20 MB), keyed by collection and language, giving roughly 100 shards at ten million pages and 1,000 at a hundred million. A router, itself a small static file, maps each collection and language pair to its shard. Search loads one shard, filters it in memory, and answers. No query ever touches more than one shard.
The ranking job
Kindness Rank is a batch job, run offline. Inputs: the link graph (every page, every link between pages) and the vouching graph (which authors the community stands behind). The job iterates the rank equation with a damping factor of 0.85 until the numbers settle, applies the kindness coefficient per page, and writes one float per page back into the index shards. At ten million pages the graph is on the order of ten million nodes and a few hundred million edges, which fits in memory on one large machine; beyond that, the job partitions by collection, runs the partitions in parallel, and merges. Ranking cost grows in the workshop, in batch windows. It never touches the serving path.
Serving and caching
Pages are static files served from edge caches close to the reader, over HTTPS with certificates the platform renews itself. Content pages cache hard: a new deploy is a new version, so a cached copy is never wrong, just briefly older, and deploys are verified at the edge after each push. Count files (the farm statistics, this network's public numbers) are served with no-cache headers on purpose: numbers must never be stale, a lesson this system learned on its first day. Images are WebP, sized near their display size, and every image carries tags and alt text.
Invariants
Five things are always true, and any change that breaks one is rejected. One: a page renders from exactly one record. Two: every page is reachable from a tag shelf. Three: every number shown to the public comes from the single counted source file, rendered live, never typed into a page by hand. Four: the serving path contains no database and no per-visitor computation. Five: the whole library can be rebuilt from the records and the generators alone, on a clean machine, with no other state.
The rules that keep it simple
One page, one file, no page depending on another page to exist.
One source of truth per collection. Pages are renderings, never originals.
Every page is tagged, and every tag is a shelf with its own page.
The index is data, the ranking is precomputed, and search is just reading.
New URLs are one clear word. If a person cannot read a link aloud, the link is wrong.
Growth comes from multiplication: new languages, new shelves, new collections. Never from bolting on machinery.
What is not true yet
This page describes the model Clear is built on. A model is only worth trusting if the distance between it and reality is written down, so here it is, dated and kept current. Last updated Day 2, October 13, 2026.
Ranking is designed, not running
Kindness Rank and TagRank are described above as batch jobs. Today they are designs on this page, not systems in production. No ranking job has run over a real link graph, the vouching graph has no data yet, and search ordering is a small set of editorial choices. Closing the gap: build the link graph from the built pages, run the first ranking pass, and store real numbers in the index.
Search is a hand index, not the sharded router
The index today is one small hand checked file covering the front door of the network, not the per collection shards and router described above. It answers honestly at this size. It will not answer honestly at fifty thousand dishes. Closing the gap: generate the index from the records automatically, then shard it by collection and language when one file stops being small.
The deploy road is the weakest layer
The pipeline section above says a deploy is a git push. For Clear Recipe tonight that is not how it works: the library is published as a direct upload of about eleven thousand files, and on a bad network that takes hours and babysitting. The reading room is strong; the road into it is a dirt track. Closing the gap: an automated publishing pipeline with atomic deploys and verification built in, owned by a platform engineer when we hire one.
This page broke the counting rule
The schematic above carries numbers typed in by hand: a page count and a goal from the day it was drawn. They went stale immediately, which is exactly the failure the counting rule exists to prevent. The rest of this site renders its numbers from the one counted source. This diagram does not, yet. Closing the gap: redraw the schematic so its numbers render from the same source as the Farm.
Records will outgrow plain files
One record per dish in plain files is the right size for hundreds of dishes and the wrong size for tens of thousands. The generators also carry knowledge that should live in the records themselves. Closing the gap: a real records store that the generators read, adopted when the master list passes a few thousand dishes, without changing anything a reader sees.
Verification is newborn
The Inspector, the checker that counts what actually serves, was built on October 12 and 13, 2026. It has passed smoke runs and caught real failures, but its full census discipline is being proven, not proven. Closing the gap: a full census after every five thousand pages, reported whether it passes or fails.