Client handoff plan

What the client is receiving

The Measles Vaccination (MMR) Coverage Dashboard is a public website that shows vaccination coverage at three levels:

  1. A national map of available state data.
  2. County-level coverage within a state.
  3. K–5 school and grade-level details where those data are available.

The live demonstration is currently at accidda.github.io/measles-dashboard.

Technical description in plain language

This is a static web application. It has no application server, database, login system, or server that the client must purchase and maintain.

The technical overview and data URL format are maintained in ARCHITECTURE.md and API.md.

Recommended client-controlled setup

The recommended final arrangement is an ACCIDDA-owned GitHub repository and GitHub Pages site:

https://github.com/ACCIDDA/measles-dashboard
https://accidda.github.io/measles-dashboard/

The client should control the ACCIDDA organization, its administrators, the repository settings, and the GitHub Pages site. State repositories may remain owned by their contributing organizations as long as they are public and continue to publish the expected files. The dashboard reads those repositories rather than copying their data into the dashboard repository.

Transfer and launch checklist

A client administrator should complete these steps with the development team:

  1. Create or transfer the dashboard repository to the client’s ACCIDDA organization. Preserve the repository history and the main branch.
  2. Enable GitHub Pages for the dashboard repository using GitHub Actions as the source. The repository already contains a deployment workflow that installs Node 20, builds the site, and uploads the result to Pages.
  3. Merge and deploy the reviewed production branch. The deployment workflow runs on pushes to main; it can also be started manually from the Actions page.
  4. Open the published URL and verify the national map, North Carolina state view, county drill-down, school details, and the API page.

How a developer can obtain and run the project

The client’s development team can work locally without a special server:

git clone https://github.com/ACCIDDA/measles-dashboard.git
cd measles-dashboard
nvm use                 # uses the Node version in .nvmrc (currently Node 20)
npm ci
npm run dev             # opens a local development site

Before merging a change, run the same checks used by the project:

npm run lint
npm test
npm run build

The build is the important launch check: it regenerates the data/API artifacts, creates the production bundle, and is the same general operation used by GitHub Actions. A pull request should be reviewed before it reaches main.

State data: how the pieces fit together

The repositories have separate responsibilities:

The common bundle uses this structure:

states.csv
states/<state-code>.csv
states/<state-code>/schools.csv

The state code, state FIPS, state name, county/school identities, and coverage columns must pass the shared schema. Missing measurements must remain blank; they must not be changed to zero. The preparation example and validation commands are documented in the measles-AA README and VALIDATION.md.

Registering a state repository

Once the dashboard’s state-registration workflow is part of the production branch, a state maintainer can:

  1. Open the dashboard repository’s Actions tab.
  2. Choose Register State Repository and select Run workflow.
  3. Enter the two-letter state code and the state repository’s HTTPS URL.
  4. Wait for the workflow to validate the public repository and open a pull request.
  5. Have a dashboard administrator review the repository URL, source commit, dataset path, row counts, and validation results.
  6. Merge the pull request only after the public data endpoint is confirmed.

This workflow reads public metadata and CSV blobs; it does not execute code from the state repository. The detailed procedure is in REGISTRATION.md.

Routine maintenance

Updating existing state data

  1. Obtain the approved source data and document its source and reporting period.
  2. Place the raw inputs in the state repository’s local input area.
  3. Run the measles-AA preparation and validation process.
  4. Review row counts, state/county names, and a sample of coverage values.
  5. Publish the prepared CSV bundle from the state repository.
  6. Run the dashboard checks and verify the public URLs in a browser.

The current registration design records a source commit so reviewers can tell which data version is being used. Updates currently require a maintainer’s PR approval to trigger automatic deployment.

Adding another state

Use the same state-repository format, validate the bundle, and submit it through the registration workflow. The dashboard’s state registry is intended to be the single source of truth; adding a state should not require rewriting the map or page components.

Troubleshooting examples

Cost and capacity expectations

If usage grows substantially, the client should monitor GitHub Pages bandwidth and Actions usage. The static build can be moved to another static host later, but that would be a hosting migration rather than a change to the application itself.

Evidence used for this plan