How econscout is built.
A literacy tool for the US economy, running on free public data and a cache that never waits on a government API.
Most economic coverage hands you one number and calls it the score. The jobs print. The GDP line. The headline that moves the market for an afternoon. econscout was built on the opposite idea: that no single number is the economy, and the skill worth teaching is reading across many of them, through deep history, across states, with the events that moved them in view.
It runs entirely on free public data and free-tier infrastructure. Government agencies publish the numbers. A scheduled job pulls them, tags each one with its source and the date it is current as of, and stores them. The site reads from that store, never from a live agency API, so a slow or offline government server never takes the site with it. The whole thing is built for iteration: live and quietly usable while it grows.
How it works, in plain English
Five steps from a government spreadsheet to the chart on your screen.
A scheduled job pulls the data.
A Cloudflare Worker wakes up on a timer, calls each government API, and pulls the latest figures. It is guarded to run once per scheduled time, so a hiccup never sets off a stampede of catch-up pulls.
Each number is tagged and stored.
The Worker normalizes what it pulls into one shape, stamps every figure with its source and as-of date, and writes it to a Postgres database. That database is the cache the whole site reads from.
The site reads the cache, never the source.
When you load a page, econscout reads from its own database, not from a government API. A slow or offline agency can delay tomorrow's update, but it cannot break the page in front of you today.
Maps join data to geography in your browser.
State and county shapes are pre-simplified map files served as static assets. Your browser pulls the shapes once and joins them to the numbers by FIPS code, so the database stays small and the maps stay fast.
Every number shows its source and date.
Nothing appears without provenance. Each figure carries the agency it came from and the date it is current as of, so you always know what you are looking at and how fresh it is.
Architecture, the technical view
Read top to bottom. The government APIs are the upstream source; everything below is econscout's own.
Map geometry is pre-simplified TopoJSON on R2 object storage. Your browser joins it to the numbers by FIPS code, which keeps the database tiny.
- Never a live API call at page load. The site reads its own cache, so a third party's uptime is decoupled from yours.
- Geometry is static, not in the database. Map shapes live as files and join in the browser, which keeps the database small enough to stay on the free tier to county level.
- Every observation carries its source and as-of date. No naked numbers reach the screen.
- The data model has no causal field. An era or a policy can be marked with dates and a factual label, but there is nowhere to store "this caused that." Neutrality is enforced by the structure, not just the copy.
- Color scales stay colorblind-safe. Where a brand color would mislead on a map or chart, the colorblind-safe palette wins. That is a hard rule.
The stack, and what each piece does
The technical name on top, the plain-English version underneath.
SvelteKit, deployed to Cloudflare's edge. Renders the pages and runs the light server logic.
What this is: the toolkit that turns the code into the interactive site you are using. Fast to load, and app-like where it needs to be, on the maps, overlays, and analysis.
Supabase Postgres. Stores every series, region, and event, plus the source and as-of metadata on each figure.
What this is: the cache the site reads from. Postgres is a long-proven open database; Supabase is a managed, free-tier home for it.
Cloudflare Workers + Cron. A scheduled function pulls each source on a timer and writes to the database, guarded to run once.
What this is: the part that does the data pulling on a schedule, so the numbers stay current without anyone pressing a button.
MapLibre GL + R2. Open-source map rendering, with pre-simplified geometry served as static files from object storage.
What this is: the maps engine and the place the state and county shapes live. Keeping shapes as files instead of database rows is what keeps the whole thing free.
Cloudflare Pages. Global static hosting plus serverless functions, on the same platform as the Workers and storage.
What this is: where the site lives. Push the code, Cloudflare deploys it worldwide, with no servers to babysit.
Where the data comes from
All free, all public, reliability first.
FRED Federal Reserve Bank of St. Louis. The anchor for macro time series, with decades of history.
BLS Bureau of Labor Statistics. Jobs and prices, in detail.
Census ACS American Community Survey. Regional income, rent, and home values.
BEA Bureau of Economic Analysis. State output and personal income.
Census TIGER The map geometry, simplified to TopoJSON.
A few problems worth solving
Never going stale in silence.
Cached data is fast, but a cache can quietly serve a number that stopped updating. Every figure carries the date it is current as of, and each series is checked against a refresh log, so a stalled feed shows as stale instead of passing for fresh.
Neutrality built into the schema.
The riskiest part of an economy site is politics. The defense is structural: the data model stores dates and factual labels for eras and events, and nothing else. There is no field for "this policy caused that outcome." The literacy layer then teaches the attribution problem out loud. Facts on the page, the judgment left to the reader.
Colorblind-safe over brand.
The brand has its colors, but a map or chart that misleads a colorblind reader is a broken chart. Where the two conflict, the data-viz palette wins. A hard rule, not a preference.
Zero cost at launch.
Every piece sits on a free tier. The one real space hog, map geometry, lives as static files rather than database rows, which keeps the database small enough to stay free well past the launch set of indicators.
econscout is on a soft launch. It is live and quietly usable, and built to improve with real use. The political-era overlays are next, with deeper maps and more indicators behind them. Start at the literacy layer or the dashboard.