Skip to main content

Demo data and seeding

This page describes the demo data seeding system and the safety controls that prevent it from running in production.

Who this is for

Operators setting up non-production demo or evaluation environments. This feature is not available in production.

Production guard

Demo seeding refuses to run when NODE_ENV=production or ENVIRONMENT=production (or prod). These controls are enforced in the backend before any seeding logic executes. Do not set ALLOW_DEMO_SEEDING=true in a production environment.

What seeding does​

Seeding populates the database with a realistic set of demo data for a customer scenario, including:

  • Users with different roles (admin, quality admin, team lead, employees).
  • Training materials with versions, quiz questions, and completion evidence.
  • Controlled documents across lifecycle states.
  • Campaign assignments and completion history.
  • Guided /demo journeys that show how to test the most important workflows after a customer code is validated.

A re-seed wipes the existing data before inserting fresh records. An in-progress seed rejects concurrent requests with 409 Conflict to prevent corruption.

Double-gate requirements​

The POST /v1/seed-database endpoint requires all three of the following before it will run:

GateWhat to setDescription
Environment gateENVIRONMENT is not production/prod and NODE_ENV is not productionChecked first; no bypass possible.
Feature flagALLOW_DEMO_SEEDING=trueMust be the literal string true.
Access codeBOOTSTRAP_CODE=<your-code>The caller must supply this code in the request body. Compared with constant-time equality to prevent timing attacks.

If any gate fails, the endpoint returns an error without performing any database operation.

Per-customer demo access codes​

Demo environments for individual customers use distinct access codes. These codes are non-production credentials. They grant access to the seeded customer demo experience, not to production data.

Each per-customer access code is configured in the BOOTSTRAP_CODE environment variable of that customer's demo deployment. A customer's access code only works against their own demo environment.

warning

Per-customer demo access codes are non-production credentials. They should never be reused in a production deployment and should be rotated if shared externally.

Guided customer demo​

After a valid customer code is entered on /demo, Better Comply shows a guided test map instead of dropping the visitor directly into a role picker. Each card explains the benefit, the requirement area it proves, the role used for the walkthrough, and the steps to try.

For the Schnee-Gruppe demo, the guided paths cover:

Guided pathWhat it proves
Controlled documentsWork instructions become versioned controlled sources with content, original layout, version history, and training traceability.
Editable AI assessmentsAI-generated questions stay editable before release and can include question types, answers, and explanations.
Assignment matrixEmployee attributes such as department, activity, plant, and workstation drive automatic assignments.
Scheduling and recertificationDue offsets, grace periods, recurrence, version history, and new-version retraining are visible in the training flow.
LanguagesThe demo can be inspected across supported interface languages while training language remains controlled by the authoring flow.
Emailless operatorsShop-floor workers can log in with a personnel number and PIN while evidence remains attributable.
Supervisor reportsTeam leads can review due, overdue, passed, and incorrect-answer status within their scoped team data.

The same screen also keeps a free role picker for unguided exploration.

Setting up a demo environment​

  1. Deploy the backend to a non-production environment (e.g. Cloud Run dev project, Docker on a test server).
  2. Set the environment variables: 
    ENVIRONMENT=development
    NODE_ENV=development
    ALLOW_DEMO_SEEDING=true
    BOOTSTRAP_CODE=demo-2026-customer-abc
  3. Confirm the deployment is not pointed at a production Supabase project.
  4. From the application's Dev Tools page, enter the access code and click "Load demo data".

Checking seed status​

The POST /v1/check-database-status endpoint (no authentication required) returns a seededAt timestamp when the database has been seeded. The Dev Tools page uses this to show the current seed state and to reconcile after a page refresh (so a user who refreshes mid-seed sees the correct status rather than triggering a duplicate seed).

Concurrent seed guard​

If a seed is already in progress (e.g. triggered from another browser tab), a second request to /v1/seed-database returns 409 Conflict. The Dev Tools page surfaces this as "a load is already running" and polls check-database-status until the existing seed completes.