Building HIPAA-Compliant Healthcare Software: Lessons from PSI Nest

The Challenge

PSI Nest started as a straightforward request: build a practice management system for mental health professionals. But healthcare software is never straightforward. HIPAA compliance adds requirements that touch every layer of the stack, from database encryption to audit logging to access controls. Getting it wrong is expensive: HHS enforces civil monetary penalties across four culpability tiers — from lack of knowledge up to willful neglect left uncorrected — with per-violation amounts and annual caps per violation category, both adjusted for inflation every year.

Architecture for Compliance

The stack is NestJS with TypeScript on the backend, React on the frontend, and Neon DB (PostgreSQL) for storage. Managed databases are perfectly usable for PHI (Protected Health Information) as long as the vendor signs a Business Associate Agreement and the required controls are configured — which is exactly what we did with Neon. We deployed the application layer on Coolify, a self-hosted platform that gives us full control over the rest of the infrastructure. Self-hosting is one valid architecture choice, not a HIPAA requirement; what HIPAA actually requires is a signed BAA with every service that touches PHI.

Encryption at Every Layer

The HIPAA Security Rule does not mandate a specific encryption algorithm. Encryption is an addressable implementation specification (45 CFR §164.312(a)(2)(iv) for data at rest and §164.312(e)(2)(ii) for transmission), which means you either implement it or document why an equivalent safeguard is reasonable — and in practice, encrypting is the only defensible answer. We chose AES-256 for data at rest, a widely accepted and defensible choice, and TLS 1.3 for all data in transit. We went further than the baseline: specific PHI fields like patient names, diagnoses, and treatment notes use application-level encryption with rotating keys. Even if someone gains database access, the raw data is unreadable without the application keys.

Access Controls and RBAC

We implemented role-based access control with four roles: practice owner, clinician, front desk, and billing. Each role has granular permissions. A front desk staff member can view appointment schedules but cannot access clinical notes. A billing staff member can see procedure codes but not treatment details. Every permission check happens server-side, never in the client.

Audit Logging

HIPAA requires a complete audit trail of who accessed what PHI and when. We built an immutable audit log that captures every read, write, and delete operation on PHI. The logs are stored in a separate database with write-only access from the application. They include the user, timestamp, action, resource, and the IP address. A common misconception: HIPAA's six-year retention rule (§164.316(b)(2)(i)) applies to required documentation — policies, procedures, and assessments — not to the audit logs themselves. How long you keep audit logs is a decision that comes out of your own risk analysis; like many organizations, we retain them for six years to align with the documentation window.

Clinical Workflow Design

Beyond compliance, the system needed to actually improve clinical workflows. We built an appointment scheduler with automated reminders, a patient portal for intake forms and secure messaging, a clinical notes system with templates for common assessment types, and an integrated billing module that generates CMS-1500 claims.

The key insight was involving clinicians in every design decision. Software that is technically compliant but hard to use will be worked around, and workarounds create security gaps.

Results

PSI Nest launched in 12 weeks and passed an independent HIPAA security assessment. The practice reduced administrative time by 40% and eliminated paper-based processes entirely. Patient satisfaction improved because intake and scheduling moved online.

Healthcare software requires a different mindset than typical web development. Security is not a feature; it is the foundation everything else builds on. Have a healthcare project? Let us talk.