Documentation

Everything you need to drive the demo, read your numbers with confidence, and pull data out programmatically.

Getting started

Go to /demo/request and leave your email — you'll receive the access PIN.
You land in the real Barnboard application on a synthetic 12-cow herd.
Sign in with the personal guest login you received.

Access PIN: 8437
Your login: a personal guest username & password arrive together with your PIN when you request access.
Guest logins are disposable: after you sign out twice, the credentials expire — just request access again. Everything you enter is demo data — log milkings, add treatments, try to break it. (On the hosted demo the database resets periodically; on-premises it is yours and persists.)

A day in the life

Morning. Log each cow's AM litres on the Milk page — one tap, one number.
Glance at the dashboard. Two charts side by side: the last 14 days actual, and the next 7 days forecast (dashed bars, labeled with the model version). The forecast is recomputed from your own records — no cloud involved.
Glance at the tiles. Beside today's totals: a price outlook tile (next year's ₹/L, built from India's official price index and your own sales) sits next to this month's revenue.
Check the flags. If a cow has run well below her own forecast for 3 straight days, she's flagged. In the seeded herd that's cow #102 — her drop pattern is planted so you can see the alert working. Half-logged days (AM entered, PM missing) are ignored by the model, so a busy evening never fakes an alarm. A likely heat alert works the same two-signal way: cow #110's 21-day cycle plus her one-day dip flag her in time to breed.
Evening. Log PM litres; record a milk collection on the Sales page and the month's revenue updates — with a projected month-end figure behind it.
Any time. Pull any table as CSV from the app, or hit the JSON API (below) from your own tools.

How it works

The medallion pipeline

Raw records land in bronze (typed, cataloged, exactly as entered), get cleaned into silver, and are modeled into gold — analysis-ready facts like per-cow per-day litres. Every step records lineage: any number can be traced back to the rows that produced it. Authentication tables never enter the pipeline (personal data is excluded at the front door). Re-running the pipeline on the same inputs yields bit-identical outputs — reproducibility is tested, not assumed.

Governed metrics

A metric here is a versioned definition, not a formula someone typed into a cell. Each definition names its owner, its unit, its lineage, and its aggregation class — and the class is enforced. Additive things (litres) may be summed up a grain; ratios (price per litre, yield per cow-day) are recomputed, never summed. Every analyst answer ships a receipt: the definition, the version, the lineage, and the exact SQL.

The models

Model	Method	Evaluated
7-day yield forecast	Champion/challenger: every night five strategies (trend, smoothing, last-value, per-cow selected, and a lactation curve for cows with 90+ days of history) compete on a held-out week; the winner is served. The served model can never be worse than the naive baseline, because naive is itself a candidate.	Current holdout MAEs: champion 1.12 L · lactation curve 1.22 (beat the trend model's 1.28 on a multi-month backtest) · all recorded in models/eval.md
Drop detection	Mean deviation of the last 3 complete days vs the cow's own forecast; flag at −20%; half-logged days excluded	Catches the seeded decliner; zero false positives across the stable herd
Heat (estrus) detection	Rules, no ML: a cow whose insemination failed is watched on the 21-day cycle; flagged only when the cycle window AND a one-day milk dip (≤92% of her own mean) agree	Seeded heat event flagged exactly once; zero false positives by construction
Revenue projection	Month-to-date rate extrapolated to month-end	8.1% absolute error with the final week hidden
Price outlook	FAOSTAT India milk price index (1991–2025) drift-forecast for direction × the farm's own volume-weighted ₹/L for level	Walk-forward: drift 4.6% error vs naive 6.9% over the held-out years

Honest caveat: these figures come from three weeks of synthetic demo data. The methods are deliberately simple and auditable; expect the margins to improve — and the evaluation to get harder — with real multi-month history.

API reference

Authentication

API calls need either a signed-in browser session or the farm's feed token — the same secret that powers the calendar feed. An owner finds it in the app (the calendar subscription URL contains it). Pass it either way:

curl "https://<demo-host>/api/v1/cows.json?token=YOUR_TOKEN"
curl -H "Authorization: Bearer YOUR_TOKEN" "https://<demo-host>/api/v1/cows.json"

Unauthenticated calls get JSON 401 — never a login redirect.

Endpoints

Endpoint	Returns
`GET /api/v1/schema`	The versioned data contract: every exportable table with column names, types, and keys — program against this, not guesswork.
`GET /api/v1/{table}.json`	Full rows for `cows`, `milk_logs`, `treatments`, `breedings`, `sales` in an envelope: `{schema_version, table, row_count, rows}`. Anything else → 404 (whitelist).
`GET /api/v1/metrics`	Every governed metric: id, label, version, owner, unit, aggregation class, breakdown dimensions.
`GET /api/v1/metrics/{id}?by=dim`	The metric's value with its receipt — definition, owner, version, lineage, and the exact SQL. `?by=breed` style breakdowns for declared dimensions. Unknown id → 404, undeclared dimension → 422.
`GET /api/v1/predict/yield/{cow_id}?days=7`	The cow's forecast: date + litres per day, with the serving model version. Unknown cow → 404. `days` caps at 30.
`GET /export/{table}.csv`	The same whitelisted tables as headed CSV (browser session).

Sample forecast response:

{
  "schema_version": "1.0",
  "model": "yield_forecast", "model_version": "v1",
  "cow_id": 1, "tag": "101", "breed": "HF cross",
  "trained_through": "2026-09-03",
  "forecast": [
    {"date": "2026-09-04", "litres": 25.7},
    {"date": "2026-09-05", "litres": 25.5}, …
  ]
}

Your data & portability

One file. The entire farm database is a single SQLite file. Backing up is copying the file; the platform ships an online-backup tool that verifies the copy's integrity while the app keeps running.
Round-trip guaranteed. Export all tables to CSV, import them into a fresh database, and you get the same data back — this exact drill is part of the automated test suite.
Nothing leaves. Models train and serve on the same machine. The only outbound traffic the platform ever makes is fetching public reference datasets — once, checksummed, and only when you ask.

Running it yourself

Requirements: Python 3.12 and four pinned packages for the app; the data and model layer is standard-library only. Three verified ways to run the same codebase: bare metal under PM2 with a systemd boot unit (survives power cycles — drilled, not assumed), a Docker container (image builds and serves; login and dashboard verified inside it), and the serverless demo twin. Operations run themselves: nightly database backups with a rehearsed restore, nightly pipeline-and-retrain so forecasts follow the milk, and CI on every code change. See the feature matrix — everything marked Built has actually been run.

Barnboard Data Platform · beta · questions? Come back through the demo and poke the real thing.