Patient Survey Engine Technical Guide

System Boundaries

Public routes include patient intake, location QR resolution, and Twilio webhook handling.
Authenticated routes cover import, dispatch, responses, provider delivery, organizations, rosters, questionnaire management, metrics, alerts, and admin monitoring.
The roster domain is distinct from the broader patient import domain and is keyed by location and service date.
Front-desk users are constrained to roster-specific behavior and location scope, while org_admin and ops_admin have narrower operational surfaces than full admins.

API.md is the route-level reference.
Validation report summarizes the currently exercised user stories, user types, and pass results.
Postman Collection validates the implemented API end to end.
Postman Local Environment provides local variables.
sample-roster.csv supports QR and front-desk testing.

Local Validation Workflow

Run npm run validate to start the app, execute API and data-model checks, build the frontend, validate docs content, and verify the deploy artifact.
Run npm run validate:content when editing docs and web content only.
Run npm run validate:live after deployment against a deployed base URL.

Run npm run docker:local:up to build and serve the app in Docker locally.
Review /docs/, /index.html, /frontdesk.html, and QR landing routes in the containerized environment.
Use npm run docker:local:logs and npm run docker:local:down for local operations.

Pre-Deploy and Live Validation

Monitoring and Delivery Notes

Metrics are protected and require auth or a configured scrape token.

Dispatch and delivery history should be reviewed before blaming Twilio or downstream endpoints.

Provider delivery prefers locationId-based routing for stable downstream matching.

Browser portal requests can use cookie auth, and mutating requests must satisfy CSRF protection.

Provider delivery can be exercised locally using the mock receiver path already covered by the validation suite.

Production validation should keep write paths limited to a dedicated test organization and location.

Validation Coverage

Docs and navigation are validated with the content validator before deploy.

The local validation lane builds the frontend, exercises API workflows, and checks deploy artifacts.

Live smoke validation confirms health, docs, and key runtime behavior against a deployed base URL.