The architecture behind a production patient-intake agent for medical practices — the four layers, where the first version broke, and the decisions that made it compliant without making it useless. Public excerpt; full teardown with the implementation detail lives in the Builder library.
This is the architecture behind an intake system that cut a practice's front-desk intake workload by 60%. Not a diagram from a pitch deck — the shape of the thing that actually runs.
Layer 1 — Capture. A mobile-first form the patient completes on their own device. The unglamorous decision that matters most: every field is typed and constrained at capture. Free-text is a last resort, because every free-text field is a manual review you've deferred, not avoided.
Layer 2 — Validation. Member IDs checked against format rules per payer. Dates cross-checked for internal consistency. Document photos verified as readable before the patient leaves the flow. The principle: the patient is the cheapest validator you will ever have — while they're present and motivated, a re-prompt costs seconds. The same fix at the front desk three days later costs a phone-tag cycle.
Layer 3 — Routing. Validated records write to the PM system and CRM through vendor APIs. Exceptions — the genuinely ambiguous cases — route to staff with full context attached. The ratio you're tuning for: high-nineties percent straight-through, low single digits to humans. If your exception rate is 20%, your validation layer is underbuilt.
Layer 4 — Compliance envelope. BAAs with every vendor in the path, encryption both directions, role-scoped access, audit logs on every pipeline run. Built first, not retrofitted — because retrofitting compliance means rebuilding layers 1–3.
Two failures worth having in advance:
Webhook retries created duplicate records. The PM system's API accepted a write, timed out on the response, and our retry created the patient twice. The fix is idempotency keys on every write — obvious in hindsight, absent from every tutorial. If your integration doesn't have them, you have this bug and haven't noticed yet.
Insurance card photos failed silently at the worst moment. Patients uploaded glare-heavy photos that passed a naive "file exists" check and failed at human review days later — recreating exactly the phone-tag loop the system existed to kill. The fix moved readability checking into the capture flow (Layer 2), re-prompting while the patient still had the card in hand.
The full teardown — the exception-routing decision tree, the payer-format validation table, the idempotency implementation, and the deployment checklist we now run on every intake build — lives in the Builder library.
Implementation detail, checklists, and the parts we'd rather not have public — for members.
Unlock with Builder