Quiet Chart

Overview

Quiet Chart is a sample case study for an electronic medical records system aimed at small clinics: one or two doctors, a front desk, and a single server in a back room or a small VPS. It covers patient registration, visit notes, prescriptions and an audit trail of every change.

The guiding idea is in the name. Clinical software is used under time pressure, so the interface should be calm, fast and predictable, with nothing on screen that does not help with the patient in front of you.

The problem

Small clinics often sit between two poor options: paper records that are hard to search and easy to lose, or large hospital systems that are expensive, slow on modest hardware and built around workflows the clinic does not have. Staff end up keeping the real information in notebooks and spreadsheets next to the official system.

Goals

• Find any patient and open their chart in a couple of keystrokes.
• Record a visit note without leaving the keyboard.
• Keep a complete, tamper-evident history of who changed what, and when.
• Run comfortably on a single small server, with backups that leave the building.
• Make the access rules simple enough to explain to the whole clinic in one sentence each.

Technical approach

The application is a server-rendered web app, so every screen works on the clinic's existing computers without installing anything. PostgreSQL holds the records, because transactions and constraints are exactly what medical data needs.

Every write goes through a small service layer that does three things in one transaction: validates the input, updates the record, and appends an event to the audit log. Nothing writes to a patient table directly.

Role-based access keeps the rules explicit. Front desk staff manage registration and appointments, clinicians read and write clinical notes, and only an administrator can export data.

Architecture

Figure 1 shows the layout. Caddy terminates TLS and forwards requests to the application. The application talks to PostgreSQL, writes every change to the append-only audit log, and a nightly job produces an encrypted backup that is copied off the server.

Technology stack

• TypeScript and Next.js for the application and its server-rendered screens.
• PostgreSQL for records and the audit log.
• Docker Compose to run the proxy, application and database together.
• Caddy for automatic HTTPS.

Challenges and solutions

Search that respects how people type names

Names are spelled inconsistently. Search combines a prefix match on the name with exact matches on date of birth and record number, so "rah 1984" finds the right patient without a fuzzy search that sometimes returns the wrong one.

An audit trail that cannot be edited quietly

The audit table only accepts inserts. The application's database role has no permission to update or delete rows in it, so history cannot be rewritten from the application, even by a bug.

Working through a flaky connection

Visit notes are saved as drafts every few seconds, so a dropped connection costs a sentence rather than a consultation.

Results

Sample entry. Record what changed after launch here, with numbers only if you measured them. Useful measures for a system like this are the time to open a chart, how many records still live on paper, how often staff need help, and whether a restore from backup has been tested.

Lessons learned

• In clinical software, predictability beats cleverness. The same action should always be in the same place.
• Design the audit trail first. Adding one later means finding every place that writes data.
• Backups need a restore drill on the calendar, not just a schedule.