CONFIDENTIAL · ArrAI internal · MedR client review · not for distribution outside ArrAI
MedR · Knowledge Transfer · Deck 2 of 3

User Journeys

Every role the system recognises, and the exact path each one walks from first contact to a completed referral — screen by screen, endpoint by endpoint, with the email fired at each step and the point where the path currently breaks.

6 roles 16 screens 96 endpoints Verified on code + walked on the live demo

00Who the system knows about

Roles are Django groups. There is no separate "specialist" role — direction is a property of the referral row, not of the person. Any verified practitioner can both send and receive.

RoleHow the system identifies themCan doCannot do
Visitor
unauthenticated
No token in localStorage Landing and policy pages, request a demo, register, check email availability, list insurers, job roles and clinics, geocode a postcode Everything else — every other view requires a verified practitioner or delegate
Practitioner
Clinician group
Clinician group and UserProfile.isVerified The whole product: search, refer, accept, reject, book, mark DNA, patients, analytics, practice management, delegates, settings Admin endpoints
Delegate
acting for a practitioner
Delegate group plus a verified DelegateUserLink to exactly one practitioner Nearly everything the practitioner can, operating directly on their data — the backend substitutes the practitioner's profile for every query Manage other delegates, edit or delete a referral, all admin routes
Patient A Patient row created by a practitioner. No account, no login, no FK to a user. Receive transactional email only, and only if primaryEmail is set Log in. There is no patient portal and no patient-facing screen anywhere
MedR staff
Staff group
Staff group; created by a management command or the admin-user endpoint Five staff API endpoints, plus the full Django admin at /medr/ In practice, use the in-app Admin screen for anything real — it is not wired to the API
Operations Operations group; authenticates by an X-Custom-Token header rather than Knox Nothing today The permission class exists but is applied to no view. The machinery is built and unattached
The delegate permission model is built but not enforced

DelegateUserLink carries five permission booleans — view, create and manage referrals, manage insurance, manage practices. They are stored, surfaced in the API, and toggled by switches in the UI, but no view or service ever reads them. On creation the backend hard-codes three to true and ignores the other two, discarding whatever the form submitted. A delegate's real permissions are therefore whatever the endpoint-level permission classes allow, identically for every delegate.

01Visitor becomes a verified practitioner

Visitor→ Practitioner
01
Lands on the marketing site
Hero, "Find / Refer / Track", demo cards, testimonials.
LandingPage.tsx
02
Registers
Two tabs: name, email, password — then specialities and registration number.
POST /register/User created inactive
03
Receives verify email
Link carries a user hash, time hash and code.
Template 8075893 — real
04
Clicks the link
Modal opens over the landing page and verifies automatically.
POST /register/verify-email/…This IS the verification
05
Logs in
Knox token issued; response flags that the profile is incomplete.
POST /login/
06
Forced to add a clinic
Lands on Practice Management with a blocking modal. Every other nav item is disabled.
POST /clinician-role-profile/create/
07
Sets accepted insurers
Toggles each insurer. Now discoverable in search.
POST /user/insurance-agreements/toggle/
Nobody approves a practitioner. Clicking the email link is the entire check.

set_verified_clinician() has exactly one caller — inside email verification — and zero test callers. It sets isVerified = True and moves the user into the Clinician group in one step. There is no review queue, no approval endpoint, no second actor. The registration number is captured as free text and never validated against any register.

The API nonetheless returns "Email successfully verified, please wait for the MedR team to review your account." The account is already live and fully privileged when that message is shown.

Consequence: email is on the critical path to every new account

Because the only route to isVerified = True runs through the emailed link, and no email currently leaves the building, no new practitioner can onboard on a production-mode deployment until the email pipeline works. The same applies to password reset and to every delegate invitation. This is why the email work is not a notifications nicety — it gates registration.

02Referrer sends a referral

PractitionerReferrer
01
Dashboard
Five cards: overview, pending, top clinicians, top specialties, favourites.
5 dashboard endpoints
02
Find a practitioner
Filter by speciality, insurer, clinic and postcode. Results sorted by real distance, on a map or a list.
GET /clinicians/list/
03
Open a profile
Detail modal; can mark as a favourite.
GET /clinician/<id>/
04
Pick or add the patient
Debounced search, or create a new patient record with consent capture.
POST /patient/create/
05
Clinical details
History, reason for referral, urgency — and a clinical-letter upload.
The upload is discarded
06
Send
Referral created as PENDING; timeline event and in-app notifications written.
POST /referrals/create/3 emails queued
07
Track it
Sent tab, summary tiles, filters, sortable table, detail view with a timeline.
Read-only — no actions
The clinical letter never leaves the browser

The referral form renders a file input labelled "Upload PDF or Word document (Max 10MB)" and stores the file in component state. The create payload never includes it, the serializer has no file field, and there is no attachment model on Referral at all. The landing page advertises "Attach referral letter with one click." This is the largest single gap between what the product promises and what it does.

03Target practitioner works the referral

PractitionerTarget
01
Notified
In-app bell fires reliably. The email does not.
Template 5 — placeholderEmail misaddressed
02
Received tab
Same table as Sent, filtered the other way.
POST /referrals/table/list/
03
Accept or reject
Guarded: must be the target and still hold the speciality.
POST /referrals/accept|reject/<id>/
04
Book the appointment
Marks the referral completed.
POST /referrals/book/<id>/
05
Or mark did-not-attend
Reversible — booked and DNA flip both ways.
POST /referrals/dna/<id>/
06
Referrer sees the change
Status updates on their Sent tab plus an in-app notification.
No rejection reason field exists

04Delegate is invited and acts for a practitioner

DelegatePractice staff
01
Practitioner adds them
Name and email, from Practice Management.
POST /user/delegate/create/
02
Invitation email
Names the inviting practitioner.
Template 1 — placeholderNo real template exists
03
Completes profile
Confirms their name and sets a password in a modal over the landing page.
POST /verify-delegate/
04
Logs in
Profile completeness is computed from the linked practitioner's clinics.
POST /login/
05
Works the practitioner's queue
Every screen shows the practitioner's data. Can create referrals and drive all four transitions.
One delegate → one practitioner only

Note: a delegate can accept, reject, book and mark DNA on the practitioner's behalf — those four transitions inherit the default permission class. Only edit and delete of a referral are practitioner-only. Worth confirming that is the intended clinical governance model.

05Patient

The patient is a record, not a user

There is no patient account, no login, no portal and no patient-facing screen. A patient exists as a row created by a practitioner, carrying name, date of birth, sex, contact details, address, insurance policy or self-payer flag, and a consent checkbox with a timestamp.

Their entire experience of MedR is up to five emails over a referral's life — created, accepted, rejected, booked, did-not-attend — and only if primaryEmail was filled in. Those five templates are correctly addressed, but all five are placeholders, none carries a link back into the app, and all five arrive under the subject line "You have been referred by …" regardless of what actually happened.

06MedR staff

MedR staffAdmin
01
Logs in normally
Same modal as everyone else.
POST /login/
02
Lands on Find Clinician
Not the dashboard, not Admin. Sidebar shows only two items.
On first login this misroutes — see below
03
Opens the Admin screen
Tabs for users, clinics and practice profiles.
100% hardcoded sample data
04
Real work happens in Django admin
The only working levers: flip verification, change groups, read the audit log.
/medr/
A complete admin API exists with no working screen in front of it

The backend serves seven staff endpoints — list user profiles, list practitioner profiles, list and verify insurers, create an admin user, list patients, list referrals. The frontend Admin page calls none of them. It renders three hardcoded arrays and its add, edit and delete controls persist nothing. An administrator using that screen is looking at invented users, clinics and practices.

Admins land on the wrong page the first time they log in

The routing decision reads the admin flag from a value captured before login wrote it, so the very first login sends an administrator to the dashboard instead of Find Clinician. It corrects itself on any refresh. Cosmetic, but it is the sort of thing that gets reported as "the admin login is broken".

07Where a user lands, from every entry point

Asked explicitly, so stated exactly. Navigation is a single React state value, not a URL — so "where you land" is decided entirely by one initialiser plus one switch statement.

Entry pointFirst screenWhat is on top of it
Fresh visit, no sessionLanding pageNo sidebar, no header chrome. Cookie consent banner.
Verification link from the sign-up emailLanding pageVerification modal, auto-runs, then offers "Continue to Login"
Delegate invitation linkLanding pageComplete-profile modal — confirm name, set password
Password reset linkLanding pageForgot-password modal in set-new-password mode
Login — practitioner, profile completeDashboard—
Login — practitioner, no clinic yetPractice ManagementBlocking modal plus an amber banner; every other nav item disabled
Login — delegateDashboardFalls back to Practice Management only if the linked practitioner has no clinic
Login — MedR staffFind ClinicianIntended; misroutes to Dashboard on the very first login
Refresh, anywhere, while signed inDashboard (or Find Clinician for staff)Whatever screen you were on is lost, along with filters, tabs, drafts and open modals
Any 401 from the APILanding pageToken dropped, hard redirect to /
There is no router, and that has a direct cost to the email work

The app has no routing library. Navigation is one useState value switched over in a single component, and the address bar reads / on every screen. Nothing ever pushes a history entry, and a mount-time effect actively strips query parameters back out of the URL.

Consequences: the browser back button leaves the application entirely; a refresh returns you to the dashboard; nothing — no referral, no patient, no practitioner profile — can be bookmarked or shared.

The part that matters for delivery: the app recognises exactly four ?type= values — login, verify clinician email, verify delegate email, password reset. It does not recognise type=referral, which is precisely what the referral emails are built to send. So even once templates exist and sending is switched on, "view this referral" links will land the user on a bare dashboard. Deep-linking has to be built before referral emails are worth sending.

The routing findings were confirmed by walking the live demo, not just by reading code

Signed in on demo.medr.co.uk and tested each behaviour directly. The URL stays / on every screen. Browser back leaves the application entirely to a blank page; forward returns but lands on the dashboard. Reload keeps the session but bounces to the dashboard rather than staying put. A hand-typed deep path keeps the path in the address bar and renders the dashboard anyway. So the ceiling for any emailed link is "the dashboard" — never the referral it is about.

Two corrections to the demo credentials in our brief, worth passing back to Anshul: the documented password is wrong, and one of the two documented logins does not authenticate at all. The login endpoint also takes the email in a field named username, not email. Specific credentials deliberately omitted from this hosted copy — they are in the local version.

08Dead ends a user can reach today

Paths that look complete in the interface and do nothing. Separated from the items the client has already declared out of scope.

Journey stepWhat happensImpact
Clinical letter uploadFile is selected and held in state; the create payload omits it. No attachment model exists.critical advertised feature
Edit a referralThe screen relabels itself "Edit Referral" but submits to the create endpoint, producing a duplicate. The update endpoint has no caller in the frontend.critical data integrity
Admin screenHardcoded sample rows; controls persist nothing.critical
Register from a policy pageThe success callback is empty, so a completed registration leaves the user on the page, not signed in and not redirected.high
Successful referral denialShows a red error toast on the success path.medium looks like a failure
Delegate opens Practice ManagementThe Staff & Delegates tab renders for them, then its data call returns 403.medium
Delegate permission switchesPersist and show a success toast; nothing reads them.medium false assurance
"Wait for the MedR team to review your account"No review exists. The account is already live.medium misleading
Analytics exportThe endpoint returns an empty object. Mitigated — the button is commented out.low
Request a demoFires a Slack message and persists nothing. A missed enquiry is unrecoverable.medium commercial
Find peers in your own specialityThe speciality filter excludes every role the searcher already holds — a cardiologist cannot filter for cardiologists.low confirm intent
Insurance toggleApplies to every one of the practitioner's clinics at once; the read shows only the first. Per-clinic differences cannot be expressed.low confirm intent

Already known and deliberately out of scope

Invite a practitioner

Sends an email, records no invitation. Completing the flow belongs to a later build.

Billing

A deliberate placeholder behind a blur overlay. The backend returns fixed values; there is no subscription model.

Auth improvements

Social login and magic links are explicitly excluded from the launch scope.