How the MedR referral platform is actually built, as read from the code on dev-v-2-0. Every claim on this page is traceable to a file and line. Where the written documentation and the code disagree, the code is what is shown here.
MedR is a UK private-practice referral network. A verified practitioner searches a directory of other practitioners by speciality, insurer and geographic distance, attaches a patient record and clinical history, and sends a referral. The receiving practitioner accepts, rejects, books, or marks did-not-attend. Both sides — plus optional delegate staff acting on a practitioner's behalf — are notified in-app and by email. It is a Django REST API with a React single-page app in front, run as four Docker containers on a single EC2 instance per environment.
Endpoint count from the Endpoint enum registries in users/endpoints.py, referral/endpoints.py, system/endpoints.py. Test result from an executed run of the suite: 539 passed, 1 skipped, 540 collected.
The React frontend described in the repository's own CLAUDE.md — three npm workspaces named medr-components, medr-logic-lib, medr-ui, with an API client generated from the OpenAPI schema — no longer exists. It was deleted on 22 April 2026 in commit ad09a47b ("DELET OLD FRONTEND DIRS", 984 files, 139,192 deletions), together with the entire Cypress end-to-end suite.
The live frontend is _design_frontend_export/MedR Clinical Dashboard 12 03 2026/ — an export from a design tool, first committed 13 March 2026, and developed in place ever since (192 commits). Dockerfile.frontend builds the production image directly from that folder. This is not a mock-up sitting beside the real app; it is the app.
Two fully separate environments on the client's AWS account (381491949502, eu-west-2). Deliberately plain: EC2 and Docker Compose, no Lambda, no edge, no managed container service.
docker-compose.demo.yml, nginx/conf.d/*, scripts/constants.sh, and the client's recorded infrastructure walkthrough of 31 Aug 2026.In nginx/conf.d/demo/default.conf the basic-auth directives are declared at server level on line 60, after the location blocks. /api/ (line 41) and /medr/ — the Django admin login — (line 51) both carry auth_basic off. Only the SPA shell at / is gated.
Verified live, and worse than it reads: the demo backend also runs with DEBUG = True, so a 404 through that unauthenticated path returns Django's debug page listing all 105 URL patterns.
nginx/conf.d/medr/default.conf:55 reads server_name medr.co.uk, www.medr.co.uk;. nginx separates server names with spaces, not commas, so the first token becomes the literal string medr.co.uk, and matches nothing — the apex domain would fall through to the default server block, which serves the API rather than the app. Worth a live check rather than a code change.
| Container | Image / build | Ports | Present in dev | Present in demo/prod | Notes |
|---|---|---|---|---|---|
| nginx | Dockerfile.nginx | 80, 443 | yes | yes (ECR :latest) | Config chosen by CONFIG_ENV. Nothing in the repo listens on 443. |
| frontend | Dockerfile.frontend | 3000 | yes | yes (ECR :latest) | Builds the design export; npm ci --legacy-peer-deps. |
| backend | Dockerfile.backend | 8000 | yes | yes (ECR :latest) | Migrations run in the entrypoint on start. |
| redis | redis:7-alpine | — | yes | yes | Broker only when ENV_TYPE is STAGING or PRODUCTION. |
| postgres | postgres:16-alpine | — | yes | absent | Demo/prod DB comes from the server's own .env. |
| celery worker | — | — | commented out | commented out | Command reads -A base; the app is named backend. |
| celery beat | — | — | commented out | commented out | Needs django_celery_beat, which is not a dependency. Nothing schedules periodic work, so beat is not required. |
Three Django apps and a consistent four-layer call path. Understanding this one path explains most of the codebase, because every referral action follows it.
referral/services/full_referral.py → referral/models/referral/manager.py → referral/models/referral/model.py.Identity, practitioners, delegates, reference data
UserProfile · ClinicianRoleProfile · DelegateUserLink · Address · ClinicCenter · ClinicianContact · FavouriteClinician · InsuranceAgreement · JobRole · NotificationsSettings · VerificationCode · EventNotification
57 migrations
The clinical workflow
Patient · Referral · ReferralEvent. Also holds the referral service layer and the whole analytics query surface.
28 migrations
Cross-cutting platform concerns
AuditLog · HelpRequest · EmailSent. Plus the Mailjet service, the Slack service, and the two Celery tasks.
9 migrations
MedrBaseAPIView sets permission_classes = [IsVerifiedClinicianOrDelegate]. Since nearly every view inherits it and few override, that — not the project-wide IsAuthenticated — is the real gate. A user must be authenticated, have a UserProfile, be isVerified, and sit in the Clinician or Delegate group.
get_clinician_user_profile() returns the delegate's own profile for audit attribution, but substitutes the linked practitioner's profile for every data query. So a delegate reads and writes the practitioner's referrals and patients without any special-casing downstream. The link is one delegate to exactly one practitioner.
users and referral extends a shared BaseModel providing update_from_dict() and a recursive __repr__. A referral points at ClinicianRoleProfiles, not user profiles — it targets a practitioner at a specific practice.Five stored statuses. Transitions are guarded in the model: the caller must be the target practitioner and must still hold the referral's speciality, or the action raises.
ReferralEvent, an EventNotification per recipient, one Slack message, and three Mailjet tasks.There is exactly one outbound email mechanism. Django's own mail framework is never used. Every email event builds a dataclass, hands it to a Celery task, and the task calls Mailjet with a template ID and a variables dictionary. The email bodies themselves live in Mailjet, not in this repository.
All ten *ReferrerInput and *TargetInput classes in backend/system/services/email/emails.py contain the identical line self.receivers = EmailUserInfo(Name=self.patient_name, Email=self.patient_email) inside get_email_variables() — at lines 407, 440, 509, 542, 611, 644, 713, 746, 815 and 848. The caller in full_referral.py correctly passes the clinician's own recipient_email; the value is then discarded.
Net effect if sending were switched on as-is: the patient receives three differently-templated emails per referral event, each carrying the other parties' names, roles, email addresses and phone numbers. The practitioners receive nothing. Independently re-derived from source and confirmed.
| Email family | Dispatch site | Template ID | State |
|---|---|---|---|
| Clinician verify email | users/models/userprofile/manager.py | 8075893 | real |
| Clinician add-clinic prompt | users/models/userprofile/manager.py | 8077177 | real |
| Password reset request | users/models/userprofile/manager.py | 8077202 | real |
| Password updated | users/models/userprofile/manager.py | 8077228 | real |
| Invite a practitioner | users/views/views_crp.py | 8114519 | real |
| Help request | system/models/helprequest.py | 8114565 | real |
| Delegate verify email | users/models/delegateuserlink/manager.py | 1 | placeholder |
| Delegate registration complete | users/models/delegateuserlink/manager.py | 2 | placeholder |
| Staff error notification | system/views/views_requests.py | 3 | placeholder |
| Referral created — referrer / target / patient | referral/services/full_referral.py | 4, 5, 6 | placeholder |
| Referral accepted — referrer / target / patient | referral/services/full_referral.py | 7, 8, 9 | placeholder |
| Referral rejected — referrer / target / patient | referral/services/full_referral.py | 10, 11, 12 | placeholder |
| Referral booked — referrer / target / patient | referral/services/full_referral.py | 13, 14, 15 | placeholder |
| Did not attend — referrer / target / patient | referral/services/full_referral.py | 16, 17, 18 | placeholder |
24 members in MedrEmailTemplates. 6 real, 18 placeholder. Counted mechanically and cross-checked against EMAILS_KEY, which the service asserts is the same length at start-up.
All ten practitioner dispatch sites pass host="", producing the bare fragment ?type=referral&referral_id=42 instead of a URL. The five patient templates carry no link variable at all. An EMAIL_LINK_BASE_DOMAIN variable exists in the env files and is read by no Python code.
All fifteen read You have been referred by {referrer_name} — including the rejection, the booking confirmation and the did-not-attend notice.
The EmailSent model, its migration and a full status-transition manager all exist, but no code ever creates a row. Mailjet's returned message IDs are discarded, there is no inbound webhook, and the de-duplication guard that reads this table is therefore a permanent no-op.
This matters for the handover: anyone onboarding from the docs alone will build a wrong mental model. Every row below was checked against the files.
| The documentation says | The code says | Where |
|---|---|---|
Frontend is frontend/, three npm workspaces, API client generated from OpenAPI | Deleted in April 2026. The frontend is a design-tool export with a hand-written axios client and no codegen script. | commit ad09a47b; Dockerfile.frontend |
| Django 4.2 | Django 5.2.3 | backend/pyproject.toml |
| Backend lint is ruff | black. ruff is not a dependency at all. | pyproject.toml poe tasks |
| CI stages are fetch-secrets → lint → type-check → test | lint → type-check → test → build. No fetch-secrets stage. | .gitlab-ci.yml |
A deploy/ directory holds compose files and certs | Does not exist. Compose files sit at the repo root; deploy scripts under scripts/deploy/. | repo root |
scripts/build_docker_containers.sh, scripts/deploy_application.sh | Real names are build-docker-containers.sh and deploy-demo-version.sh. There is no deploy_application.sh. | scripts/ |
Vite dev server proxies /api to the backend | No proxy is configured. The SPA calls the API base URL directly. | vite.config.ts |
poetry poe serve starts an HTTPS dev server | Plain runserver over HTTP on port 8000. | pyproject.toml |