Smart + Compliant Referral System
Matching, live state, and records that exist before their owner does.
Both of these look like UI features and neither is. The referral system spans three user types with genuinely different permissions and flows, and referral state has to persist across interactions where the two parties see different things and act at different times.
Matching is a two-stage problem. Multi-attribute search retrieves candidates against the hard constraints, and a deployed model scores what survives to produce the final ranking and recommendations the user acts on. I kept the stages separate rather than folding ranking into the query or letting the model handle retrieval. Search is where correctness lives, since a provider who fails a constraint should never surface at any rank, and the model is where preference lives. Separating them means the model can be retrained or swapped without touching query semantics.
Referral state also has to be live. Providers work their referrals as a queue, and the state changes are driven by the other party's actions rather than their own, so I implemented a WebSocket layer that pushes state to providers instead of having clients poll for it. Polling forces a choice between wasted requests and a stale queue, and a stale queue means a provider working a referral someone else already handled.
Profile claiming is the stranger half. Unclaimed profiles exist as real records before their subject ever authenticates, then get claimed through identity verification, with SSN validation for healthcare seekers. A mistake there hands one patient's record to another person. I built it on an MVP architecture with explicit interface and implementation layers separating state, view visibility, and service-side verification, rather than letting visibility rules double as authorization. Hiding a record and refusing to serve it are different guarantees, and only one of them survives a crafted request.
In healthcare, identity resolution is a security boundary wearing a UX costume.