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](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:

```bash
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:

```text
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:

```bash
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:

```text
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](https://support.bolt.new/integrations/git).

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](https://support.bolt.new/cloud/hosting/publish).
Bolt's Netlify integration is optional and is not required for this dashboard;
see [Netlify integration](https://support.bolt.new/integrations/netlify) 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.