DClaw Forecast documentation

Everything you need to use DClaw Forecast: how to sign in, what each screen does, how to read the numbers, and how the product is built.

One idea runs through everything: build a baseline (the forecast before you change anything), change one thing, and compare it with your experiment (the forecast after the change). The gap between the two is what your change did.

1. Getting started

Try the demo, no account needed. The landing page at forecast.smritiraj.online has a working lab under "Try it yourself". Move the interest rate, drag the window, press Run experiment.
Create an account. Go to Register and sign up with your email (you'll get a 6-digit code) or with Google.
Land in the Workspace. You start on the Dashboard with three sample series. Open one to see its forecast.
Open the Forecast Lab from Learn Lab in the top bar when you want to experiment.

The sign-in service currently runs as a development instance: you may see a small "development" badge, and the number of accounts is capped. It works normally otherwise.

2. The Workspace

The Workspace (/app) is for everyday forecasting on a single series. The top bar has the sections, the dataset picker, Saved, Export, Copy summary and Account (your data, and sign out).

Dashboard

One card per series with its latest forecast, the change against the last actual value, and the method that won.

Data

See the history behind a series, or bring your own. Drop a .csv file (up to 5 MB) or paste a date and a value on each line. Monthly, weekly and daily data all work: dates such as 2024-03, 2024-03-15, 15/03/2024, 03/15/2024 or Mar 2024 are read, and weekly or daily values are combined into calendar months, as a total (sales, visits) or an average (prices, temperature). Partial months at either end are left out, and the page tells you which; daily data with no weekends is judged on working days. Before anything loads, a preview says how the file was read: day or month first (decided once for the whole file), which column the values come from (pick another if there are several), and any repeated dates. Semicolon-separated files may use a comma as the decimal point, and Excel's Unicode exports are read too. A plain list of 8 to 600 numbers, one per line, also works; it is read as months ending last month. Imported series are saved to your account under "Your datasets".

Forecasts

Data: the three samples, your uploads, or Real data: New Delhi temperature (Open-Meteo) and the S&P 500 monthly average (FRED).
Model: Linear, ETS, Theta, Seasonal naive, ARIMA, Ensemble or Auto (Auto picks whichever had the lowest error on the most recent 3 to 6 months, re-fitted without them). With less than two years of history, ETS and Ensemble are fitted as Linear, and the forecast says so.
How far ahead: 6, 12 or 18 months.
Uncertainty range: 80%, 90% or 95% of plausible outcomes.
The brief beside the chart gives the endpoint, the change, the range and how the method scored on past data.

Scenarios

What-if assumptions on top of the forecast: a hotter or cooler trend, stronger or weaker seasonality, and a one-off shock in a month you choose. They change the future you're asking about, not how well the model fits the past.

AI Copilot

Ask questions about the forecast you're looking at ("why does it dip in March?", "how uncertain is December?"). The Copilot is given the computed numbers and told never to invent any. Each account gets up to 30 AI answers a day; after that, or if no AI model is available, a rule-based explainer replies from the same numbers.

Saved, Export and Copy summary

Saved stores the current forecast settings to your account so you can reload them later. Export downloads the forecast as CSV, and Copy summary copies a plain-text summary.

Your data and account

Account ▾ → Your data & account lists everything stored for you: saved series, saved forecasts, Lab experiments, Beat-the-model rounds and the daily AI answer counts. Download my data saves all of it as one JSON file. Delete my account (type delete to confirm) removes all of it and your sign-in account straight away; it can't be undone.

3. The Forecast Lab

The Lab (/app/lab) is where you change one thing at a time and see exactly what moved. Settings sit on the left. Beginner mode shows the essentials and Advanced adds the model's internal settings. Help mode explains terms where they appear.

Hover the ? next to any setting. The tooltip always follows the same order: What is it?, Why does it matter?, If you increase it, If you decrease it, May affect, then Learn more and the technical name.

View	What it's for
Experiment	Press Set as baseline, change a setting, and read What changed? and Observed impact. Switch the chart between Experiment, Overlay and Difference. The Scenario timing panel under the chart applies a change to part of the horizon only.
Guided	Five exercises. Predict first, set the values (or press Set it for me), record a run at each step, and read Your result, calculated from your own runs.
Sensitivity	Slide one setting across its whole range and see how the forecast, error and range respond, one real run per value.
Heatmap	Two settings at once, colouring each cell by the result you choose.
Relationships	A map of which settings depend on each other. Each pair is run at both ends of both ranges; a line means the effects don't simply add up.
Scenarios	Describe a future in the dataset's own language and compare up to three scenarios. Open scenario timing takes you to the timed version.
Backtest	The model is re-fitted on earlier data and asked to predict months it didn't see, several times over. Shows each window's error and whether the range caught the actual values.
Time machine	Drag to any past month (or press Play). The model is re-fitted on only the data known then, its forecast is drawn against what happened, with hits inside the range and 1/3/6-month errors, plus a track record across every starting point.
Beat the model	Pick a series (a sample or a city's observed temperature). Drag across the hidden six months (or use the arrow keys on each point) to draw your guess, set how sure you are (±%), then Reveal. Your rounds build a track record: wins, average misses and how often your ranges held against the 80% they claim.
Models	All six methods (Linear, ETS, Theta, Seasonal naive, ARIMA, Ensemble) on one chart with their scores, and a note when the long-run test and the single recent test disagree.
Importance	Ranks settings by how much they actually moved the chosen result, and says why the rest didn't.
Domains	Weather, GDP and Stocks, each with its own data and controls (next section).
History	Experiments you've saved, compared side by side with the differing settings highlighted. Synced to your account.

Scenario timing

Set Timed change (for example +10%), Starts in forecast month, Lasts, a Path shape (step, gradual, temporary or a custom path you drag) and After the window (return to baseline, or keep the effect). The chart hatches the window, and the table shows the average change before, during and after it, measured against the same forecast without the change.

4. Domains

All three run on real data by default, and each keeps a clearly labelled, generated sample you can switch to with the Data or Place picker.

Ask the Copilot in the Lab

The Ask the Copilot button in the Lab header opens the same assistant as in the Workspace, but it also knows your experiment: the baseline, the timed change, the history window and the validation scores. Ask “What changed against my baseline, and why?”.

Say it in words and possible futures

On the Experiment tab, type a what-if such as “a 10% promotion in months 4–6, then back to normal” and press Read it. The settings it will change appear as chips; nothing changes until you press Apply. Common phrasings are read by built-in rules; others go to Claude and count toward the daily AI allowance. Show possible futures draws 200 of 1,000 simulated paths behind the forecast and shows the chance of ending at or above a target.

Weather

Six monthly measures: average daily high, rainfall, cloud cover, peak wind (average of each day's strongest wind, km/h), humidity (%) and sunshine (hours a day). Each is forecast as a range: P10 (a low case), P50 (the middle) and P90 (a high case), clipped to what is physically possible. The Chart picker shows any of the six; the month cards list all of them. Each month gets a sky icon and a season read from the forecast by stated rules, and the page shows how often the charted measure's range held on past data.

Choose a place: New Delhi, Mumbai, Bengaluru, Kolkata or Chennai use real observations from January 2021 to the last complete month (Open-Meteo archive, ERA5 reanalysis, CC BY 4.0), refreshed daily. The generated sample location is still available.

GDP

Quarterly GDP growth modelled from four inputs: interest rate, inflation, a business-activity survey and the change in unemployment. By default this is official US data from FRED, Q1 2012 onward: real GDP (as an index), the Fed funds rate, CPI inflation over the past year and the unemployment rate. The PMI isn't free to publish, so the Philadelphia Fed manufacturing survey stands in for it; the generated sample uses a PMI. A month that was never published (October 2025, after the US government shutdown) is skipped when averaging a quarter. Set each input's future path (size, start quarter, length, shape, after). The page shows GDP against the no-change path, an exact per-input breakdown of why it changed, what the model learned, and a test on held-out quarters. These are associations in the data, not proven causes.

Stocks

Daily closes of the S&P 500, Nasdaq Composite or Dow Jones (about the last three years, from FRED; market holidays skipped), or the generated sample stock. Technical features: yesterday's return, returns 2–5 days ago, a moving-average gap, RSI (a 0–100 momentum indicator), recent volatility and the size of yesterday's move. Choose a target:

Price: a P10/P50/P90 fan for 5, 20 or 60 trading days.
Daily return: tomorrow's move, which is close to a coin flip.
Volatility: how big the next week's moves will be, which is genuinely predictable.

Every model is scored on the last 120 days it never saw. Nothing here is investment advice.

5. Reading the numbers

In plain English	Technical name	What it tells you
Average error	`MAE`	How far off the method was, on average, on past data it didn't see.
Large-error sensitivity	`RMSE`	Like average error, but big misses count for more.
Average % error	`MAPE`, `SMAPE`	The error as a percentage of the actual value. Months whose actual is 0 have no percentage and are left out of MAPE; SMAPE still counts them.
Range coverage	coverage	How often the actual value landed inside the shaded range.
Direction right	direction accuracy	How often the forecast got the up-or-down move right.
Uncertainty range	prediction interval; P10–P90	Where the actual value will probably land. It widens further ahead.
Percentage points	pp	A change in a rate: 4% to 5% is +1 pp (not +1%).

Expected vs observed. Ochre panels show what a change is expected to do: guidance, before you run it. Teal "Observed" panels show what it did, always calculated from the run.

6. A day in the life

A demand planner has to commit to next quarter's stock order.

In the Workspace, she opens Electronics Demand and leaves the model on Auto. The brief says the forecast rises and shows how the method scored on held-out months.
They set the uncertainty range to 90%. The line doesn't move, but the range widens. That's the point of the setting.
In the Lab they press Set as baseline, then use Scenario timing to model a +15% promotion for three months from month 4, returning to baseline afterwards.
Observed impact shows the lift during the window and none after it. The Difference chart shows exactly which months move.
In Backtest they check that the range caught most held-out months, then save the experiment and export the forecast as CSV.

7. Technical architecture

Front end: Next.js 15 (App Router) and React 19 on Node.js 24, deployed on Vercel.
Forecasting engine: TypeScript, running in the browser. It includes Linear (trend plus seasonal profile), ETS (additive Holt-Winters), Theta (exponential smoothing plus half the long-run drift, on the seasonally adjusted series), Seasonal naive (last year repeated, the benchmark), seasonal ARIMA (order chosen automatically: seasonal differencing, a variance rule for the ordinary difference, then p and q by AICc; fitted by conditional least squares), an error-weighted Ensemble of Linear and ETS, and Auto. The GDP and Stocks domains use ordinary least squares. All backtests, sweeps, heatmaps and scenarios run on the same engine.
Accounts: Clerk (email code and Google). Middleware gates /app and the data routes.
Storage: Neon Postgres through Drizzle ORM. It has five tables: datasets (name, unit, monthly history, start month), forecasts (dataset, model, horizon, confidence level, scenario settings), lab_experiments (saved Lab experiments, newest 30 per user), challenge_rounds (Beat-the-model rounds, newest 500) and copilot_usage (AI answers per user per day, for the daily limit). Every row is scoped to the signed-in user. Migrations are managed with drizzle-kit.
Tests: 76 unit tests (Vitest) for the forecasting maths and the importer, and 28 browser suites that compare every screen with the engine, run before and after each release.
Copilot: a server route that calls Claude Haiku through the Vercel AI Gateway, then OpenRouter, then Anthropic directly, then a rule-based answerer, in that order. It stops the model when you close the panel, and an answer that never came from the AI doesn't count toward the daily limit. The browser never sees an API key.
Help text: one parameter registry (lib/params/registry.ts) drives every tooltip, the Learn More drawer, Help mode and search.

8. API reference

JSON over HTTPS. Data routes require a signed-in session (Clerk cookie) and return 401 {"error":"Unauthorized"} otherwise. Everything is scoped to the signed-in user. Errors are always JSON with an error message: 400 for invalid input, 404 for an id that isn't yours or doesn't exist, 409 when an account limit is reached, 413 when a body is too large, 415 when it isn't sent as application/json, 429 for too many requests, and 503 when the database doesn't answer (try again). Request bodies are size-checked before they are read. Responses with your data carry Cache-Control: private, no-store.

GET/api/datasets

Your saved datasets, newest first.

POST/api/datasets

Save a series. Body (up to 64 KB): name, history (8 to 600 numbers; null or text is refused, not stored as 0), optional unit, subject, startMonthIndex (0–11), startYear and period (1–52). 400 if the name or values are missing or a number is out of range.

{ "name": "Store A sales", "unit": "units", "history": [120, 131, 128, 140, 152, 149, 161, 170] }

DELETE/api/datasets/:id

Delete one of your datasets.

GET/api/forecasts

Your saved forecasts.

POST/api/forecasts

Save forecast settings. Body: name, datasetRef, model (linear, ets, theta, snaive, arima, ensemble or auto), horizon (whole number, 1–36), ciLevel (0.8, 0.9 or 0.95) and drivers (trend and shock between −1 and 1, seasonal 0–3, shockMonth within the horizon). datasetRef must be a sample, a real-data series or one of your saved series. 400 {"error":"Invalid forecast payload."} otherwise.

GET/api/forecasts/:id

One saved forecast, or 404.

DELETE/api/forecasts/:id

Delete one saved forecast.

GET/api/account/export

Everything stored for your account as one JSON file: account, datasets, forecasts, labExperiments, challengeRounds, copilotUsage.

DELETE/api/account

Deletes all of your data, then your sign-in account. Body must be {"confirm":"delete"}, otherwise 400.

GET/api/health

Public, no sign-in. 200 {"ok":true,"db":"ok","dbMs":…,"ai":"configured","version":…,"time":…} when every table answers within 3 seconds, 503 with "db":"error" or "timeout" when not. HEAD works too. For uptime monitors.

GET/api/weather?city=delhi

Observed monthly weather for delhi, mumbai, bengaluru, kolkata or chennai: average daily high, total rainfall, average cloud cover, peak wind, humidity and sunshine from January 2021. Source: Open-Meteo (CC BY 4.0). 502 if the source doesn't respond.

GET/api/gdp

US quarterly real GDP (index), Fed funds rate, CPI inflation, unemployment and the Philadelphia Fed survey, from FRED.

GET/api/stocks?index=sp500

About 750 daily closes of sp500, nasdaq or dow, from FRED.

GET / POST / DELETE/api/challenge

Beat-the-model stats and recent rounds; submit a round (datasetId, cut, guess of 6 numbers, width); the server computes every score. A replay of hidden months you've already played is answered with "repeat":true and doesn't count toward your record; more than 20 rounds a minute gets 429. DELETE clears your rounds.

POST/api/webhooks/clerk

For Clerk only: a signed user.deleted event deletes that account's stored data. Unsigned requests get 400; 503 until the signing secret is configured.

POST/api/scenario-parse

Reads a what-if sentence with AI when the built-in rules can't. Returns settings clamped to the Lab's ranges.

POST/api/copilot

Used by the in-app Copilot; not a public API. Body: a question (up to 500 characters) plus the computed forecast context (up to 32 KB); larger requests get 413, and a context missing the forecast's fields gets 400. The answer streams back as text, and an x-copilot-source header says which engine answered.

9. Troubleshooting

Sign-up says an account limit was reached

The sign-in service is on a development plan with an account cap. Contact us and we'll free up space.

My CSV was rejected

The message under the box says what was read and what is missing. Monthly data needs a value for every month; weekly or daily data needs at least 8 full months with no long gaps; every line of a plain list needs a number (the message names the line). If the dates look shifted, check the preview's "Dates read as" note.

My Lab history is missing on another computer

Lab history is synced to your account. Sign in with the same account and reload the Lab; anything saved while offline uploads on the next load.

The Workspace says it couldn't load your saved series

The database didn't answer in time. Nothing is lost: press Retry, or reload the page a moment later.

The Copilot's answers look short or templated

It's using the rule-based answerer, which happens when the AI model is unavailable. The numbers are still correct.

A setting says "No effect"

That's deliberate. For example, what-if assumptions can't change validation error, and ETS smoothing does nothing under the Linear model. The tooltip explains why.

10. Honest limits

Real data covers five Indian cities (weather), the United States (GDP) and three US indices (stocks). The models are small and linear, so on real data they can lose to simple guesses; the page says when they do.
Forecasts are monthly: weekly and daily uploads are combined into months, not forecast day by day.
Prophet, Random Forest and XGBoost are planned, not built.
Accounts run on a development plan until launch.