SummerProject2026/docs/bolt_deployment.md

Dashboard-only Bolt deployment

Last reviewed: 2026-07-21

Not part of the current delivery plan. The presentation now uses the same-network live-demo procedure in demo_script.md. This checklist is retained only as a boundary reference if public hosting is reconsidered later.

Non-negotiable publication boundary

Publish a separate Bolt project or GitHub repository containing only the contents of dashboard/. In that project, index.html must be at the project root.

Do not import the full Utah Vehicle Health source repository into Bolt. Do not depend on Bolt supporting a dashboard working-root setting. The source repository contains private-pipeline structure that a static host does not need, even when local secrets and data are Git-ignored.

The deployment project must never contain .env files, credentials, private data or marts, database files, model artifacts, SQL, pipeline scripts, repository history from outside dashboard/, raw JSON, operational records, or row-level predictions.

1. Verify the source dashboard locally

From the Utah Vehicle Health repository root:

npm --prefix dashboard test
node dashboard/server.mjs

Open http://127.0.0.1:4173 and verify:

• the development-preview banner says the values come from the private 10,000-vehicle sample and are not population estimates;
• the routes are Overview, Sample cohorts, Model & benchmark, and Data & methods;
• the final model is calibrated logistic regression and the boosted tree is benchmark-only;
• model cards show 2024 calibration-fit diagnostics, not the opened 2025 holdout comparison;
• no vehicle-level prediction service or input form exists;
• county displays communicate feed coverage rather than population rankings; and
• a missing or invalid aggregate bundle produces an unavailable state, not fallback estimates.

Stop the local server with Ctrl-C after verification.

2. Create a fresh dashboard-only artifact

Use a new directory and, preferably, a new deployment repository. Copy the contents of dashboard/, not the directory's parent and not the main repository's .git history.

The reviewed project tree is:

index.html
styles.css
package.json
server.mjs
README.md
js/
  app.js
  charts.js
  data.js
public/data/
  age_risk_curve.json
  cohort_scorecard.json
  coverage_quality.json
  data_manifest.json
  filter_catalog.json
  model_diagnostics.json
  overview_period_county.json
  sha256_manifest.json
tests/
  contract.test.mjs

Do not add any other repository directory. In the fresh artifact root, run:

npm test
HOST=0.0.0.0 npm start

No dependency install or build step is required. The PORT environment variable is honored automatically by server.mjs when a host supplies it.

Before creating the deployment repository, inspect its entire file tree. Apart from package.json project metadata, the only JSON allowed is the reviewed aggregate bundle under public/data/. Confirm that data_manifest.json still declares:

development_preview: true
population_estimate_allowed: false
locked_test_metrics_published: false

Do not hand-edit an aggregate file to make validation pass. Regenerate it through the private local exporter and repeat the review.

3. Import only the dashboard repository into Bolt

The recommended handoff is a fresh GitHub repository containing the reviewed tree above. It may be private if the connected Bolt account has access.

1. On the Bolt homepage, choose the GitHub import control.
2. Select the separate dashboard-only repository or use Import from URL.
3. Confirm index.html appears at the imported project root.
4. Inspect the Bolt file tree before previewing. If SQL, scripts, artifacts, private data, .env, or source-repository files appear, stop and delete that Bolt project; create a clean dashboard-only project instead.
5. Use HOST=0.0.0.0 npm start if Bolt requests a preview command. There is no build command.

Bolt's current GitHub import workflow is documented in GitHub for version control.

If a separate GitHub repository is not used, create a fresh Bolt/StackBlitz project and upload only the reviewed dashboard files so the same tree appears at the project root. Never upload the full source repository and then try to hide or ignore its private-pipeline directories.

4. Review in Bolt before publishing

Use the preview URL and repeat the local visual checks. Also verify directly:

• /public/data/data_manifest.json resolves;
• an unknown file path returns 404;
• /.env, /data/, /artifacts/, /models/, /sql/, and /scripts/ return 404;
• the browser makes requests only for the static HTML, CSS, JavaScript, and approved files under /public/data/; and
• no analytics, database, authentication, or third-party data service was added by an automated Bolt edit.

Preview privately first. If Bolt proposes code changes, review the full diff and rerun npm test; do not accept changes that add a database, environment secret, tracking script, model API, prediction form, or remote data source.

5. Publish with Bolt Hosting

Bolt Hosting is the intended host for this prototype:

1. Open the dashboard-only project.
2. Select Publish in the upper-right corner.
3. Choose private visibility for presentation review when available.
4. Select Publish and wait for the generated bolt.host URL.
5. Run the post-publication checks below before changing visibility to public.

Bolt documents this flow in Publish your project to a live website. Bolt's Netlify integration is optional and is not required for this dashboard; see Netlify integration only if hosting requirements explicitly change.

6. Post-publication checks

At the exact published URL:

1. Hard-refresh and confirm the development-preview banner remains visible.
2. Visit all four routes and verify labels, charts, and keyboard navigation.
3. Confirm the Model & benchmark view identifies logistic as final, tree as benchmark, and its values as 2024 calibration-fit checks.
4. Confirm no 2025 holdout metric appears in the site or public JSON.
5. Confirm there is no vehicle-level lookup, input form, or row-level output.
6. Confirm coverage language does not imply statewide representation or county ranking.
7. Request the denied paths from step 4 again and require 404.
8. Save the published URL, release ID, publication date, and reviewer decision; do not save private paths, row values, or credentials in the release note.

If any check fails, use Bolt's Publish menu to unpublish or keep the site private until a corrected dashboard-only artifact passes local and hosted review.

Updating a published prototype

Changes in a Bolt project are not automatically live. For each update:

1. regenerate/review aggregates locally;
2. run the dashboard contract test;
3. update the separate dashboard-only repository/project;
4. inspect Bolt's diff and preview;
5. use Publish > Update; and
6. repeat every post-publication check.

Never synchronize private pipeline directories into the deployment repository.