Your patient shows you a QR code. You scan it. That’s it.

This section is written for IT system administrators and engineers deploying the reader. Practice administrators don’t need to read this — pass it along to your IT team.

Quick start - local development install

Requires Node.js on the server. Four commands to run a dev instance:

# Clone, install, and serve

git clone https://github.com/CMSgov/kill-the-clipboard-qr-code-reader.git

cd kill-the-clipboard-qr-code-reader

npm install

npm run dev

# Reader builds and serves at: http://localhost:3000

Camera access requires HTTPS on non-localhost devices. To test on an iPad on the office network: npx localtunnel --port 3000

Production deployment - static reader

The reader is a static site. Build it, then serve packages/scanner/dist/core/ from any host your check-in devices can reach (internal web server, CDN, S3, Netlify, Vercel, GitHub Pages):

npm run build

# Upload packages/scanner/dist/core/ to your web host

Or run it as a container:

npm run build

docker build -t ktc-scanner packages/scanner

docker run -p 8080:80 ktc-scanner

HTTPS is required in production for camera access.

Optional - proxy and sidecar

Only if your deployment needs them (see the decision tree above). Both ship with standalone Dockerfiles:

# CORS proxy

docker build -t ktc-proxy packages/proxy

docker run -p 3080:3080 ktc-proxy

# Enterprise sidecar (needs config + persistent volume)

docker build -t ktc-sidecar packages/sidecar

docker run -p 3090:3090 -e DATABASE_PATH=/data/ktc.db -v ktc-data:/data ktc-sidecar

Documentation for your security review

Authoritative install, security, and configuration documentation lives in the repository, structured for the questions a security team will ask:

• Self-hosting guide - full self-hosted setup walkthrough
• Core deployment - scanner build, local dev, static deploy, CORS proxy, known-issuer host checks
• Sidecar deployment - environment variables, connector configuration
• Architecture executive summary - system architecture overview
• Security & compliance spec - PHI handling, XSS/SSRF protections, audit posture

What’s in the QR code

The QR code contains a SMART Health Link (SHL) — not raw PHI. The SHL is an encrypted URL pointer to a FHIR bundle or PDF stored on the patient app’s server, time-limited and revocable by the patient. Your reader fetches and decrypts the bundle when it resolves the pointer.

What data comes across

Structured patient data in FHIR R4 (US Core IG) covering USCDI v3: demographics, medications, allergies, conditions, immunizations, vital signs, lab results, care team, insurance card. Unstructured documents (PDFs, scans, notes) come as FHIR DocumentReference with binary attachments.

The visit record goes back to the patient

At the close of the encounter, your EHR returns a visit summary — diagnoses, procedures, instructions, follow-up — in FHIR through the same channel used at check-in. The patient’s app receives it automatically. No portal. No paper. No printing the after-visit summary and handing it to them.

Identity and authentication

The patient verified their identity with an IAL2/AAL2 credential (CLEAR, ID.me, or equivalent including mobile driver’s licenses) when they set up their app. That identity travels with the SHL bundle. You do not ask for portal credentials or additional verification — the QR is the proof.

HIPAA

The patient is exercising their HIPAA right of access (45 CFR 164.524). They’re sharing their own records with you. Your receipt of the data is consistent with your existing covered entity obligations.