Technical Overview
The Build
A self-hosted, offline-first EMR for a volunteer medical mission. This page covers the stack, architecture posture, security model, and the engineering decisions that shaped the system — including the ones that were wrong and got corrected.
Stack
| Layer | Technology | Note |
|---|---|---|
| OS | Kubuntu (Linux) | Native install, no VM layer; migrating to a dedicated mini PC for future missions |
| Runtime | Node.js (single process) | Serves the API and the built frontend from one process |
| Database | SQLite (single file) | No server to configure or keep running; backups are file copies |
| Frontend | React (static build) | Built once, served as static files by the same Node process |
| Process management | systemd | Auto-start on boot, restart-on-crash, no manual steps after power-on |
| Network | Clinic LAN only | Tablets reach the app by IP in a browser; no internet, no domain, no public exposure |
| Remote access | SSH via ed25519 keys | Accessible remotely via SSH config alias for admin and maintenance |
Architecture and Security
Network posture
LAN-only. No public IP, no public DNS, no internet dependency during clinic operations. The server is reachable only from devices on the clinic network. Designed for remote sites with intermittent or no connectivity.
Network-scoped trust
The application is reachable only on the clinic LAN, by IP, in a browser — no public exposure and no domain. The earlier OpenEMR build required installing a private CA root on every tablet before each mission; the custom system removed that step entirely, since an isolated clinic LAN does not carry the same threat model as a publicly reachable system.
Firewall posture
Default-deny inbound. Web traffic and remote management access are explicitly allowed; everything else is blocked. Verified after configuration and before each deployment.
Access control
Role-based, matched to actual staffing: one admin account for the tech lead, individual accounts for each station lead, and a shared PIN for volunteers. A tablet's station is its identity; a lead's account is their individual accountability. Auto-lock on inactivity (10-minute default) preserves an in-progress form exactly as left.
Backup and recovery
Hourly backups using SQLite's online backup API, safe to run during active writes. The system has been reboot-tested end to end — power off, power on, app started, tablets connected, data intact, backups resumed — with no keyboard required.
HIPAA-aligned hybrid model
For Laredo (US jurisdiction): paper-primary during the mission, post-mission EMR entry. Patient records are not held in the live system during clinic hours. This limits real-time data exposure and aligns with HIPAA principles without requiring a formal compliance posture.
Forms and Reporting
Five station forms, plus reporting and patient management, each coded directly against its paper original rather than built through a form editor. Paper forms are still the specification; deviations require clinical justification.
Registration
IntakePatient lookup by surname or MMDM patient number. Printed slip with the MMDM number. Typed DOB with auto-format and validation.
Triage
TriageFull vitals panel — BP, pulse, temperature, weight, height, BMI, SpO2, respiratory rate, glucose, LMP where applicable. Chief complaint in the patient's own words. Abnormal values auto-highlighted against a configurable threshold. Routes patients downstream.
Medical
MedicalSOAP note structure. Three-state ROS toggle (not assessed / negative / positive). 96-drug Spanish formulary with Costa Rica names preserved. Pediatric patients auto-flagged by age and routed here.
Vision
VisionService tracker. Snellen with and without correction, near and far. Autorefractor capture with minus-cylinder convention and axis validation. Pinhole acuity, anterior and posterior findings, IOP. Append-only dispensing log for readers, sunglasses, and drops.
Dental
DentalMedical history and pre-medication screening. Universal Numbering System tooth chart (adult 1–32, primary A–T) with per-tooth procedure logging. Dental prescriptions from the same formulary. Derived medication-flag panel surfaces relevant patient meds without re-collecting them.
Reporting
AdminPatients by station, today and mission total. Vision inventory consumed — readers by strength, sunglasses by type, drops by type. Computed live from the database, no cached numbers.
Patient Management
AdminDemographic corrections, add or remove services, guarded deletion with cascade through dependent records.
Key Decisions
Build in-house over contracted setup
ShippedChosen
Configure cloud and network infrastructure in-house with the MMDM president
Rejected
$6,000 contracted setup through a Microsoft networking subsidiary
The MMDM president is a former Microsoft employee with hands-on infrastructure experience. Paying $6,000 for a setup we could do ourselves — with someone more familiar with the org's specific needs — was not justified. The in-house build also gave full ownership of the configuration going forward, with no vendor dependency.
Ubuntu over Windows
ShippedChosen
Migrate to Ubuntu 22.04 LTS on a fresh VM
Rejected
Continue repairing the corrupted Windows/XAMPP installation
The MariaDB system database was untrustworthy after corruption. Repair would have left questions about silent data damage. Ubuntu gives a known-clean baseline, a real package manager, and SSH access without additional tooling.
Private CA over self-signed certs
ShippedChosen
Build a private certificate authority; install root cert once per device
Rejected
Per-endpoint self-signed certs (or no TLS at all)
Self-signed certs require an exception per device per endpoint. A private CA requires one trust install per device, after which all signed certs are trusted automatically. For a multi-station clinic that re-provisions tablets regularly, the operational difference is significant.
Rebuild over patch
ShippedChosen
Full OpenEMR reset in place during the Costa Rica mission
Rejected
Continue on the corrupted build, or fall back to an older insecure version
The running version was corrupted. The previous build lacking required security updates was not an acceptable alternative for a system holding patient data. A rebuild from a clean configuration, documented well enough to execute under pressure, was the correct call. The rebuild completed and the system returned to service within the hour.
Paper-primary field protocol
ShippedChosen
Paper is the primary workflow during missions; EMR entry happens post-session
Rejected
EMR-primary for the first deployment
Going EMR-primary on a first field deployment introduces data integrity and clinical workflow risks simultaneously. A shadow deployment catches problems at lower stakes. For Laredo, the paper-primary model also serves as the HIPAA-aligned privacy posture: patient data is not held in the live system during clinic hours.
Paper forms as the specification
ShippedChosen
Treat each paper form as the canonical spec; deviations require station-lead sign-off
Rejected
Design forms from scratch based on EMR best practices
Station leads have conducted 26 and 32 missions on paper. They know which fields get filled and which get skipped. Forms designed without that input would have required rework. The paper-as-spec rule produced forms the leads recognized as theirs.
Configurable routing thresholds
ShippedChosen
Routing thresholds (e.g., vision age cutoff) editable mid-mission without code changes
Rejected
Hardcoded thresholds in form logic
The vision lead changed the age cutoff for routing patients to the eye doctor midway through the Costa Rica deployment. A hardcoded value would have required a code change, a rebuild, and redeployment mid-clinic. The configurable model cost nothing to build and prevented a real operational blocker.
Custom build over OpenEMR and Power Apps
ShippedChosen
Scrap OpenEMR and the subsequently-proposed Power Apps direction; build a purpose-built Node.js + SQLite system instead
Rejected
Continuing to configure OpenEMR's Layout-Based Forms, or building the volunteer-facing form layer in Microsoft Power Apps
OpenEMR's architecture assumes a permanent clinic with reliable internet and trained admin staff — the opposite of a week-long mission with intermittent power and first-day volunteers. Power Apps looked like the answer once OpenEMR was ruled out, and was proposed to the board on that basis. Continued hands-on building surfaced a real limitation: genuine offline-first, real-time data collection was difficult to solve well in a no-code platform. A custom build, maintained directly, solves offline-first properly and gets closer to what each station lead actually wants. Microsoft 365 and SharePoint stay in the picture as the archive layer under the existing BAA — only the point-of-care interface changed.
Open Items
- highLaredo-specific form configuration (Medicaid Y/N, mailing address, Prevent Blindness referral) — target: pre-Nov 4, 2026
- highPhilippines deployment configuration (Batangas, Feb 2027) — new international scope, form and network requirements TBD
- mediumMigrate from the development Kubuntu box to a dedicated mini PC for field deployment
- mediumclinic.mmdm.org remote-review subdomain — DNS coordination through eCatholic, mmdm.org's current host
- mediumPharmacy station account for Laredo (dispensing + e-prescribing workflow) — target: pre-Nov 4, 2026
- mediumVision form value sets (Snellen model, reader strengths, sunglasses SKUs, dispensing model) — pending clinical-lead input
- mediumDental form review with Cathy Short and Linda
- lowFormulary admin data from Dr. Byrd
- lowAutorefractor USB/CSV integration (currently photo + manual transcription)