diff --git a/docs/bolt_deployment.md b/docs/bolt_deployment.md deleted file mode 100644 index 21a320c..0000000 --- a/docs/bolt_deployment.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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.