Demo data

A module installed on an empty database shows nothing. You can ask the reader to type fifteen records before seeing a screen, or you can ship something to look at.

The folder

modules/pipeline_rivals/
  demo/
    rivals_competitor.json
    assets/
      logo.svg

One file per model, named after it. Nothing to call: the kernel reads that folder.

[
  {
    "ref": "pipeline_rivals.demo_meridian",
    "name": "Meridian Suite",
    "tier": "direct",
    "notes": "Strong on reporting, sells to the CFO."
  }
]

Loading

kewos demo load --database-url "$KEWOS_DATABASE_URL" -m pipeline_rivals

demo: 1 record(s) created

The same command, a second time:

demo: 0 record(s) created

The ref is what makes replaying harmless: it is registered in the external-id registry, and an already-bound record is skipped. No ref means a record re-created on every call.

In production it refuses

kewos demo load --database-url "$KEWOS_DATABASE_URL"

DemoDataError: demo data loading refuses to run outside development
(KEWOS_ENV is 'production'); demo data is never seeded into a real environment.

The guard is in the loader, not in a guideline. A sample set poured into a customer’s database stops being distinguishable from their real data within days: it is irreversible without a backup, and nobody notices straight away.

The four conventions that avoid surprises

A relation is given by ref. A Link whose value is a string is resolved against the registry:

{ "ref": "pipeline.demo_lead_acme", "stage_id": "pipeline.demo_stage_proposition" }

An unknown ref raises, naming the field and the value, rather than writing an empty link.

The order is dependency order, then filename order within a module. A referenced record must load before the one pointing at it: core before sales, and pipeline_stage.json before pipeline_lead.json.

An image is a path, not a payload. A file field whose value is a string names a file in demo/assets/. It is uploaded to storage and attached after the row exists. With no storage configured the record still loads, without its picture.

An amount is given by its _amount leg alone. The kernel completes the monetary triplet at the company’s currency. Writing all three columns by hand risks freezing one that should have been derived.

Why it is worth writing

Demo data goes through the gated session, like real data: ACL, audit, sequences, derived defaults and stored-field computation all apply. So it is not decoration: it exercises your module end to end, and a set that will not load reveals a model that will not fill.

It is also what a customer demonstration shows. A lead called “Test 3” for €1 says something about the product, and it is not flattering.