De-Mystifying Healthcare Apps: A “SMART on FHIR” Starter Kit for Developers

By Hisham Alrashdan — Healthcare Integration Engineer

Building a healthcare app is not like building a standard web app. You cannot just “login with email” and query a database. You must handle strictly regulated patient data, integrate with massive Electronic Health Record (EHR) systems (like Epic or Cerner), and strictly follow security protocols.

This high barrier to entry discourages many developers. I built the SMART on FHIR Starter Kit to lower that barrier.

This open-source repository is a small, working example for learning and demos. It handles the SMART sign-in (OAuth2) and the first data reads. It is not production software.

The Problem: The “Auth” Wall

The biggest hurdle in healthcare app development is the Launch Sequence.

To securely connect an app to a hospital system, you must use the SMART App Launch Framework. This involves a complex dance of redirects, handshakes, and token exchanges:

1. The app launches from inside the EHR (or standalone).
2. It redirects the user to the hospital’s Authorization Server.
3. The user logs in (as a doctor or patient).
4. The app receives an authorization code.
5. The app exchanges that code for an Access Token.
6. Finally, the app can fetch data (e.g., GET /Patient/123).

Coding this from scratch for every project is error-prone and tedious. A single mistake in the OAuth2 scope handling can break the entire integration.

The Solution: A Pre-Configured SMART Starter Kit

My SMART FHIR Starter Kit acts as a “batteries-included” foundation. It uses the standard SMART library, fhirclient.js, in plain HTML and JavaScript. There is no build step.

Key Features

• Zero-Config Auth Flow: Handles the entire OAuth2 “Code Flow” out of the box.
• Patient Context Ready: Automatically detects the current patient ID from the EHR session and fetches their demographics.
• Sandbox Compatible: Pre-configured to work with the standard SMART Health IT Sandbox for easy testing.
• Simple stack: plain HTML and JavaScript with fhirclient.js 2.6.3.

Technical Implementation

The kit is designed to abstract away the protocol complexity.

1. The Launch (launch.html) When a doctor clicks your app icon in the EHR, this file triggers the FHIR.oauth2.authorize() sequence, requesting the scopes launch openid fhirUser patient/*.read. patient/*.read means: read the data of the patient in context. In a standalone launch the app asks for launch/patient instead, so the user can pick a patient.

2. The Handshake (index.html). After sign-in, index.html calls FHIR.oauth2.ready(). fhirclient swaps the code for an access token. Then the app reads the patient in context:

const client = await FHIR.oauth2.ready();
const patientId = client.patient.id;
const patient = await client.request(`Patient/${encodeURIComponent(patientId)}`);

3. The UI Layer The dashboard shows the patient (name, birth date, gender, ID), the 5 latest encounters, active medications and the 10 latest observations. All server text is shown with textContent, so text from a FHIR server cannot run script in the page.

Why This Matters

This starter kit is more than just code; it is an educational tool. It bridges the gap for standard web developers trying to enter the health-tech space. By stripping away the complexity of the initial connection, it empowers engineers to prototype solutions—like a Cardiac Risk Calculator or a Diabetes Tracker—in hours instead of weeks.

To try it, clone the repository, run npm run start:smart-app (it needs Python 3), and open http://localhost:8000/index.html. For a full SMART launch, open https://launch.smarthealthit.org/ and use http://localhost:8000/launch.html as the app launch URL.

The kit also has an HL7 v2 channel for Open Integration Engine (OIE). Each message must have a message ID (MSH-10) and a patient ID (PID-3). The channel maps ADT to a FHIR Patient and ORU lab results to FHIR Observations. A message with a missing field gets an error ACK (AE). It was tested on OIE 4.7.0.

Conclusion

This project demonstrates that building secure healthcare applications doesn’t have to be an insurmountable challenge. By abstracting the complexities of OAuth2 handshakes and SMART launch contexts into a reusable boilerplate, we can lower the barrier to entry for digital health innovation.

The kit shows that plain web pages can use the standard SMART sign-in to read EHR data. It was tested with public test servers only. A real app still needs its own security and compliance review.

You can view the full source code, try the sandbox launch, and read the setup guide and the known limits on my GitHub.