Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Static Content Hosting

Serve the files that are the same for every user from object storage behind a CDN, so the app servers handle only the requests that depend on who is asking or on current data.

Most of the bytes were the same for everyone

Filing season opens on the first of the month at a regional tax office, and about 22,000 taxpayers load its online filing app in the first ten minutes. The app is a single-page application: a 1.6 MB JavaScript bundle, a stylesheet, two web fonts and the illustrations that walk people through each form, about 2.3 MB on a first visit. The requests that do the real work, loading a taxpayer's prefilled return or saving a page of it, carry a few kilobytes each. All of it went to the same six application servers.

In those ten minutes the servers sent roughly 50 GB of files unchanged since the last deploy, about 85 MB a second. Connections stayed open streaming the same bundle to taxpayers on slow home connections, saves queued behind them, and within four minutes the one button that mattered was timing out. The database was mostly idle.

What the office shipped for the next season is Static Content Hosting: the files that are identical for every requester and change only when the team deploys move off the application servers into object storage, and a CDN serves them from there. The six servers keep only the requests whose answer depends on who is asking or on current data.

Built before anyone asks

A useful test for static: could the response be produced before any request arrives? The bundle, the stylesheet, the fonts, the illustrations and the filing guide PDF pass: the build, or an editor, makes them once, and every taxpayer receives the same bytes. The HTML page that loads this app passes too: it is the same short shell for every taxpayer, with no one's data in it. A taxpayer's prefilled return, the refund estimate and the save call do not, even though some are small JSON responses: they are computed from the database at the moment of the request, and they stay with the app servers.

Two paths from one browser

The CDN answers file requests from its cache and fetches misses from the bucket; only API calls reach the app servers. The deploy job writes to the bucket, never to the servers.

API calls reach the app servers on a hostname of their own, where the API has to allow the site's origin through CORS, or on a path such as /api/ that the CDN forwards to them uncached. The app servers lose their copy of the built files and the route that streamed them, their deploy no longer ships the front end, and their capacity is sized for filing requests alone. The bucket can stay private, read by the CDN under credentials of its own (Object storage & blobs).

A year for the bundle, a minute for the page

The first version gave everything in the bucket a one-day cache lifetime. On the second day of the season a fix to the deductions form went out, and for up to a day taxpayers whose browsers or nearby CDN edges already held app.js kept running the broken one. A purge empties the CDN's copies (CDN & static delivery), but nothing reaches into a browser's cache, and a shorter lifetime would only trade that delay for far more requests checking a file that rarely changes.

The build tool already had the answer. With content-hashed (or fingerprinted) file names, it names each output after a hash of its bytes: app.3f9c2a1b.js, deductions.71b20c4e.js. A changed file gets a new name, so a name never comes to stand for other bytes, and these files can go out with Cache-Control: max-age=31536000, immutable: a year. The one file that cannot be renamed is the entry document, index.html, because it is what the site's stable address, the one taxpayers type and bookmark, serves. It lists the current hashed names and gets either no-cache, which lets caches keep it but makes them check with the origin before each use, usually answered by a small 304, or a lifetime of a minute or so. A deploy reaches a taxpayer when their browser next fetches the HTML, and the hashed files it names come with it. What each directive means is HTTP caching: Cache-Control, ETags & revalidation.

Watch outCommon mistake: giving index.html the year-long lifetime of the hashed files. Each browser then keeps the old page, and the old bundle it loads, until that copy expires or the taxpayer forces a reload, and no new file name reaches them before that.

New files first, old files kept

Hashed names make the order of a deploy matter. Upload index.html first, and a taxpayer who loads the page a second later gets HTML pointing at app.8d41e07f.js before that file is in the bucket: a blank screen, and an error the CDN may keep for a while if its settings cache errors. Deleting causes the opposite failure. A taxpayer who opened the app before the deploy still runs the old page; when they open the deductions form, it loads deductions.71b20c4e.js on demand, and if the deploy has removed that file, the click fails. So the team's deploy runs in this order:

  1. The build produces the hashed files and the new index.html together, once.
  2. The deploy job uploads every new hashed file next to the old ones already in the bucket.
  3. The deploy job uploads index.html last, and purges it at the CDN if an edge lifetime would otherwise keep the old one.
  4. A cleanup job, days later, deletes the hashed files that no release of the last few weeks referenced.

Rolling back is the same move in reverse: upload the previous index.html, whose files are still in the bucket. Old files cannot be kept forever, so a tab left open longer than the retention can still ask for a file that is gone; the app should catch that failed load and reload the page, after saving the taxpayer's unsaved changes or warning that a reload would lose them. Building those files once and promoting the same output to every environment is CI/CD pipelines: integrate, build once, promote.

A bookmarked deductions page

The app does its own routing in the browser: /returns/2025/deductions is drawn by JavaScript, and no file by that name exists. Opened from a bookmark the next evening, that path goes to the CDN and on to the bucket, which has no such object: an error page instead of the return. A single-page app that routes on the client needs a fallback on its static host, set up as a rewrite rule or a custom error response: a path that matches no file gets index.html, and the app's router draws the page from the URL. A site whose pages exist as files, one per URL, needs none of this.

Keep the fallback narrow. Under /api/ it turns a mistyped API call into an HTML page with a 200; for a missing .js file it hands the old tab above HTML where it expected JavaScript, a confusing failure instead of a clear 404. And since every unknown path now gets a page, the app has to draw its own not-found screen.

Last year's return, for its owner only

One folder is not public: each taxpayer's filed returns and statements, as PDFs that only that taxpayer may download, and a CDN URL anyone can pass around cannot enforce that. The bytes still skip the app servers. The taxpayer asks the API for a document; the API checks that it belongs to the signed-in account, one database row, and answers with a link to that one object, signed by the service and valid for five minutes. The download then goes from storage, or from a CDN that verifies such signatures, straight to the taxpayer, and no unsigned route to the PDFs is left open. A link that leaks works until it expires, which is why the lifetime is short. What the signature can pin, and what it cannot stop, is Valet Key.

Putting the app in S3 behind CloudFront

The Serverless Web App on AWS Challenge puts this split first among its requirements, "Host the static single-page app globally with edge caching", next to a REST API served from functions behind an API gateway. Put the app's files in S3 behind CloudFront, send nothing but API calls to the gateway, and label the edges so the Grid shows which requests are files answered at the edge and which reach a function. If a page load still passes through the gateway, the app tier is serving bytes it does not need to.

Practice this