A Field Guide to
Modern Software Concepts

Imagine you are building a paper form for new library patrons. Before any patron arrives, you decide which boxes the form will have — name (text), age (a number), has_card (yes or no). That blueprint is the schema. The forms patrons fill out are the data. The blueprint exists once; the filled forms exist by the thousand.

In software, a schema describes the structure, the types of each field, and the rules (which fields are required, what range a number may fall in). It is enforced by databases, by APIs, and by validation libraries — each rejecting any record that does not fit.

JSON — JavaScript Object Notation — uses six building blocks: strings, numbers, true / false / null, arrays (in [ ]), and objects (in { }, holding key–value pairs). That is the entire grammar. Despite its tiny vocabulary, almost every web service in the world speaks it.

JSON has no comments, no dates, no decimals-with-units, no functions. Its great virtue is precisely this poverty: every language can read it the same way.

If a restaurant kitchen is a system, the menu is its API. You do not enter the kitchen. You read the menu (the contract), you place an order (a request) at the agreed counter (the endpoint), and a meal (the response) comes out. The chef may switch ingredients, hire new cooks, or rebuild the stove. As long as the menu is honored, you do not care.

Modern web APIs typically use HTTP with verbs (GET, POST, PUT, DELETE), a URL identifying the resource, optional headers (auth, content-type), and a JSON body. The reply is a status code (200 OK, 404 not found, 500 error) plus a body.

When you read the sentence "The cat sat on the mat," your brain unconsciously identifies the subject, the verb, and the prepositional phrase. A parser does the same for code or data: it takes raw text and recovers the structure hidden inside it.

Parsing usually happens in two passes. First the lexer (or tokenizer) chops the text into atomic tokens — numbers, identifiers, operators. Then the parser arranges those tokens according to grammar rules into an Abstract Syntax Tree (AST) — the structured form on which evaluators, compilers, and linters then operate.

A regular expression — regex — is a string in which most characters mean themselves but a few have superpowers: . matches any character, * means "zero or more of the previous", + means "one or more", \d matches digits, [a-z] matches a range, ^ and $ anchor to start and end, and parentheses capture groups for later use.

Regex is dense. A pattern that takes ten minutes to write may take an hour to read. But for jobs like extracting all phone numbers from a document, no other tool is so concise.

Out of the box, an LLM is a free-form storyteller. Ask it for a recipe and you may receive a friendly preamble ("Sure! Here's a great recipe…"), then the recipe in markdown, then a closing remark. Useful to a human; ruinous to a program that tries to JSON.parse() the reply.

JSON mode changes the decoding rule of the model. At every token step, the sampler is constrained so the cumulative output remains valid JSON. The model can no longer wander into prose. It must close every brace it opens.

If JSON is a written record, a JSON Schema is the official template the record must conform to. The schema declares the expected type of every field ("string", "integer", etc.), which fields are required, what format a string must obey (email, URI, date), what range a number must lie in, and even how items inside an array should look.

A validator reads the schema, reads the data, and reports every place where data and schema disagree. This same schema then drives form generators, code generators, OpenAPI documentation, and — most importantly — LLM structured-output enforcers.

An LLM by itself only knows what is in its weights. Ask it for today's weather and it will guess. ReAct (Yao et al., 2022) lets the model break out of its head: at each turn it may produce a Thought (private reasoning), an Action (a call to a tool — search, calculator, database, API), and then read an Observation from the tool. It loops until it can give a final Answer.

This single cycle — Thought → Action → Observation → Thought → … → Answer — is the engine behind most modern AI agents, including the one that wrote this page.

Most CSS frameworks (Bootstrap, Material UI) ship pre-made components — a "Card", a "Button" — each with its own opinions. Tailwind CSS does the opposite. It ships utility classes: p-4 means padding 1 rem, text-xl means large font, rounded-lg means large border radius, bg-blue-500 means medium-blue background. You build the component yourself by stringing utilities together, in the markup, exactly where the design lives.

The promise: no more renaming CSS classes, no more "button-primary-large-disabled-rounded" spaghetti. The cost: HTML can grow visually noisy. Most teams accept the trade-off.

The intuition is simple. A document deserves a high score for a query if (1) the query words appear in it, (2) the words are rare in the corpus (so they are informative — "the" is useless, "axial-flux" is golden), and (3) the document is not too long (a long document mentions everything; a short, focused one mentioning your terms is more likely to be on-topic).

BM25 — Best Match 25 — combines these three signals with two tuning knobs (k₁ for term saturation and b for length normalization). It is the default ranker in Elasticsearch, Lucene, and OpenSearch, and the keyword half of nearly every modern hybrid retrieval pipeline.

Before any text reaches a transformer, a tokenizer breaks it into pieces. Common words become a single token ("the"); rare or invented words split into several ("unhappiness" → "un" + "happi" + "ness"). Punctuation, spaces, and emojis each cost something. A useful rule of thumb in English: about 4 characters per token, or roughly 0.75 tokens per word.

The context window is the maximum number of tokens a model can attend to at once: prompt plus history plus generated reply. Older models held 4k; modern frontier models hold 200k–1M. Exceed it and the oldest tokens fall off the back of a moving train.

Imagine assigning every English word a coordinate in a high-dimensional map. Words that play similar roles in similar contexts (king, queen, monarch) get neighbouring coordinates; unrelated words (queen, asphalt) land far apart. That assignment is an embedding. Modern embeddings live in 768- or 1536-dimensional space, but the idea is the same: distance encodes meaning.

The clever bit is that the same trick works for sentences, paragraphs, even images. Once you have vectors, you can ask the question every search engine secretly wants to ask: find me the things most similar to this.

Cosine similarity ignores how long the vectors are and asks only: do they point in the same direction? Two vectors pointing the same way score 1; perpendicular ones score 0; opposite ones score −1. For text embeddings (which are usually L2-normalised), cosine and dot-product give the same ranking.

A naive search compares the query to every vector — fine for thousands, painful for millions. Production systems use approximate nearest-neighbour indexes (HNSW, IVF, ScaNN) that trade a sliver of recall for orders-of-magnitude speed.

You cannot embed a 200-page PDF as one vector — you would lose all locality. So you cut. Naive cuts at fixed character counts can split a sentence in half and bury the answer across two chunks. Better cuts respect structure: paragraph boundaries, sentence boundaries, headings. Better still, an overlap of a few sentences between adjacent chunks ensures context near the seam is never lost.

Three knobs matter: chunk size (typically 200–800 tokens), overlap (10–20%), and splitter strategy (recursive by paragraph → sentence → word).

An LLM trained last year does not know your codebase, your customers, or yesterday's meeting notes. RAG bridges the gap. At query time the system retrieves the most relevant chunks from a vector index (and often a keyword index), augments the prompt with them, and asks the model to answer using that context. The model's job changes from recall to read-and-respond.

Done well, RAG cuts hallucination, gives citations, and lets you update knowledge without retraining. Done poorly, it serves wrong chunks confidently.

Vector search is fast but coarse. It returns 100 plausible chunks in milliseconds. A reranker — typically a smaller cross-encoder model that reads query and candidate together — then assigns each one a precise relevance score. You discard the bottom 95 and keep the top 5.

Why two stages? A cross-encoder is too slow to run over a million documents, but a vector index is too crude to put the truly best result on top. The combination delivers both recall and precision.

Hybrid search runs both retrievers in parallel, then merges the lists. The simplest, most robust merger is Reciprocal Rank Fusion (RRF):

score(d) = Σ_r 1 / (k + rank_r(d))

For each retriever r, you take 1 over (a small constant k, typically 60, plus the rank of the document in that retriever's list). Sum across retrievers. Documents ranked highly by either method bubble up; documents ignored by both stay low. No score normalisation needed.

Function calling (also called tool use) is the structural foundation of every modern AI agent. You describe each tool with a name, a description, and a JSON schema for its parameters. The model, when it judges a tool call necessary, emits a JSON blob naming the tool and supplying its arguments. Your code receives the blob, runs the function, returns the result, and the model continues.

This is more disciplined than JSON mode: JSON mode controls format, function calling controls which function.

Chain-of-thought (CoT) prompting nudges a model to produce its intermediate reasoning out loud — list assumptions, do arithmetic, work the problem in stages — before stating the final answer. Wei et al. (2022) showed this single change can lift performance on math and reasoning benchmarks by tens of percentage points, especially in larger models.

CoT differs from ReAct: CoT is reasoning only (no tool calls), while ReAct interleaves reasoning with actions. Modern reasoning models (o1, o3, Claude with extended thinking) bake CoT into their decoding so you no longer have to ask.

Without a standard, every AI app re-implements its own tool wiring: a custom GitHub plugin, a custom Slack plugin, a custom database plugin. MCP (Model Context Protocol) defines a small client–server protocol where AI applications (the host) speak to MCP servers that each expose tools, resources, and prompts. Build the server once; every MCP-aware host can use it.

The protocol carries three primitives. Tools are functions the model can invoke. Resources are read-only data the host may inject into context. Prompts are reusable templates servers offer to clients.

The verb signals intent: GET reads, POST creates, PUT replaces, PATCH partially updates, DELETE removes. The server reads the verb and the URL, does its work, and returns a status code grouped by family: 2xx success, 3xx redirection, 4xx client error (your fault), 5xx server error (their fault).

Verbs and codes carry a contract beyond their literal action. GET is meant to be safe and cacheable; repeating it must not change state. PUT and DELETE are meant to be idempotent (chapter 27).

OAuth 2.0 is the protocol behind every "Sign in with Google" button. The user authenticates once with the identity provider; the application receives a short-lived access token instead of the user's password. Subsequent API calls present the token as a Bearer header.

That token is often a JWT (JSON Web Token) — three Base64-encoded parts separated by dots: a header (the algorithm), a payload (claims about the user), and a signature the server can verify without a database lookup. Anyone can read the payload; only the issuer, with the secret, could have signed it.

Polling is HTTP business as usual: every few seconds the client sends "any updates?" and the server answers yes or no. Simple, firewall-friendly, but wasteful when nothing changes — and laggy by definition (you only learn at the next poll).

WebSockets open a single TCP connection that stays alive. Either party may push a message at any time, with no per-message HTTP overhead. The cost: stateful connections, harder load-balancing, harder horizontal scaling.

A webhook is a normal HTTP endpoint you host. You register its URL with a third-party service (Stripe, GitHub, Slack), and from then on the service pushes events to you the moment they occur. Your endpoint receives a JSON payload, returns 200 OK, and gets back to its life.

Webhooks invert the usual control flow: you become the server-of-events. They are the lightest possible event bus across the public internet.

Cross-Origin Resource Sharing (CORS) protects you from a malicious page secretly making authenticated calls to your bank in your name. The browser enforces a "same-origin policy": JavaScript loaded from foo.com may freely call foo.com, but to call bar.com it needs bar.com's permission, expressed in response headers like Access-Control-Allow-Origin.

The notorious "CORS error" you see in the console is not a bug in the browser — it is the browser doing exactly the job it is paid for. The fix is on the server you are calling, not on yours.

A request travels through layers, and at every layer something might already have the answer. The browser's memory cache, the disk cache, a CDN edge node, an application cache (Redis), the database's own buffer pool. A hit at any layer skips the rest. A miss falls through to the next.

Caching is governed by two hard problems, both quoted endlessly: invalidation (when does cached data become stale?) and naming (what is the right key?). Get either wrong and users see yesterday's prices.

Networks drop packets. Clients retry. Without care, a single "charge $50" intent turns into two charges. The cure is the idempotency key: the client invents a unique ID per intent and sends it with every retry. The server records the result against the key, and a second arrival with the same key returns the same result without doing the work again.

GET, PUT, and DELETE are naturally idempotent (re-reading, re-replacing, re-deleting all converge). POST is not — and almost every payment system requires an Idempotency-Key header to make it so.

Every public API rate-limits: 100 requests per minute, 10,000 tokens per second. Exceed it and the server returns 429 Too Many Requests, often with a Retry-After header. A client that hammers harder will only be banned faster.

The standard polite response is exponential backoff with jitter: wait b · 2ⁿ seconds before retry n, plus a small random offset to avoid synchronized retries from a thousand clients colliding (the "thundering herd"). It's the universal manners of distributed systems.

The runtime maintains a call stack (currently executing functions), a callback queue (tasks waiting their turn — timer fires, network responses), and a microtask queue (Promise resolutions, almost-immediate). The event loop is the rule: when the stack is empty, drain all microtasks, then take one task from the queue, then repeat.

async/await is sugar over Promises. await suspends the function, frees the stack, and the runtime resumes the function once the awaited Promise settles — typically as a microtask.

The classic example: two threads each read a counter (it says 5), each add 1, each write back. Done concurrently, the counter ends at 6, not 7 — one increment is lost. The bug is invisible until the day it bites in production.

Cures come in three families. Locks serialize access (mutex, semaphore). Atomic operations bundle read-modify-write into one indivisible step (compare-and-swap). Avoid sharing: actors, message queues, immutable data — no two threads touch the same memory.

Debounce: wait until the user stops, then fire once. Perfect for search-as-you-type — no point querying after every keystroke when one's coming a millisecond later.

Throttle: fire at most once every N milliseconds, no matter how often events arrive. Perfect for window resize or scroll handlers — you want updates during the action, just not 200 of them per second.

YAML ("YAML Ain't Markup Language") uses indentation, hyphens for lists, and colons for key-value pairs. It supports comments, multiline strings, and references — at the cost of subtle whitespace bugs and famously inconsistent boolean parsing (yes, NO, on all once meant booleans). It dominates Kubernetes, GitHub Actions, Ansible, and ML configs.

TOML ("Tom's Obvious, Minimal Language") trades indentation for explicit [sections] and quoted strings. Less expressive, far less ambiguous. The Rust ecosystem (Cargo.toml) and Python's pyproject.toml made it ubiquitous.

John Gruber and Aaron Swartz invented Markdown in 2004 as a writing format that compiled to HTML. The genius: the source reads naturally, even unrendered. **bold** looks like emphasis even before it becomes bold. # Heading looks like the heading it represents.

Today, almost every README, every chat client, every AI prompt uses Markdown. Variants (CommonMark, GitHub-Flavored Markdown) standardised the messy edge cases.

You have a users table and an orders table. Each order has a user_id. To list every user with their orders, you JOIN on the matching id. The interesting question is: what do you do with users who have no orders, or orders whose user was deleted?

INNER JOIN keeps only matched rows. LEFT JOIN keeps every row from the left table, padding with NULL where the right is missing. RIGHT JOIN is its mirror. FULL OUTER JOIN keeps every row from both, padding both sides.

A hash is a one-way fingerprint. Given the input, you always get the same fixed-size output; given the output alone, you cannot recover the input. A single bit changed in the input produces a wholly different hash. Use cases: password storage (with salt), file integrity, content-addressed storage (Git, IPFS).

Encryption is reversible — given the right key. The output looks random, but the legitimate holder of the key can decrypt back to the original. Use cases: transmitting secrets (TLS), storing sensitive data at rest, signed messages.

The bug behind a thousand breaches: confusing them. Storing a password "encrypted" means someone with the key can read every password. Storing a password "hashed" (with bcrypt/argon2) means even the database admin cannot.

Base64 takes raw bytes and re-expresses them using only sixty-four printable characters: A–Z, a–z, 0–9, plus + and /. The trick is arithmetic: every three bytes (24 bits) splits cleanly into four six-bit groups, each of which indexes into the 64-character alphabet. The output is exactly 4/3 the length of the input, padded at the end with = when the byte count is not a multiple of three.

A URL-safe variant swaps + for - and / for _ so the result can travel inside URLs and filenames without further escaping. JWTs (chapter 22) use the URL-safe form; classic data URIs use the standard form. Both decode the same bytes back.

It bears repeating, because the misconception is endemic: Base64 is encoding, not encryption. There is no key. Anyone with a browser console can decode it.