Handbook / Reference
The sandbox, and connecting a real database
The demonstration company lives in its own database. Swapping in a real one is one environment variable.
The guided tour does all of this for you. On the dashboard, Guided tour walks the whole flow - a new enquiry through to a paid invoice - performing every real action with believable data, so you watch the records get made instead of reading about them. Sandbox only; run it as often as you like.
There are two datasets, and they never meet.
| Sandbox | Live | |
|---|---|---|
| What is in it | Two fictional companies, ready to explore | Whatever a real company has put there |
| Database | data/sandbox.db | data/biltbase.db |
| Uploads | uploads/sandbox/ | uploads/live/ |
| Run it | npm run sandbox | npm run live |
| Load the demo | npm run sandbox:seed | Refused |
| Safe to wipe | Yes - that is the point | No |
Everything you see in the sandbox is doing real work. There are no fixtures, no stubbed responses and no artificial delays anywhere in the application. Every figure on every page comes back over HTTP from SQLite through exactly the same code a real database goes through - so how long a page takes here is how long it will take there, for data of the same size.
Which one am I looking at?
The sandbox says so, permanently, in a bar across the top that
cannot be scrolled past - and on the sign-in screen before anybody
types a password. The demo account shortcuts only appear there too.
GET /api/health answers the same question for anything
automated, and the server prints it on startup.
Connecting a real database
- Point at itSet
BILTBASE_DATASET=live, orDB_PATHstraight at the file you want. An explicit path always wins. - Point the uploads with it
UPLOAD_DIR. The database references files by name, so the two belong together - back them up together as well. - Set the secret
BILTBASE_SECRETbefore storing any real mail credentials. It is the key they are encrypted with. - Sign upCreate the company account from the sign-in screen. The schema builds itself on first open; there is no separate migration step.
How the two are kept apart
Each database is stamped with what it is, inside the file,
the first time it is opened, and never restamped. That stamp - not the
filename, not the environment variable - is what the software believes.
So renaming a real company's database to sandbox.db does
not make it wipeable, and pointing BILTBASE_DATASET=sandbox
at it does not either. If the two disagree the server says so on
startup and goes with the stamp.
Loading demo data into a database stamped live is refused
outright, with the command you probably meant. --force
exists, prints a warning, and is there for the one case where you
genuinely want fictional data in a real file.
Undoing things
| What happened | The way back |
|---|---|
| Sandbox got into a mess | npm run sandbox:reset wipes it and loads the demonstration company again. That is what it is for. |
| Want a clean sandbox | Delete data/sandbox.db and seed again. |
| Seeded demo data into a real database | Only possible with --force, and it is not undone by re-running anything. Restore from backup. |
| Ran the wrong dataset | Nothing was written unless you changed something. Stop it, set the variable, start it again. |