Your First HIPAA App: 8 Things Developers Learn the Hard Way

Irina Bodean — Fri, 16 Oct 2026 06:11:55 +0000

Your first healthcare project usually starts with a familiar feature list: forms, a dashboard, messaging, search. You have built all of these before. Then someone says "HIPAA" on the kickoff call, and the familiar list stops feeling familiar.

HIPAA is the US law that protects health information. For developers, most of it lands in two places. The Privacy Rule limits who can see and share patient data. The Security Rule sets the safeguards your system needs around electronic patient data. There is no official HIPAA certification for software. Compliance is something you build and document, not a badge you earn.

It applies when your app handles health data for a healthcare provider, a health plan, or a vendor working for them. A standalone fitness tracker may fall outside it.

A lot of it stays invisible until it bites you. If you are about to build a HIPAA compliant app for the first time, here are eight lessons developers tend to learn the hard way. The examples come from ReferralMD, a referral platform for US doctors and specialists that the CorLab engineering team worked on.

One note: this is HIPAA for developers, not legal advice. Your compliance officer makes the final calls.

1. PHI is more than medical records

Protected health information (PHI) is health information that can be tied to a specific person. Once it is stored or sent electronically, it becomes ePHI. Most developers picture diagnoses and lab results. Those count, but so do many things that look harmless on their own.

An appointment time is PHI when it sits next to a patient's name. So is an email address in a referral form, an IP address in a patient portal log, or a photo of a face. HIPAA's de-identification rules list 18 identifiers, from names and dates to device serial numbers. If any of them is attached to health data, treat the record as PHI.

The practical lesson: map your data before you design the database. Mark every field that is PHI, or could become PHI when combined with another field. That map decides which tables need extra protection, which services may touch them, and what must never leave your system.

2. You need a BAA with every vendor that touches PHI

A business associate agreement (BAA) is a contract that obliges a vendor to protect PHI it creates, receives, stores or transmits for you. No BAA, no PHI.

Developers usually remember the database host. The surprises are elsewhere: the email service that sends appointment reminders, the SMS gateway, the logging service, the error tracker that captures request bodies, the analytics script on the patient portal, the AI API you call to summarize notes. The same goes for AI coding assistants and no-code builders if production data can pass through them.

This includes your own team. If your developers can reach production data, your company needs a BAA with the client too. If they work only with synthetic data and never touch production, you may not.

Also check the fine print. Many cloud providers sign a BAA, but it covers only a listed set of their services, not everything in the console. Before you add any third-party tool, ask one question: could PHI ever reach it, even by accident? If yes, the vendor signs a BAA or the data does not go there. Keep that vendor list in the repo, next to your architecture docs.

3. Logs, chat and error tools leak PHI

Your main database is usually the best-protected place in the system. The leaks happen around it.

The ReferralMD case page notes that about 60% of referrals go unseen, the gap the platform was built to close. Part of the answer is a real-time chat, so doctors and specialists can discuss a referral without phone tag. Clinicians write the way clinicians talk: names, conditions, medications, all in one message. The message store can be locked down, and PHI can still escape through request logs that capture message bodies, WebSocket debug output, or an error report that ships the full payload to a third-party tracker. You can see the chat and the rest of the workflow in the ReferralMD case study.

The fix is to redact by default, at the logger, so no one has to remember it at every call site:

Then apply the same rule to your error tracker and analytics. Scrub payloads before they leave your servers, and test it by searching your logs for a fake patient name.

4. Encryption without access control is not enough

Encryption at rest and in transit is the first thing every team adds, and it should be. It protects you from a stolen disk or an intercepted connection. It does nothing about a user who logs in legitimately and opens records they have no reason to see.

That is why the Security Rule also asks for unique user IDs, automatic logoff and strong authentication, which in practice means multi-factor login. On top of that, HIPAA's minimum necessary standard says people should get only the PHI they need for the task in front of them. In code, that means access scoped by relationship, not just by role. A specialist should see the patients referred to them, not every patient in the system.

There is a real design tension here. ReferralMD turns scattered patient data into a one-page visual summary, with live links to X-rays and MRI scans, and puts everything needed for a referral decision within two clicks. Speed matters to busy clinicians. But a fast screen also has to be a narrow one: decide what appears on it, for whom, before you optimize how quickly it loads.

5. Audit trail: who saw what, and when

Sooner or later someone will ask: who opened this patient's record last Tuesday? If your system cannot answer, you have a compliance problem.

The Security Rule requires audit controls that record activity in systems holding ePHI. Audit logging is not the same as application logging. Most teams log writes and forget reads. Log both. A useful audit event has the user, the patient record (by internal ID), the action, the time, the source and the outcome.

Three rules keep the trail useful. Log access events, not the PHI itself. Make the audit store append-only, so no one, including admins, can quietly edit history. And agree on retention with your compliance team early, because audit data grows fast and is painful to backfill.

6. Test data must be synthetic

The fastest way to get realistic test data is to copy production into staging. It is also the fastest way to put PHI into an environment with weaker controls, more people with access and no BAA coverage for half the tools.

You have two options. De-identify real data under HIPAA's rules, which is harder than deleting the name column. Or generate synthetic patients with a tool like Synthea, which produces realistic records, including in FHIR format. For most teams, synthetic is simpler and safer. Ban production copies outside production, and make that a written rule, not a habit.

7. FHIR, HL7 and fax take longer than the app

First-time teams estimate the app and forget the EHR integration work. The integrations usually take longer.

FHIR R4 is the modern standard: a REST API with JSON resources like Patient, Practitioner and ServiceRequest. Certified EHRs in the US must offer a FHIR API, which sounds like good news. In practice, every EHR vendor has its own registration process, sandbox, app review and quirks. HL7 v2 messages are still everywhere in hospitals, and they look nothing like FHIR.

Then there is the integration nobody puts in the estimate: fax. Many US practices still send referrals by fax. ReferralMD's dashboard accepts electronic referrals, including ones that started as a fax. A fax is PHI arriving as an image, so it needs secure intake, matching to the right patient and a human check when matching fails.

Integration is often the biggest line item in custom healthcare software development. Scope each connection as its own workstream, with its own timeline and its own test data.

8. Have a breach plan before launch

Under the Breach Notification Rule, the clock starts at discovery, and that is a bad moment to learn who to call.

The deadlines are concrete. Affected individuals must be notified without unreasonable delay, and no later than 60 days after discovery. Breaches affecting 500 or more people also go to HHS within that window, and to the media when 500 or more residents of one state or jurisdiction are affected. If you build software for a healthcare provider, your contract likely sets an even shorter deadline for telling them.

The developer's part of the plan is practical. Know who gets the first call. Have alerts that would actually notice unusual access. And make sure your audit trail from lesson 5 can answer the first question anyone asks: whose data was exposed? Run a one-hour tabletop exercise before launch. It costs little and shows every gap.

What these lessons have in common

Almost none of these lessons is about clever code. They are about decisions made early: which data counts as PHI, which vendors may touch it, who sees what, what gets logged, where test data comes from, and who answers the phone on a bad day.

That is the real difference between healthcare app development and the apps you have built before. The features look the same. The constraints sit underneath them, and they are much cheaper to design in than to retrofit. Most of HIPAA compliant app development comes down to these early decisions.

If you take one thing from this post, make it the data map from lesson 1. Almost every other lesson starts there.

What surprised you on your first healthcare project? Share it in the comments.

Thanks to the CorLab Tech engineering team for the technical input behind these lessons.

DEV Community: Irina Bodean