Clinic records app architecture: the decisions that matter

Situation: Role-only access lets every nurse read every chart, which is the most common cause of reportable snooping incidents.

Choice: Row-level security by org, column visibility by role, and a care-team relationship check for clinicians, with break-glass as the audited exception.

• Rejected: Role-only access: simple but over-broad.
• Rejected: Per-record ACLs maintained by hand: precise but unmaintainable at scale.
• Consequence: Every chart query joins the care team, so the index on (user_id, patient_id) is critical.
• Consequence: Break-glass and its review queue become a compliance workflow the product must run.

Situation: Auditors ask who viewed a chart, not only who changed it; an asynchronous log can lose events.

Choice: Every PHI read writes a hash-chained access-log row in the same transaction; if the log write fails the read fails.

• Rejected: Async log shipping: cheaper but can drop events.
• Rejected: Log writes only: misses the snooping case.
• Consequence: Reads cost one extra insert, so the log table is partitioned and write-optimised.
• Consequence: Availability depends on the log write path, which is accepted for PHI.

Situation: A clinical note is a legal record; silent edits destroy its evidentiary value.

Choice: Notes are drafts until signed; after signing only amendments create version rows with the reason and the original preserved.

• Rejected: Editable notes with an edit history column: can be bypassed by direct updates.
• Rejected: Delete and recreate: loses provenance.
• Consequence: The UI needs an explicit amend flow.
• Consequence: Storage grows with versions, covered by partitioning.

Situation: Disk encryption does not protect against a compromised application role or a leaked dump.

Choice: Encrypt direct identifiers and note bodies with per-organisation keys; search with HMAC blind indexes rather than plaintext indexes.

• Rejected: Disk or volume encryption only: protects lost drives, not queries.
• Rejected: Application-wide single key: one leak exposes all tenants.
• Consequence: Fuzzy name search is limited to exact and prefix keys.
• Consequence: Key rotation needs a re-encryption job.

Indexes are chosen from the questions the app asks most often. Each line below names a table and the question its main index answers.

• patients: unique (org_id, mrn) — medical record number unique per organization.
• care_team_members: (user_id, patient_id) — does this clinician have a treating relationship.
• encounters: (patient_id, started_at DESC) — chart timeline.
• clinical_notes: (patient_id, created_at DESC) — notes in a chart.
• clinical_note_versions: unique (note_id, version) — one row per version, race-safe amendment.
• consents: (patient_id, kind, revoked_at) — active consent lookup in the access check.
• disclosures: (patient_id, disclosed_at DESC) — accounting of disclosures for a patient.
• phi_access_log: (patient_id, created_at DESC) — who accessed this chart.

Forge64 matches your description to one of 25 reference architectures, writes the plan and data model into the project, generates the app, and runs a quality gate over the code before you see it. Each app gets its own Postgres database and sign-in with no per-user fee. Hosting on Forge Cloud and Forge Payments are rolling out.

This is a reference design for the category, not a promise that every item is generated today. Built-ins such as background jobs, file uploads and search are rolling out; email sent from your app is coming soon, so anything here that needs it is something you add yourself for now.

What is the most important architecture decision for a clinic records app?

Authorisation by tenant, role and treating relationship. Row-level security by org, column visibility by role, and a care-team relationship check for clinicians, with break-glass as the audited exception.

Do I have to make these decisions myself?

No. Forge AI plans them from your description and writes the decisions into the project as architecture records you can read and change.

What do the alternatives cost me?

For example, for "Read-logging in the same transaction as the read": Async log shipping: cheaper but can drop events. Log writes only: misses the snooping case.

• How to build a clinic records app
• Example prompt for a clinic records app
• Clinic records app security checklist
• Clinic records app scaling checklist
• Often combined: booking system
• Often combined: SaaS dashboard
• All app types